@estiva-app/ui 0.25.0 → 0.27.0

package/src/MenuItem.stories.tsx

@@ -1,135 +1,151 @@
-import type { Meta, StoryObj } from '@storybook/react-vite'
-import { IconCopy, IconPin, IconTrash } from '@tabler/icons-react'
-import { Avatar } from './Avatar'
-import { useRef, useState } from 'react'
-import { Button } from './Button'
-import { Divider } from './Divider'
-import { EnterHint, Menu, MenuItem, MenuPanel, MenuSub } from './Menu'
-
-/**
- * One row of a menu. Anatomy: `leading` (a 16px icon or an Avatar) · label
- * with an optional `description` line · one thing at the right edge —
- * `trailing` (any hint), else `shortcut` (the kbd chip), else the `submenu`
- * chevron. Stories sit on a `MenuPanel` — the menu's surface, drawn without
- * its behaviour — so the row is seen where it lives. A live menu portals and
- * places itself, so it cannot stand in the page (Katerina, D25); **Menu →
- * FromATrigger** is where the keyboard and the placement are.
- */
-const meta = {
-  title: 'Overlays/MenuItem',
-  component: MenuItem,
-  decorators: [
-    (Story) => (
-      <div className="flex min-h-[120px] w-full items-center justify-center">
-        <MenuPanel className="w-72">
-          <Story />
-        </MenuPanel>
-      </div>
-    ),
-  ],
-  args: { label: 'Rename', onClick: () => {} },
-  argTypes: {
-    onClick: { control: false },
-    leading: { control: false },
-    trailing: { control: false },
-  },
-} satisfies Meta<typeof MenuItem>
-
-export default meta
-type Story = StoryObj<typeof meta>
-
-export const Default: Story = {}
-
-export const WithAnIcon: Story = {
-  args: { label: 'Pin', leading: <IconPin size={16} stroke={1.5} className="text-text-secondary" /> },
-}
-
-export const WithAShortcut: Story = {
-  args: { label: 'Copy link', leading: <IconCopy size={16} stroke={1.5} className="text-text-secondary" />, shortcut: 'Ctrl+C' },
-}
-
-/** The row opens another menu. */
-export const Submenu: Story = {
-  args: { label: 'Move to…', submenu: true },
-}
-
-/**
- * The submenu, working. The story above draws the row at rest — the chevron is
- * the whole affordance — but a row that opens another menu can only be tried
- * inside a real one, so here is one.
- *
- * Hover **Move to…**, or arrow onto it and press →. The panel opens beside the
- * row, flips to the other side at a screen edge, and stays open while you
- * cross the diagonal into it.
- *
- * From the keyboard: → opens it and leaves the highlight on the row, ↓ steps
- * into it, and ← closes it and puts the highlight back on the row. Measured in
- * that order — → then ← alone does nothing, because focus has not entered yet.
- */
-export const SubmenuLive: Story = {
-  parameters: { controls: { disable: true } },
-  decorators: [(Story) => <Story />],
-  render: () => (
-    <div className="flex min-h-[220px] w-full items-start justify-center pt-4">
-      <Menu trigger={<Button variant="outlined">Open the menu</Button>}>
-        <MenuItem label="Rename" onClick={() => {}} />
-        <MenuSub label="Move to…">
-          <MenuItem label="Item one" onClick={() => {}} />
-          <MenuItem label="Item two" onClick={() => {}} />
-          <MenuItem label="Item three" onClick={() => {}} />
-        </MenuSub>
-        <Divider className="my-1" />
-        <MenuItem label="Delete" destructive onClick={() => {}} />
-      </Menu>
-    </div>
-  ),
-}
-
-/** A person as a row — the face, the name, a second line, a trailing hint. Peek's mention rows. */
-export const APerson: Story = {
-  args: {
-    label: 'Ana Duarte',
-    description: 'Product designer',
-    leading: <Avatar name="Ana Duarte" size={32} />,
-    trailing: <EnterHint />,
-  },
-}
-
-/** The submenu's chosen value. */
-export const Selected: Story = {
-  args: { label: 'Item one', selected: true },
-}
-
-export const Destructive: Story = {
-  args: { label: 'Delete', destructive: true, leading: <IconTrash size={16} stroke={1.5} className="text-error-default" /> },
-}
-
-/** Every shape on one canvas. */
-export const AllVariants: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <>
-      <MenuItem label="Bare" onClick={() => {}} />
-      <MenuItem label="With an icon" leading={<IconPin size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
-      <MenuItem label="With a shortcut" shortcut="Ctrl+K" onClick={() => {}} />
-      <MenuItem label="Icon and shortcut" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="Ctrl+C" onClick={() => {}} />
-      <MenuItem label="Opens another menu" submenu onClick={() => {}} />
-      <MenuItem label="Ana Duarte" description="Product designer" leading={<Avatar name="Ana Duarte" size={32} />} trailing={<EnterHint />} onClick={() => {}} />
-      <MenuItem label="The chosen value" selected onClick={() => {}} />
-      <MenuItem label="Destructive" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
-      <MenuItem label="A very long label that runs out of room and truncates" onClick={() => {}} />
-    </>
-  ),
-}
-
-/** The tall picker row — 48px, px-3, a 32px face or tile, the description line, and the hint while highlighted. TopicMenu, MentionMenu, the files menu and the launcher all draw this row. */
-export const Tall: Story = {
-  args: {
-    size: 'tall',
-    label: 'Ana Duarte',
-    description: 'Product designer',
-    leading: <Avatar name="Ana Duarte" size={32} />,
-    selected: true,
-    trailing: <EnterHint />,
-  },
-}
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconCopy, IconHash, IconPin, IconTrash } from '@tabler/icons-react'
+import { Avatar } from './Avatar'
+import { useRef, useState } from 'react'
+import { Button } from './Button'
+import { Divider } from './Divider'
+import { EnterHint, Menu, MenuItem, MenuPanel, MenuSub } from './Menu'
+
+/**
+ * One row of a menu. Anatomy: `leading` (a 16px icon or an Avatar) · label
+ * with an optional `description` line · one thing at the right edge —
+ * `trailing` (any hint), else `shortcut` (the kbd chip), else the `submenu`
+ * chevron. Stories sit on a `MenuPanel` — the menu's surface, drawn without
+ * its behaviour — so the row is seen where it lives. A live menu portals and
+ * places itself, so it cannot stand in the page (Katerina, D25); **Menu →
+ * FromATrigger** is where the keyboard and the placement are.
+ */
+const meta = {
+  title: 'Overlays/MenuItem',
+  component: MenuItem,
+  decorators: [
+    (Story) => (
+      <div className="flex min-h-[120px] w-full items-center justify-center">
+        <MenuPanel className="w-72">
+          <Story />
+        </MenuPanel>
+      </div>
+    ),
+  ],
+  args: { label: 'Rename', onClick: () => {} },
+  argTypes: {
+    onClick: { control: false },
+    leading: { control: false },
+    trailing: { control: false },
+  },
+} satisfies Meta<typeof MenuItem>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+export const WithAnIcon: Story = {
+  args: { label: 'Pin', leading: <IconPin size={16} stroke={1.5} className="text-text-secondary" /> },
+}
+
+export const WithAShortcut: Story = {
+  args: { label: 'Copy link', leading: <IconCopy size={16} stroke={1.5} className="text-text-secondary" />, shortcut: 'Ctrl+C' },
+}
+
+/** The row opens another menu. */
+export const Submenu: Story = {
+  args: { label: 'Move to…', submenu: true },
+}
+
+/**
+ * The submenu, working. The story above draws the row at rest — the chevron is
+ * the whole affordance — but a row that opens another menu can only be tried
+ * inside a real one, so here is one.
+ *
+ * Hover **Move to…**, or arrow onto it and press →. The panel opens beside the
+ * row, flips to the other side at a screen edge, and stays open while you
+ * cross the diagonal into it.
+ *
+ * From the keyboard: → opens it and leaves the highlight on the row, ↓ steps
+ * into it, and ← closes it and puts the highlight back on the row. Measured in
+ * that order — → then ← alone does nothing, because focus has not entered yet.
+ */
+export const SubmenuLive: Story = {
+  parameters: { controls: { disable: true } },
+  decorators: [(Story) => <Story />],
+  render: () => (
+    <div className="flex min-h-[220px] w-full items-start justify-center pt-4">
+      <Menu trigger={<Button variant="outlined">Open the menu</Button>}>
+        <MenuItem label="Rename" onClick={() => {}} />
+        <MenuSub label="Move to…">
+          <MenuItem label="Item one" onClick={() => {}} />
+          <MenuItem label="Item two" onClick={() => {}} />
+          <MenuItem label="Item three" onClick={() => {}} />
+        </MenuSub>
+        <Divider className="my-1" />
+        <MenuItem label="Delete" destructive onClick={() => {}} />
+      </Menu>
+    </div>
+  ),
+}
+
+/** A person as a row — the face, the name, a second line, a trailing hint. Peek's mention rows. */
+export const APerson: Story = {
+  args: {
+    label: 'Ana Duarte',
+    description: 'Product designer',
+    leading: <Avatar name="Ana Duarte" size={32} />,
+    trailing: <EnterHint />,
+  },
+}
+
+/** The submenu's chosen value. */
+export const Selected: Story = {
+  args: { label: 'Item one', selected: true },
+}
+
+export const Destructive: Story = {
+  args: { label: 'Delete', destructive: true, leading: <IconTrash size={16} stroke={1.5} className="text-error-default" /> },
+}
+
+/** Every shape on one canvas. */
+export const AllVariants: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <>
+      <MenuItem label="Bare" onClick={() => {}} />
+      <MenuItem label="With an icon" leading={<IconPin size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
+      <MenuItem label="With a shortcut" shortcut="Ctrl+K" onClick={() => {}} />
+      <MenuItem label="Icon and shortcut" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="Ctrl+C" onClick={() => {}} />
+      <MenuItem label="Opens another menu" submenu onClick={() => {}} />
+      <MenuItem label="Ana Duarte" description="Product designer" leading={<Avatar name="Ana Duarte" size={32} />} trailing={<EnterHint />} onClick={() => {}} />
+      <MenuItem label="The chosen value" selected onClick={() => {}} />
+      <MenuItem label="Destructive" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
+      <MenuItem label="A very long label that runs out of room and truncates" onClick={() => {}} />
+    </>
+  ),
+}
+
+/** The tall picker row — 48px, px-3, a 32px face or tile, the description line, and the hint while highlighted. TopicMenu, MentionMenu, the files menu and the launcher all draw this row. */
+export const Tall: Story = {
+  args: {
+    size: 'tall',
+    label: 'Ana Duarte',
+    description: 'Product designer',
+    leading: <Avatar name="Ana Duarte" size={32} />,
+    selected: true,
+    // `hint`, not `trailing`: shown only while the row is highlighted, on the fill's own timing.
+    hint: <EnterHint />,
+  },
+}
+
+/** A topic in the picker: `EnterHint`'s `target` says what Enter gives you, after the key. Hover another row and back to see the hint follow the highlight. */
+export const ATopic: Story = {
+  args: {
+    size: 'tall',
+    label: 'design',
+    description: '12 members',
+    leading: <IconHash size={16} stroke={1.5} className="text-text-secondary" />,
+    selected: true,
+    hint: <EnterHint target="#design" />,
+  },
+  // axe color-contrast is off here until PLAN.md stage 0.10 is ruled: the
+  // target is muted text, 3.05:1 on a highlighted row in signal (AA 4.5:1).
+  parameters: { a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } },
+}

package/src/Person.stories.tsx

@@ -13,6 +13,13 @@ type Story = StoryObj<typeof meta>
 
 export const Named: Story = {}
 
+/** With their picture — here an inline SVG, as Avatar's own story uses, so the story needs nothing from anywhere. */
+export const WithPicture: Story = {
+  args: {
+    picture: 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><rect width="10" height="10" fill="%2346c08a"/><circle cx="5" cy="4" r="2" fill="%23fff"/></svg>',
+  },
+}
+
 /** Nobody has published a name: the silhouette and the em dash, muted — the same mark a property with no value uses. */
 export const Unnamed: Story = {
   args: { name: undefined },

package/src/PersonTrigger.stories.tsx

@@ -14,6 +14,13 @@ type Story = StoryObj<typeof meta>
 /** The row shape — face · name · chevron on a 32px button, Ship's top bar. */
 export const Row: Story = {}
 
+/** The row with the person's picture — an inline SVG, as Avatar's own story uses. */
+export const RowWithPicture: Story = {
+  args: {
+    picture: 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><rect width="10" height="10" fill="%2346c08a"/><circle cx="5" cy="4" r="2" fill="%23fff"/></svg>',
+  },
+}
+
 /** While what it opens is open, the row holds its hover fill. */
 export const RowOpen: Story = {
   args: { open: true },

package/src/SectionHeader.stories.tsx

@@ -17,6 +17,11 @@ type Story = StoryObj<typeof meta>
 
 export const Plain: Story = {}
 
+/** `chevron`: the header of a section that folds. The title becomes the toggle, and the chevron turns with it. CollapsibleSection draws this for you. */
+export const Folding: Story = {
+  args: { chevron: true, isExpanded: true, onToggle: () => {} },
+}
+
 /** Actions beside the title, in the order given — revealed on hover or focus. */
 export const WithActions: Story = {
   args: {

package/src/eslint/no-rebuilt-behaviour.ts

@@ -190,7 +190,7 @@ export const OWNED_BEHAVIOURS: OwnedBehaviour[] = [
     id: 'portal',
     behaviour: 'Floats on top of the page',
     baseUi: ['Dialog', 'AlertDialog', 'Popover', 'Menu', 'Select', 'Combobox', 'Autocomplete', 'Tooltip', 'PreviewCard', 'Toast'],
-    owners: ['DialogShell', 'ConfirmDialog', 'CommandPalette', 'Popover', 'Menu', 'Select', 'ChipInput', 'Tooltip', 'PreviewCard', 'Toast'],
+    owners: ['DialogShell', 'ConfirmDialog', 'CommandPalette', 'Lightbox', 'Popover', 'Menu', 'Select', 'ChipInput', 'Tooltip', 'PreviewCard', 'Toast'],
     reads: 'createPortal, called, or imported and never called',
   },
   {
@@ -204,21 +204,21 @@ export const OWNED_BEHAVIOURS: OwnedBehaviour[] = [
     id: 'page-keys',
     behaviour: 'Takes its keys by itself',
     baseUi: ['Dialog', 'AlertDialog', 'Popover', 'Menu', 'Select', 'Combobox', 'Tooltip', 'PreviewCard', 'Toast'],
-    owners: ['DialogShell', 'Popover', 'Menu', 'Select', 'Tabs', 'Toolbar'],
+    owners: ['DialogShell', 'Lightbox', 'Popover', 'Menu', 'Select', 'Tabs', 'Toolbar'],
     reads: 'a keydown, keyup or keypress listener on window or document',
   },
   {
     id: 'focus',
     behaviour: 'Holds focus inside while open, and gives it back',
     baseUi: ['Dialog', 'AlertDialog', 'Popover', 'Menu', 'Select', 'Combobox'],
-    owners: ['DialogShell', 'CommandPalette'],
+    owners: ['DialogShell', 'CommandPalette', 'Lightbox'],
     reads: 'a focusin or focusout listener on window or document; the Tab key compared by hand',
   },
   {
     id: 'scroll-lock',
     behaviour: 'Stops the page behind it scrolling',
     baseUi: ['Dialog', 'AlertDialog'],
-    owners: ['DialogShell'],
+    owners: ['DialogShell', 'Lightbox'],
     reads: 'overflow written into the style of document.body or document.documentElement',
   },
   {

package/src/gates/app-checks.ts

@@ -45,7 +45,7 @@ export const APP_TICKET_TITLES: Record<string, string> = {
   'UIG-9': 'Lint rule — the className allow-list',
   'UIG-10': 'create-app — a command that makes a new Estiva app that runs',
   'UIG-13': "The registry widens to Peek's 115 and Ship's 74, with classification",
-  'UIG-19': 'Lock the contract in CI, and make the three Storybooks one search',
+  'UIG-19': 'Lock the contract in CI',
   'UIG-20': 'The Claude skill, reading the registry',
   'UIG-21': 'CLAUDE.md becomes an index, not a lecture',
   'UIG-22': 'Fingerprint — a hand-made header row',
@@ -190,7 +190,11 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: 'every part is described and sorted, and every file is accounted for', run: () => h.catalogue(at('.')) },
     ]),
     ticket('UIG-19', [
-      { what: 'the usage-page contract runs in CI', run: () => h.ci(/[\w:-]*contract[\w:-]*/) },
+      // The contract runs inside `estiva-ui check`, which the gate job already runs
+      // (UIG-13), so an app changes no script: it takes the package that has it.
+      { what: 'the installed package checks the usage-page contract and the story links', run: () => h.contains(at('node_modules/@estiva-app/ui/dist/registry/cli.js'), 'the usage-page contract', "the installed estiva-ui check runs the contract") },
+      { what: "CI's job gate runs it", run: () => h.ciJob('gate', 'registry:check') },
+      { what: 'the app keeps no copy of it in its own gates-checks.mjs', run: () => h.exists(at('scripts/gates-checks.mjs')) ? h.lacks(at('scripts/gates-checks.mjs'), '"When not"', 'the app checks no page sections itself') : h.PASS('the app has no gates-checks.mjs') },
     ]),
     ticket('UIG-20', [
       { what: 'a committed skill runs ui:find', run: () => (h.listFiles('.claude/skills', (n) => n === 'SKILL.md').some((f) => h.read(f).includes('ui:find')) ? h.PASS('a skill runs ui:find') : h.FAIL('no skill in .claude/skills runs ui:find')) },

package/src/gates/status.ts

@@ -73,6 +73,8 @@ export interface GateHelpers {
   share(files: string[], test: (file: string) => boolean, label: string): CheckResult
   /** Build the catalogue of the app in `appDir` (UIG-13): passes when every part is described and sorted. */
   catalogue(appDir: string): Promise<CheckResult>
+  /** Every reusable part keeps the usage-page contract (UIG-19): the package's one copy of it. */
+  contract(appDir: string): Promise<CheckResult>
 }
 
 export interface GateCheck {
@@ -178,6 +180,19 @@ export function helpers(ROOT: string): GateHelpers {
       }
     },
 
+    async contract(appDir) {
+      try {
+        const { buildAppRegistry, contractProblems, CONTRACT_KINDS } = await import('../registry/index')
+        const registry = buildAppRegistry({ root: abs(appDir) })
+        const problems = contractProblems(registry, abs(appDir))
+        const owed = registry.entries.filter((entry) => (CONTRACT_KINDS as readonly string[]).includes(entry.app?.class ?? '')).length
+        if (problems.length) return FAIL(`${problems.length} of ${owed}; the first: ${problems[0]}`)
+        return PASS(`all ${owed} reusable parts keep the usage-page contract and are drawn somewhere`)
+      } catch (error) {
+        return FAIL(String(error instanceof Error ? error.message : error).split('\n')[0])
+      }
+    },
+
     file(rel) {
       return exists(rel) ? PASS(`${rel} exists`) : FAIL(`${rel} does not exist`)
     },

package/src/index.ts

@@ -44,6 +44,7 @@ export {
   type InlineChipProps,
   type InlineChipTone,
 } from './InlineChip'
+export { Lightbox, type LightboxProps } from './Lightbox'
 export { Link, type LinkProps, type LinkVariant } from './Link'
 export { IconButton, type IconButtonProps, type IconButtonVariant } from './IconButton'
 export { Kbd, type KbdProps } from './Kbd'

package/src/registry/app.test.ts

@@ -540,11 +540,24 @@ describe.skipIf(!existsSync(cli))('estiva-ui in an app', () => {
   const run = (args: string[], cwd: string) => execFileSync(process.execPath, [cli, ...args], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
 
   it('check prints what it found, and fails on a part with no description', () => {
-    expect(run(['check', '--repo', 'fixture'], root)).toMatch(/^fixture: 17 parts in 15 files \(2 more hold none\)/)
     const bare = app({ 'src/One.tsx': 'export function One() {\n  return <i />\n}\n' })
     expect(() => run(['check'], bare)).toThrow(/One in src\/One\.tsx has no one-line description/)
   })
 
+  it('check fails a reusable part with no usage page, naming the page to write (UIG-19)', () => {
+    // The fixture's reusable parts have no pages: it was written before the contract ran in `check`.
+    let failed: { stdout?: string; stderr?: string } = {}
+    try {
+      run(['check', '--repo', 'fixture'], root)
+    } catch (error) {
+      failed = error as { stdout?: string; stderr?: string }
+    }
+    expect(failed.stdout).toMatch(/^fixture: 17 parts in 15 files \(2 more hold none\)/)
+    expect(failed.stderr).toContain('Timeline (reusable, src/components/Timeline.tsx) has no usage page: write src/components/Timeline.mdx')
+    const one = app({ 'src/One.tsx': '/** One, drawn once. */\nexport function One() {\n  return <i />\n}\n' })
+    expect(run(['check'], one)).toContain('usage pages: all 0 reusable parts keep the contract')
+  })
+
   it("find searches the app and the package, and never takes an app's own registry.json for the package's", () => {
     // What `estiva-ui build` leaves behind in an app, and git ignores.
     run(['build'], root)

package/src/registry/app.ts

@@ -678,7 +678,11 @@ export function buildAppRegistry({ root = process.cwd(), repo, packageRegistry,
   const storyOf = (p: Found) => {
     const stem = (file: string) => basename(file).replace(/\.stories\.[cm]?[jt]sx?$/, '')
     const own = basename(p.file, extname(p.file))
-    const candidates = stories.filter((s) => s.title && s.names.length && (s.component === p || (s.imports.includes(p) && (stem(s.file) === p.name || stem(s.file) === own))))
+    // A story file named after the part draws it even when its stories are of a
+    // presentational half in the same file — `FilesPanel.stories.tsx` drawing
+    // `FilesPanelView` is FilesPanel's picture, and its page attaches there (UIG-19).
+    const sameFile = (s: (typeof stories)[number]) => s.imports.some((q) => q.file === p.file)
+    const candidates = stories.filter((s) => s.title && s.names.length && (s.component === p || (s.imports.includes(p) && (stem(s.file) === p.name || stem(s.file) === own)) || (stem(s.file) === p.name && sameFile(s))))
     candidates.sort((a, b) => Number(b.component === p) - Number(a.component === p) || a.file.localeCompare(b.file))
     const s = candidates[0]
     if (!s || !s.title) return { docsId: null, storyId: null }

package/src/registry/cli.ts

@@ -15,16 +15,20 @@
  *
  * **In an app**: nothing is committed (Katerina, 18 September 2026 — the
  * package is public, the apps are private). `check` builds the app's catalogue
- * and fails when a part has no one-line description or cannot be sorted; CI's
- * `gate` job runs it. `build` writes the catalogue to a file only when asked.
+ * and fails when a part has no one-line description or cannot be sorted, or
+ * when a reusable part breaks the usage-page contract (UIG-19, `./contract`);
+ * CI's `gate` job runs it. `build` writes the catalogue to a file only when asked.
  *
  * `find` searches the package's catalogue — the one shipped inside the installed
  * package, or this repo's own in the package — plus, in an app, the app's own,
  * built fresh, plus each `--also` app that sits beside it.
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { basename, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { CONTRACT_KINDS, contractProblems, linkProblems } from './contract'
 import { findInRegistries, formatFindings } from './find'
 import { CLASSES, validateRegistry, type Registry } from './schema'
 
@@ -39,6 +43,7 @@ import { CLASSES, validateRegistry, type Registry } from './schema'
  */
 const packageBuilder = () => import('./build')
 const appBuilder = () => import('./app')
+const gatedScan = () => import('./gated')
 
 const [command, ...rest] = process.argv.slice(2)
 const VALUED = ['--limit', '--out', '--file', '--root', '--repo', '--also']
@@ -94,6 +99,60 @@ async function buildApp(folder: string, repo: string | undefined): Promise<Regis
   return registry
 }
 
+/**
+ * Every story and docs link in a catalogue, against the Storybook beside it
+ * (UIG-19). `storybook index` writes the ids Storybook itself would serve — no
+ * server, no browser, seconds — so a renamed story, or a page that no longer
+ * compiles, fails here rather than as a dead link somebody finds later.
+ * Reports, and says whether it passed. A folder with no Storybook has nothing
+ * to check.
+ */
+function checkLinks(registry: Registry, folder: string): boolean {
+  const bin = resolve(folder, 'node_modules', '.bin', process.platform === 'win32' ? 'storybook.cmd' : 'storybook')
+  if (!existsSync(resolve(folder, '.storybook')) || !existsSync(bin)) {
+    process.stdout.write('story links: no Storybook here, nothing to check\n')
+    return true
+  }
+  const out = join(mkdtempSync(join(tmpdir(), 'estiva-ui-index-')), 'index.json')
+  // A `.cmd` needs a shell on Windows, and Node wants that as one quoted line
+  // rather than an argument list. Both paths are ours: the app's folder and a temp file.
+  const run =
+    process.platform === 'win32'
+      ? spawnSync(`"${bin}" index -o "${out}" --quiet`, { cwd: folder, encoding: 'utf8', shell: true })
+      : spawnSync(bin, ['index', '-o', out, '--quiet'], { cwd: folder, encoding: 'utf8' })
+  if (run.status !== 0 || !existsSync(out)) {
+    process.stderr.write(`story links: Storybook could not index its stories, so no link can be trusted:\n${(run.stderr || run.stdout || '').trim()}\n`)
+    return false
+  }
+  const ids = new Set(Object.keys((JSON.parse(readFileSync(out, 'utf8')) as { entries: Record<string, unknown> }).entries))
+  const dead = linkProblems(registry, ids)
+  const count = registry.entries.reduce((n, entry) => n + (entry.storyId ? 1 : 0) + (entry.docsId ? 1 : 0), 0)
+  if (dead.length) {
+    process.stderr.write(`story links: ${dead.length} of ${count} lead nowhere:\n  ${dead.join('\n  ')}\n`)
+    return false
+  }
+  process.stdout.write(`story links: all ${count} open a story or docs page Storybook has\n`)
+  return true
+}
+
+/**
+ * What a part draws only when a prop is passed, where no story passes it
+ * (UIG-19, `./gated`). Strict, by Katerina's ruling: a part's own stories show
+ * everything it can draw. In an app it reads the reusable parts; in the package,
+ * every component (`kinds` is the package's one class, `component`).
+ */
+async function checkGated(registry: Registry, folder: string, kinds?: string[]): Promise<boolean> {
+  const { gatedFindings } = await gatedScan()
+  const found = gatedFindings(registry, folder, { ...(kinds ? { kinds } : {}), pictured: 'own' })
+  if (found.length) {
+    const lines = found.map((f) => `${f.part} (${f.file}) draws something only when given \`${f.prop}\`, and no story that draws it passes \`${f.prop}\`: pass it in a story`)
+    process.stderr.write(`stories: ${found.length === 1 ? 'one thing a part draws is' : `${found.length} things parts draw are`} never shown:\n  ${lines.join('\n  ')}\n`)
+    return false
+  }
+  process.stdout.write('stories: everything a part draws behind a prop is shown by a story\n')
+  return true
+}
+
 /** One line per kind, in a fixed order, so two runs read the same. */
 function summary(registry: Registry): string {
   const count = (cls: string) => registry.entries.filter((entry) => entry.app?.class === cls).length
@@ -165,8 +224,19 @@ async function main(): Promise<number> {
 
     case 'check': {
       if (!isPackage) {
-        process.stdout.write(`${summary(await buildApp(root, value('repo')))}\n`)
-        return 0
+        const registry = await buildApp(root, value('repo'))
+        process.stdout.write(`${summary(registry)}\n`)
+        // The usage-page contract and the story links (UIG-19): the one copy, run by every app's `gate` job.
+        const broken = contractProblems(registry, root)
+        if (broken.length) {
+          process.stderr.write(`${broken.length === 1 ? 'a part breaks' : `${broken.length} parts break`} the usage-page contract:\n  ${broken.join('\n  ')}\n`)
+        } else {
+          const owed = registry.entries.filter((entry) => (CONTRACT_KINDS as readonly string[]).includes(entry.app?.class ?? '')).length
+          process.stdout.write(`usage pages: all ${owed} reusable parts keep the contract and are drawn somewhere\n`)
+        }
+        const linked = checkLinks(registry, root)
+        const shown = await checkGated(registry, root)
+        return broken.length || !linked || !shown ? 1 : 0
       }
       const { buildRegistry, serializeRegistry } = await packageBuilder()
       const path = packageRegistryPath()
@@ -187,7 +257,9 @@ async function main(): Promise<number> {
         return 1
       }
       process.stdout.write(`${path}: current, ${built.entries.length} entries from ${built.builtFrom.exports} exports\n`)
-      return 0
+      const linked = checkLinks(built, root)
+      const shown = await checkGated(built, root, ['component'])
+      return linked && shown ? 0 : 1
     }
 
     default: