@estiva-app/ui 0.26.0 → 0.28.0

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:

package/src/registry/contract.test.ts

@@ -0,0 +1,158 @@
+/// <reference types="node" />
+/**
+ * UIG-19: the usage-page contract every app's `gate` job runs, and the story
+ * links. Each case is one the three repos actually have, or one that got past
+ * the copies this replaces:
+ *
+ * - a page that lost its `When not` (the ticket's own example);
+ * - Peek's pages, which never checked the order or the code under `How`;
+ * - a reusable part drawn only inside another story, whose page says so on a
+ *   **Seen in** line (Katerina, 21 September);
+ * - a story file named after a part whose stories draw its `…View` half, in the
+ *   same file — FilesPanel and TopicDetailsDialog in Peek, which the catalogue
+ *   used to call drawn nowhere;
+ * - a Windows checkout, read with CRLF.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import { buildAppRegistry } from './app'
+import { contractProblems, hasSeenIn, linkProblems, pageProblem } from './contract'
+
+const made: string[] = []
+afterAll(() => {
+  for (const dir of made) rmSync(dir, { recursive: true, force: true })
+})
+
+function app(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), 'uig19-'))
+  made.push(dir)
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'fixture-app', version: '1.0.0' }))
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, path)), { recursive: true })
+    writeFileSync(join(dir, path), text)
+  }
+  return dir
+}
+
+const PAGE = [
+  "import { Meta } from '@storybook/addon-docs/blocks'",
+  '',
+  "<Meta title='Parts/Badge' />",
+  '',
+  '# Badge',
+  '',
+  'A small count beside a name.',
+  '',
+  '## When',
+  '',
+  'A count.',
+  '',
+  '## When not',
+  '',
+  'A word.',
+  '',
+  '## How',
+  '',
+  '```tsx',
+  '<Badge count={3} />',
+  '```',
+  '',
+  '## What it owns',
+  '',
+  'Nothing. It only draws.',
+  '',
+].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`
+
+describe('a usage page', () => {
+  it('keeps the contract with an opening line and the four sections in order', () => {
+    expect(pageProblem(PAGE)).toBeNull()
+  })
+
+  it('fails without "When not"', () => {
+    expect(pageProblem(PAGE.replace('## When not', '## Not when'))).toBe('no "When not" section')
+  })
+
+  it('fails with its sections out of order', () => {
+    const swapped = PAGE.replace('## When not\n\nA word.\n', '').replace('## What it owns', '## When not\n\nA word.\n\n## What it owns')
+    expect(pageProblem(swapped)).toMatch(/^sections out of order/)
+  })
+
+  it('fails with no opening line', () => {
+    expect(pageProblem(PAGE.replace('A small count beside a name.\n', ''))).toMatch(/^no opening line/)
+  })
+
+  it('fails with no code under How', () => {
+    expect(pageProblem(PAGE.replace('```tsx\n<Badge count={3} />\n```', 'Pass a count.'))).toBe('no code under "How"')
+  })
+
+  it('reads a Windows checkout', () => {
+    expect(pageProblem(PAGE.replace(/\n/g, '\r\n'))).toBeNull()
+  })
+
+  it('knows a Seen in line, and only at the start of a line', () => {
+    expect(hasSeenIn('**Seen in** — *Messages/ConversationCard*.')).toBe(true)
+    expect(hasSeenIn('It is **Seen in** two places.')).toBe(false)
+  })
+})
+
+describe('an app against the contract', () => {
+  it('passes a reusable part with a page and a story, and asks nothing of a one-off', () => {
+    const dir = app({
+      'src/Badge.tsx': part('Badge'),
+      'src/Badge.mdx': PAGE,
+      'src/Badge.stories.tsx': "import { Badge } from './Badge'\nconst meta = { title: 'Parts/Badge', component: Badge }\nexport default meta\nexport const Default = {}\n",
+      'src/Once.tsx': part('Once', 'one-off'),
+    })
+    expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([])
+  })
+
+  it('names a reusable part with no page, and the file to write', () => {
+    const dir = app({ 'src/Badge.tsx': part('Badge') })
+    expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([
+      'Badge (reusable, src/Badge.tsx) has no usage page: write src/Badge.mdx, with an opening line, then When, When not, How, What it owns',
+    ])
+  })
+
+  it('names a page that lost a section', () => {
+    const dir = app({ 'src/Badge.tsx': part('Badge'), 'src/Badge.mdx': PAGE.replace('## When not', '## Not when') })
+    const problems = contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)
+    expect(problems).toContain('Badge (reusable, src/Badge.tsx): src/Badge.mdx has no "When not" section')
+  })
+
+  it('names a reusable part drawn nowhere, and passes it once its page says where it is seen', () => {
+    const dir = app({ 'src/Badge.tsx': part('Badge'), 'src/Badge.mdx': PAGE })
+    expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([
+      'Badge (reusable, src/Badge.tsx) is drawn nowhere: give it a story, or write a "**Seen in**" line on src/Badge.mdx naming the stories that draw it, or why none can',
+    ])
+    writeFileSync(join(dir, 'src/Badge.mdx'), PAGE.replace('A small count beside a name.\n', 'A small count beside a name.\n\n**Seen in** — *Parts/Card*, beside the title.\n'))
+    expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([])
+  })
+
+  it("counts a story file named after the part that draws its view, from the part's own file", () => {
+    const dir = app({
+      'src/Panel.tsx': `${part('Panel')}\n/** The half that only draws. */\nexport function PanelView() {\n  return <div>view</div>\n}\n`,
+      'src/Panel.stories.tsx': "import { PanelView } from './Panel'\nconst meta = { title: 'Parts/Panel', component: PanelView }\nexport default meta\nexport const Open = {}\n",
+    })
+    const entry = buildAppRegistry({ root: dir, repo: 'fixture' }).entries.find((e) => e.name === 'Panel')
+    expect(entry?.storyId).toBe('parts-panel--open')
+  })
+})
+
+describe('story links', () => {
+  it('names a link its Storybook does not have, and passes the ones it has', () => {
+    const dir = app({
+      'src/Badge.tsx': part('Badge'),
+      'src/Badge.stories.tsx': "import { Badge } from './Badge'\nconst meta = { title: 'Parts/Badge', component: Badge }\nexport default meta\nexport const Default = {}\n",
+    })
+    const registry = buildAppRegistry({ root: dir, repo: 'fixture' })
+    expect(linkProblems(registry, new Set(['parts-badge--default', 'parts-badge--docs']))).toEqual([])
+    expect(linkProblems(registry, new Set(['parts-badge--docs']))).toEqual([
+      'Badge (src/Badge.tsx) links to a story its Storybook does not have: parts-badge--default',
+    ])
+  })
+})

package/src/registry/contract.ts

@@ -0,0 +1,108 @@
+/**
+ * The usage-page contract, checked against an app's catalogue (UIG-19).
+ *
+ * Every part an app classifies **reusable** (or **promote-candidate**) has a
+ * page beside it — `<PartName>.mdx` in the component's own folder — that opens
+ * with a line saying what the part is, then `When`, `When not`, `How` (with
+ * code) and `What it owns`, in that order. And it is drawn somewhere: a story
+ * of its own, or a **Seen in** line on its page naming the stories that draw
+ * it, or saying why none can (Katerina, 21 and 23 September 2026). A one-off
+ * needs only its class and a purpose line, which the catalogue already refuses
+ * to build without.
+ *
+ * This is the one copy. Peek and Ship each used to carry their own, pasted into
+ * their `scripts/gates-checks.mjs` and run only by `gates:status`, so a page
+ * could lose its `When not` and still merge. `estiva-ui check` runs this in
+ * every app's `gate` job (docs/GATES.md §23: one copy, in the package).
+ *
+ * The package's own pages keep the fuller contract in `src/pages.test.ts`,
+ * which also reads `What it owns` back against the lint rule.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Registry } from './schema'
+
+/** The four headings, in the order a page carries them. */
+export const PAGE_SECTIONS = ['When', 'When not', 'How', 'What it owns'] as const
+
+/** The classes that owe a page and a picture. */
+export const CONTRACT_KINDS = ['reusable', 'promote-candidate'] as const
+
+/** The line that stands in for a story of the part's own. */
+const SEEN_IN = /^\*\*Seen in\*\*/m
+
+/**
+ * Why a page breaks the contract, or null when it keeps it.
+ *
+ * Read on normalised text: the apps are checked out with CRLF on Windows.
+ */
+export function pageProblem(source: string): string | null {
+  const text = source.replace(/\r\n/g, '\n')
+  const heads = [...text.matchAll(/^##+\s+(.+?)\s*$/gm)].map((m) => m[1])
+  const at = PAGE_SECTIONS.map((s) => heads.indexOf(s))
+  const missing = PAGE_SECTIONS.filter((_, i) => at[i] < 0)
+  if (missing.length) return `no ${missing.map((s) => `"${s}"`).join(', ')} section`
+  if (at.some((i, n) => n > 0 && i < at[n - 1])) return `sections out of order: they go ${PAGE_SECTIONS.join(', ')}`
+  // The opening line: the first paragraph under the title that is not markup.
+  const opening = text
+    .split(/^# .*$/m)[1]
+    ?.split(/^##\s/m)[0]
+    ?.split(/\n\s*\n/)
+    .map((s) => s.trim())
+    .find((s) => s && !s.startsWith('<') && !s.startsWith('import '))
+  if (!opening) return 'no opening line under the title saying what the part is'
+  if (!/^##\s+How\s*\n[\s\S]*?```tsx?\n/m.test(text)) return 'no code under "How"'
+  return null
+}
+
+/** Whether a page records where the part is drawn, in place of a story of its own. */
+export function hasSeenIn(source: string): boolean {
+  return SEEN_IN.test(source.replace(/\r\n/g, '\n'))
+}
+
+/**
+ * Every catalogue link that names a story or a docs page its Storybook does not
+ * have (UIG-19: a dead link is a build failure, not a dead end found six weeks
+ * later). `ids` is every entry id in the Storybook's own index — what
+ * `storybook index` writes — so this is Storybook's answer, not a guess at how
+ * it builds an id.
+ */
+export function linkProblems(registry: Registry, ids: ReadonlySet<string>): string[] {
+  const problems: string[] = []
+  for (const entry of registry.entries) {
+    for (const key of ['storyId', 'docsId'] as const) {
+      const id = entry[key]
+      if (id && !ids.has(id)) problems.push(`${entry.name} (${entry.sourceFile}) links to ${key === 'storyId' ? 'a story' : 'a docs page'} its Storybook does not have: ${id}`)
+    }
+  }
+  return problems
+}
+
+/**
+ * Every way an app's catalogue breaks the contract, one line each, naming the
+ * part, its file and what to do. Empty when it keeps it.
+ *
+ * `root` is the app's own folder: the one its catalogue's paths are relative to.
+ */
+export function contractProblems(registry: Registry, root: string): string[] {
+  const problems: string[] = []
+  for (const entry of registry.entries) {
+    const cls = entry.app?.class
+    if (!cls || !(CONTRACT_KINDS as readonly string[]).includes(cls)) continue
+    // Where the page must be: beside the component, named after the part —
+    // the same place the catalogue looks (src/registry/app.ts).
+    const page = join(entry.sourceFile.replace(/[^/\\]+$/, ''), `${entry.name}.mdx`).replace(/\\/g, '/')
+    const where = `${entry.name} (${cls}, ${entry.sourceFile})`
+    if (!existsSync(join(root, page))) {
+      problems.push(`${where} has no usage page: write ${page}, with an opening line, then ${PAGE_SECTIONS.join(', ')}`)
+      continue
+    }
+    const text = readFileSync(join(root, page), 'utf8')
+    const problem = pageProblem(text)
+    if (problem) problems.push(`${where}: ${page} has ${problem}`)
+    if (entry.storyId === null && !hasSeenIn(text)) {
+      problems.push(`${where} is drawn nowhere: give it a story, or write a "**Seen in**" line on ${page} naming the stories that draw it, or why none can`)
+    }
+  }
+  return problems
+}

package/src/registry/gated.test.ts

@@ -0,0 +1,98 @@
+/// <reference types="node" />
+/**
+ * UIG-19: what a part draws only behind a prop, and no story passes. Each case
+ * is one the scan met in Peek or the package:
+ *
+ * - a gate on the part itself (SectionHeader's chevron);
+ * - a prop handed to a smaller part that gates on it (ConversationCard's
+ *   `onReply`, which the strip draws — strict, by Katerina's ruling);
+ * - a prop handed to a dialog, shut in every story (skipped, her ruling);
+ * - a story that spreads another story's args (`...Topic.args`);
+ * - a spread it cannot open (a helper's `{...props}`), which keeps it quiet.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import { buildAppRegistry } from './app'
+import { gatedFindings } from './gated'
+
+const made: string[] = []
+afterAll(() => {
+  for (const dir of made) rmSync(dir, { recursive: true, force: true })
+})
+
+function app(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), 'uig19-gated-'))
+  made.push(dir)
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'fixture-app', version: '1.0.0' }))
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, path)), { recursive: true })
+    writeFileSync(join(dir, path), text)
+  }
+  return dir
+}
+
+const find = (dir: string) => gatedFindings(buildAppRegistry({ root: dir, repo: 'fixture' }), dir).map((f) => `${f.part}.${f.prop}`)
+
+const card = `/**
+ * A card.
+ * @registry reusable: the fixture says so
+ */
+export function Card({ title, onReply, onShare }: { title: string; onReply?: () => void; onShare?: () => void }) {
+  return (
+    <div>
+      {title}
+      {onReply && <button type="button">Reply</button>}
+      <Strip onShare={onShare} />
+      <ShareDialog onShare={onShare} />
+    </div>
+  )
+}
+
+/** The strip under a card. */
+export function Strip({ onShare }: { onShare?: () => void }) {
+  return <div>{onShare ? <button type="button">Share</button> : null}</div>
+}
+
+/** A dialog, shut until opened. */
+export function ShareDialog({ onShare }: { onShare?: () => void }) {
+  return <div>{onShare && <button type="button">Share now</button>}</div>
+}
+`
+
+const story = (body: string) => `import { Card } from './Card'\nconst meta = { title: 'Parts/Card', component: Card, args: { title: 'Hello' } }\nexport default meta\n${body}\n`
+
+describe('what a part draws behind a prop', () => {
+  it('names a gate on the part, and one it hands to a smaller part, when no story passes either', () => {
+    const dir = app({ 'src/Card.tsx': card, 'src/Card.stories.tsx': story('export const Default = {}') })
+    expect(find(dir).sort()).toEqual(['Card.onReply', 'Card.onShare'])
+  })
+
+  it('is satisfied by a story that passes them, in args or through another story’s args', () => {
+    const dir = app({
+      'src/Card.tsx': card,
+      'src/Card.stories.tsx': story("export const Default = { args: { onReply: () => {} } }\nexport const Shared = { args: { ...Default.args, onShare: () => {} } }"),
+    })
+    expect(find(dir)).toEqual([])
+  })
+
+  it('skips a prop that reaches only a dialog', () => {
+    const only = card.replace('      <Strip onShare={onShare} />\n', '')
+    const dir = app({ 'src/Card.tsx': only, 'src/Card.stories.tsx': story("export const Default = { args: { onReply: () => {} } }") })
+    expect(find(dir)).toEqual([])
+  })
+
+  it('stays quiet when a story passes props it cannot read', () => {
+    const dir = app({
+      'src/Card.tsx': card,
+      'src/Card.stories.tsx': `import { Card } from './Card'\nimport { props } from './fixtures'\nconst meta = { title: 'Parts/Card', component: Card }\nexport default meta\nexport const Default = { render: () => <Card title="x" {...props} /> }\n`,
+    })
+    expect(find(dir)).toEqual([])
+  })
+
+  it('asks nothing of a part no story draws: the contract says so instead', () => {
+    const dir = app({ 'src/Card.tsx': card })
+    expect(find(dir)).toEqual([])
+  })
+})