@prestack/thread-ui 0.0.1 → 0.1.0

package/dist/ui/compositions.ts

@@ -0,0 +1,633 @@
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from '@prestack/thread/core/files'
+import { basename, dirname, join, relative } from 'node:path'
+import { argv, stdout } from 'node:process'
+
+import { TYPED, wrapped } from '@prestack/thread/core/answers'
+import { exit, invoked } from '@prestack/thread/core/invoked'
+import { valuesIn } from '@prestack/thread/core/rows'
+import type { Threaded } from '@prestack/thread/core/thread'
+import { named as packageOf } from '@prestack/thread/core/scope'
+import type { Tree } from '@prestack/thread/core/tree'
+import { findTree, inTree } from '@prestack/thread/core/tree'
+
+import { compiled } from './generators/react.ts'
+
+export const TEACHES: readonly string[] = [
+  '  what the body may reach, and how a premium state is written:',
+  '',
+  '    `useUi()` is the door. It carries `actor` — who is asking, with the roles read from',
+  '    the row that declared itself the caller — and `translate`, `clock` and `dispatch`. Name',
+  '    it in the body and the import is written for you.',
+  '',
+  '    A premium look is not decided at the call site. A grant already says who may run an',
+  '    operation, in words your own entity declares, and a signal that names that operation',
+  '    holds for exactly the callers the grant refuses. The rule is written once, on the',
+  '    grant, and every screen follows it:',
+  '',
+  '      <FeatureBox.paywalled>',
+  '        <Text k=\'feature.title\' />',
+  '      </FeatureBox.paywalled>',
+  '',
+  '    Read it in three parts, and each is its own command:',
+  '',
+  '      `locked` is a signal the ELEMENT declares it raises — `thread create element` with',
+  '      `raises: locked`. A signal this app declares cannot be raised on an element that',
+  '      never said it raises one, so `Box` will not take it. Nothing passes it here: it is',
+  '      set for you wherever the gate refuses the operation the signal names.',
+  '      `.paywalled` is a variant worn as the TAG, never passed as a prop, and it is what',
+  '      carries the look — `thread create variant` with a `state: locked` and what it sets.',
+  '      Declare that state on a MATERIAL instead and every variant made of it locks the same',
+  '      way, which is how one overlay dresses a whole app from one row.',
+  '      The rule itself is `thread grant`, and the words in it are options on the value your',
+  '      entity names as saying what a caller may do — `thread create entity`.',
+  '',
+  '    THE MEMBER IS THE VARIANT\'S WHOLE ID, CAMELCASED — never the part after the element',
+  '    name. A variant `button-fill` is worn `<Button.buttonFill>`, and `<Button.fill>` is not',
+  '    a thing. `.paywalled` above reads short only because that variant is itself named',
+  '    `paywalled`; most carry the element in their id and wear all of it.',
+  '',
+  '  how a control reaches an operation:',
+  '',
+  '    Wiring is imperative. There is no `run=`, `operation=` or `dispatch=` prop on any',
+  '    element, and the compiler is what will tell you so. A control calls dispatch in its own',
+  '    handler:',
+  '',
+  '      <Button.buttonFill label=\'common.save\'',
+  '        onPress={() => useUi().dispatch?.(\'wf_save\')} />',
+  '',
+  '    `dispatch` is optional on the hook, so `?.` is required — without it the compiler says',
+  '    "Cannot invoke an object which is possibly \'undefined\'". The name is the operation\'s own',
+  '    id from `thread create operation`, and one this app never declared is refused before it',
+  '    runs. An operation whose `to:` named nobody is refused however the button looks — and',
+  '    `to:` takes roles off an entity, which is a noun that arrives with `thread attach',
+  `    ${packageOf('data')}\`.`,
+  '',
+  '    Nothing here decides access. The gate still refuses the operation behind the lock',
+  '    whatever the screen shows, so a screen that got this wrong shows the wrong thing and',
+  '    still cannot do the wrong thing.',
+  '',
+  '  how a press moves to another screen:',
+  '',
+  '    Name the screen. `navigateTo` takes the screen\'s export name — its id in PascalCase, so',
+  '    `order-detail` is reached as `navigateTo="OrderDetail"`:',
+  '',
+  '      <Button.buttonNormal label=\'home.orders\' navigateTo="Orders" />',
+  '',
+  '    That is the whole of it. `thread routes` reads every `navigateTo` the screens and their',
+  '    compositions hold and writes the map — from which screen, through which button, to which',
+  '    screen — and the pages. A page is reached by its route, and a sheet, popover, overlay or',
+  '    toast opens where somebody already is, so the press is written the same way for both.',
+  '    A name no screen has and a destination not written out as a name are each refused there.',
+  '    Never an `href` and never',
+  '    a router: a move the map cannot see is a screen the map reads as unreachable.',
+  '',
+  '  how a screen shows data:',
+  '',
+  '    A screen NAMES the reads it binds, and never fetches. `views` takes the ids of declared',
+  '    views, the framework runs each one, and `useView` hands back what came out:',
+  '',
+  '      export const Orders = screen(\'orders\', { as: \'page\', views: [\'vw_orders\'] }, () => (',
+  '        <Each rows={useView<readonly Row[]>(\'vw_orders\') ?? []} by="id">',
+  '          {(row) => <Text k="orders.line" with={{ name: row.name }} />}',
+  '        </Each>',
+  '      ))',
+  '',
+  '    `useView` comes through the same door as `useUi`, and it refuses a name the screen did not',
+  '    bind. `thread routes` refuses a view this app declares no operation for, and writes what each',
+  '    screen shows into the map. A fetch of your own, or a hook you wrote, is how a screen ends up',
+  '    showing something nothing declared, and there is no second way in.',
+]
+
+export const REACHES = /\buseUi\s*\(/
+
+const here = 'thread/ui/compositions.ts'
+
+const said = [
+  {
+    on: '2026-08-25',
+    said: 'Compositions is basically a mix of elements+variants, arranged with arrangement elements, with ways to invoke functions (navigateTo, dispatch).',
+  },
+  {
+    on: '2026-08-25',
+    said: 'The compositions.ts just says what the thing is, and describes it. Then the file itself, seeded, is a cmp_ file, where we build the actual UI from. And the UI file is plain react, just with our system.',
+  },
+  {
+    on: '2026-08-25',
+    said: 'Variants themselves declare what elements they relate to, in their declarations. Then the composition says button.primary and if that matches the combination of variant and element it is acceptable. And make sure the composition can only dispatch existing operations.',
+  },
+]
+
+export const declares: readonly Threaded[] = []
+
+export const COMPOSITIONS: Threaded & { readonly files: string } = {
+  id: 'composition',
+  at: here,
+  files: 'compositions/cmp_*.tsx',
+  describes:
+    'A React component made through this system: elements wearing variants, arranged, and able to reach a declared operation. Each row names a file prefixed `cmp_`, and that file is plain React a person writes, because the arrangement, the conditions and the content are theirs. A call site states only what is left over: what a thing does comes from its element, and how it looks and which states it answers to come from its variant, so `Button.primary` is legal only where a variant `primary` says it is worn by `Button`. Text in it is a message key, a look is a variant, and a value names a style guide row, never a raw one. The framework ships none, because what an app is made of is the app’s, and this row says what a composition is, never what is inside it.',
+  version: 1,
+  cites: said,
+  declares,
+}
+
+const PASCAL = (id: string): string =>
+  id
+    .split('-')
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join('')
+
+export function nameOf(at: string): string {
+  const file = at.split('\\').join('/').split('/').at(-1) ?? at
+  return PASCAL(file.replace(/^cmp_/, '').replace(/\.[^.]+$/, ''))
+}
+
+type Listed = {
+  readonly id: string
+  readonly at?: string
+  readonly describes?: string
+  readonly wears?: readonly string[]
+  readonly arranges?: boolean
+}
+
+function sheetOf(tree: Tree, file: string, ...named: readonly string[]): readonly Listed[] {
+  const at = inTree(tree, file)
+  if (!existsSync(at)) return []
+  const held = valuesIn(readFileSync(at)) as Readonly<
+    Record<string, { readonly declares?: readonly Listed[] } | undefined>
+  >
+  for (const one of named) {
+    const found = held[one]?.declares
+    if (found !== undefined) return found
+  }
+  return []
+}
+
+const camelOf = (id: string): string => id.replace(/-([a-z0-9])/g, (_, one: string) => one.toUpperCase())
+
+const sentence = (one: Listed, pad: string): readonly string[] =>
+  String(one.describes ?? '').trim() === '' ? [] : wrapped(String(one.describes), pad)
+
+function listed(tree: Tree, making: 'composition' | 'screen'): readonly string[] {
+  const elements = sheetOf(tree, `elements.${'ts'}`, 'ELEMENT', 'ELEMENTS')
+  const variants = sheetOf(tree, `variants.${'ts'}`, 'VARIANT', 'VARIANTS')
+  const compositions = sheetOf(tree, `compositions.${'ts'}`, 'COMPOSITION', 'COMPOSITIONS')
+  const screens = making === 'screen' ? sheetOf(tree, `screens.${'ts'}`, 'SCREEN', 'SCREENS') : []
+
+  const worn = new Map<string, string[]>()
+  for (const one of variants) {
+    for (const each of one.wears ?? []) {
+      const key = PASCAL(each)
+      const already = worn.get(key) ?? []
+      if (!already.includes(one.id)) worn.set(key, [...already, one.id])
+    }
+  }
+
+  const writes = (one: Listed): string => {
+    const name = PASCAL(one.id)
+    const members = (worn.get(name) ?? []).sort().map((each) => `<${name}.${camelOf(each)}>`)
+    if (members.length === 0) return `<${name}>`
+    return one.arranges === true ? `<${name}>, or ${members.join(' ')}` : members.join(' ')
+  }
+
+  const section = (title: string, rows: readonly Listed[], write: (one: Listed) => string): readonly string[] =>
+    rows.length === 0
+      ? [`  ${title}: none yet.`, '']
+      : [
+          `  ${title} (${String(rows.length)}):`,
+          ...rows.flatMap((one) => [`    ${write(one)}`, ...sentence(one, '      ')]),
+          '',
+        ]
+
+  return [
+    '',
+    ...(making === 'screen'
+      ? section('SCREENS that exist, and the name a press reaches each one by', screens, (one) => `${one.id} — navigateTo="${PASCAL(one.id)}"`)
+      : []),
+    ...section('COMPOSITIONS you can place', compositions, (one) =>
+      `<${typeof one.at === 'string' && one.at !== '' ? nameOf(one.at) : PASCAL(one.id)}>`,
+    ),
+    ...section('ELEMENTS, written as the tags they can actually be typed as', elements, writes),
+    ...(variants.length === 0
+      ? ['  VARIANTS: none yet.', '']
+      : [
+          `  VARIANTS (${String(variants.length)}), under the elements that accept them:`,
+          ...[...worn.keys()].sort().map((name) =>
+            `    ${name} — ${(worn.get(name) ?? []).sort().map(camelOf).join(', ')}`,
+          ),
+          ...(() => {
+            const nobody = variants.filter((one) => (one.wears ?? []).length === 0).map((one) => one.id)
+            return nobody.length === 0
+              ? []
+              : [`    worn by nothing, so writable nowhere: ${nobody.sort().join(', ')}`]
+          })(),
+          '',
+        ]),
+    '  Materials, style guide values, fonts and animations are chosen inside a VARIANT, never inside',
+    `  a body — \`${TYPED} create variant\` prints every one of them at the moment one is needed.`,
+    '',
+
+    `  Every element and the tags it is written as: \`${TYPED} create element\`. Every variant and`,
+    `  the tag it is worn as: \`${TYPED} create variant\`. Then open the one nearest to what you are`,
+    `  about to build with \`${TYPED} read <id>\` — it already answers how a body is arranged, how a`,
+    '  variant is worn and how a control reaches an operation, and a file cannot be wrong in the way',
+    '  a remembered example can.',
+    '',
+  ]
+}
+
+export const catalogue = async (): Promise<readonly string[]> => listed(findTree(), 'composition')
+
+export const screening = async (): Promise<readonly string[]> => listed(findTree(), 'screen')
+
+const TAG = /<([A-Z][A-Za-z0-9]*)/g
+
+export function composed(
+  body: string,
+  rows: readonly { readonly id: string; readonly at?: string }[],
+  from: 'screens' | 'compositions',
+  except?: string,
+): readonly string[] {
+  const named = new Map<string, string>()
+  for (const row of rows) {
+    const at = row.at
+    if (typeof at !== 'string' || at === '' || at === except) continue
+    named.set(PASCAL(row.id), at)
+  }
+  const found = new Set<string>()
+  for (const [, tag] of body.matchAll(TAG)) if (tag !== undefined && named.has(tag)) found.add(tag)
+  return [...found].sort().map((one) => {
+    const at = named.get(one) ?? ''
+    const file = (at.split('\\').join('/').split('/').at(-1) ?? at).replace(/\.[^.]+$/, '')
+    return `import { ${one} } from '${from === 'screens' ? '../compositions' : '.'}/${file}.tsx'`
+  })
+}
+
+const IMPORTS = /^import\s[\s\S]*?from\s*['"]([^'"]+)['"]/gm
+
+const FRAMEWORK = 'thread/'
+
+export const HOME = `${packageOf('ui')}/${here.slice(FRAMEWORK.length).split('/').slice(0, -1).join('/')}`
+
+export const DOORS: ReadonlySet<string> = new Set(['react', `${HOME}/wrappers`, `${HOME}/drag`])
+
+const SHIPPED = new RegExp(`^${HOME}/elements/([a-z0-9-]+)$`)
+
+const slashed = (path: string): string => path.split('\\').join('/')
+
+export function reaching(
+  at: string,
+  text: string,
+  elements: ReadonlySet<string>,
+  declared: ReadonlySet<string>,
+): readonly string[] {
+  const here = slashed(at).split('/').slice(0, -1).join('/')
+  const found = new Set<string>()
+  for (const one of text.matchAll(IMPORTS)) {
+    const from = one[1]
+    if (from === undefined || DOORS.has(from)) continue
+    const shipped = SHIPPED.exec(from)?.[1]
+    if (shipped !== undefined && elements.has(shipped)) continue
+    if (from.startsWith('.') && declared.has(slashed(join(here, from)))) continue
+    found.add(from)
+  }
+  return [...found].sort()
+}
+
+const CLAUSE = /^import\s+(?!type\s)([\s\S]*?)\s*from\s*['"][^'"]+['"]/gm
+
+const WORD = /(?:^|[,{]|\s)(?:[A-Za-z_$][\w$]*\s+as\s+)?([A-Za-z_$][\w$]*)/g
+
+const NOT_A_NAME = new Set(['type', 'as', 'from', 'import'])
+
+const KEPT = 'a composition keeps no state of its own. State belongs to the element that raises the signal, in the works file beside it'
+
+const RUNS = 'nothing here runs on its own. A read is bound by the screen in its own views list, and a press is answered by dispatch'
+
+const REFUSED: Readonly<Record<string, string>> = {
+  useState: KEPT,
+  useReducer: KEPT,
+  useSyncExternalStore: KEPT,
+  useEffect: RUNS,
+  useLayoutEffect: RUNS,
+  element: 'only the compiler writes an element, and a file that calls it turns off the checks that keep this one declared',
+}
+
+export const COMPILED = 'app/_generated/compiled'
+
+export function compiledAt(at: string): string {
+  return `${COMPILED}/${slashed(at)}`
+}
+
+const ENDINGS = ['.tsx', '.ts'] as const
+
+function beside(root: string, where: string, said: string): string | undefined {
+  if (!said.startsWith(`${HOME}/`)) return undefined
+  const tail = said.slice(HOME.length + 1)
+  for (const ending of ENDINGS) {
+    const at = `${COMPILED}/ui/${tail}${ending}`
+    if (!existsSync(join(root, at))) continue
+    const out = slashed(relative(dirname(where), at))
+    return out.startsWith('.') ? out : `./${out}`
+  }
+  return undefined
+}
+
+const NAMED_IMPORT = /(['"])(@[^'"]+)\1/g
+
+export function settled(
+  root: string,
+  rows: readonly Threaded[],
+  checking: boolean,
+  by: string,
+  kept: Set<string>,
+): readonly string[] {
+  const said: string[] = []
+  for (const row of rows) {
+    const file = join(root, row.at)
+    if (!existsSync(file)) continue
+    const held = compiled(readFileSync(file, 'utf8'), row.at)
+    if (held.because !== undefined) {
+      said.push(held.because)
+      continue
+    }
+    const where = compiledAt(row.at)
+    kept.add(where)
+    const text = (held.text ?? '').replace(NAMED_IMPORT, (whole: string, quote: string, said: string) => {
+      const found = beside(root, where, said)
+      return found === undefined ? whole : `${quote}${found}${quote}`
+    })
+    const at = join(root, where)
+    if (!checking) {
+      writeFileSync(at, text, 'utf8')
+      continue
+    }
+    if (existsSync(at) && readFileSync(at, 'utf8') === text) continue
+    said.push(
+      `${where} is not what the compiler writes from ${row.at}. A compiled file that differs from its ` +
+        `source is a hand edit wearing a generated name. Run \`${by}\` and commit what it writes.`,
+    )
+  }
+  return said
+}
+
+const ORG = packageOf('ui').split('/')[0] ?? ''
+
+const REACHED = /^(?:import|export)\s+(type\s+)?(?:(?:[^\n]|\n(?=[ \t}]))*?\s)?from\s*['"]([^'"]+)['"]/gm
+
+export const RUNTIME: readonly string[] = ['wrappers.tsx', 'drag.ts', 'provider.tsx', 'islands/map.ts']
+
+const NODE = /^node:/
+
+function installs(root: string): ReadonlySet<string> {
+  try {
+    const held = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as {
+      readonly dependencies?: Readonly<Record<string, string>>
+      readonly devDependencies?: Readonly<Record<string, string>>
+    }
+    return new Set([...Object.keys(held.dependencies ?? {}), ...Object.keys(held.devDependencies ?? {})])
+  } catch {
+    return new Set()
+  }
+}
+
+function packaging(said: string): string {
+  return said.startsWith('@') ? said.split('/').slice(0, 2).join('/') : (said.split('/')[0] ?? said)
+}
+
+export function emitting(
+  root: string,
+  entries: readonly string[],
+  checking: boolean,
+  kept: Set<string>,
+): readonly string[] {
+  const has = installs(root)
+  const from = join(root, 'node_modules', packageOf('ui'), 'dist', 'ui')
+  const said: string[] = []
+  if (!existsSync(from)) {
+    return [
+      `this app declares an interface and ${packageOf('ui')} is not installed, so there is nothing to emit it from. ` +
+        `Install it and run \`thread attach ${packageOf('ui')}\` again.`,
+    ]
+  }
+  const seen = new Set<string>()
+  const walk = (at: string): void => {
+    if (seen.has(at)) return
+    seen.add(at)
+    const file = join(from, at)
+    if (!existsSync(file)) {
+      said.push(
+        `${at} is part of the interface this app emits, and the installed ${packageOf('ui')} does not hold it. ` +
+          'Upgrade the framework packages and run this again.',
+      )
+      return
+    }
+    const text = readFileSync(file, 'utf8')
+    const where = `${COMPILED}/ui/${at}`
+    kept.add(where)
+    const to = join(root, where)
+    if (checking) {
+      if (!existsSync(to) || readFileSync(to, 'utf8') !== text) {
+        said.push(
+          `${where} is not what this app emits from ${packageOf('ui')}. An emitted file that differs from ` +
+            'its source is a hand edit wearing a generated name. Run `thread compositions` and commit what it writes.',
+        )
+      }
+    } else {
+      writeFileSync(to, text, 'utf8')
+    }
+    for (const one of text.matchAll(REACHED)) {
+      const named = one[2] ?? ''
+      if (named.startsWith('.')) {
+        const next = slashed(join(dirname(at), named))
+        if (next.startsWith('..')) {
+          said.push(`${at} reaches \`${named}\`, which is outside the interface this app emits.`)
+          continue
+        }
+        walk(next)
+        continue
+      }
+      if (one[1] !== undefined) continue
+      if (!named.startsWith(`${ORG}/`)) {
+        const held = packaging(named)
+        if (NODE.test(named) || has.has(held)) continue
+        said.push(
+          `${at} reaches ${held}, and this app installs nothing by that name. An emitted interface brings ` +
+            `what it reaches with it, so ${held} has to arrive when ` +
+            `thread attach ${packageOf('ui')} runs.`,
+        )
+        continue
+      }
+      said.push(
+        `${at} reaches \`${named}\`, so emitting it would leave this app importing the framework while it runs. ` +
+          'It reaches what is emitted beside it, or nothing of this framework at all.',
+      )
+    }
+  }
+  for (const one of entries) walk(one)
+  return said
+}
+
+export function stale(root: string, kept: ReadonlySet<string>, checking: boolean): readonly string[] {
+  const said: string[] = []
+  const walk = (at: string): void => {
+    const where = join(root, at)
+    if (!existsSync(where)) return
+    for (const each of readdirSync(where, { withFileTypes: true })) {
+      const path = `${at}/${each.name}`
+      if (each.isDirectory()) {
+        walk(path)
+        continue
+      }
+      if (kept.has(path)) continue
+      if (checking) {
+        said.push(
+          `${path} sits under ${COMPILED} and nothing declares what it was written from any more. ` +
+            'Run `thread compositions` and it goes.',
+        )
+        continue
+      }
+      rmSync(join(root, path), { force: true })
+    }
+  }
+  walk(COMPILED)
+  return said
+}
+
+export function handing(at: string, text: string): readonly string[] {
+  const found: string[] = []
+  for (const one of text.matchAll(CLAUSE)) {
+    for (const name of (one[1] ?? '').matchAll(WORD)) {
+      const held = name[1]
+      if (held === undefined || NOT_A_NAME.has(held)) continue
+      const why = REFUSED[held]
+      if (why === undefined) continue
+      found.push(`${at} imports \`${held}\`, and ${why}.`)
+    }
+  }
+  if (/\bfetch\s*\(/.test(text)) {
+    found.push(
+      `${at} calls \`fetch\`, and nothing here reaches the network by hand. A screen names the reads it ` +
+        'binds in its own views list, and the framework runs each one.',
+    )
+  }
+  return found
+}
+
+export function undeclared(
+  tree: Tree,
+  rows: readonly Threaded[],
+): readonly string[] {
+  const elements = new Set<string>()
+  const declared = new Set<string>()
+
+  for (const [file, exported] of [
+    ['elements.ts', 'ELEMENT'],
+    ['compositions.ts', 'COMPOSITION'],
+    ['screens.ts', 'SCREEN'],
+  ] as const) {
+    const where = inTree(tree, file)
+    if (!existsSync(where)) continue
+    const sheet = valuesIn(readFileSync(where)) as Readonly<
+      Record<string, { readonly declares?: readonly Threaded[] } | undefined>
+    >
+    for (const row of sheet[exported]?.declares ?? []) {
+      if (exported === 'ELEMENT') elements.add(row.id)
+      if (row.at !== '') declared.add(slashed(row.at))
+    }
+  }
+
+  const found: string[] = []
+  for (const row of rows) {
+    const file = join(tree.at, row.at)
+    if (!existsSync(file)) continue
+    const text = readFileSync(file, 'utf8')
+    found.push(...handing(row.at, text))
+    for (const one of reaching(row.at, text, elements, declared)) {
+      found.push(
+        `${row.at} imports \`${one}\`, which this app declares nothing by. A composition reaches ` +
+          'declared elements, other declared compositions, and the door — everything else is a thing ' +
+          'nothing wrote down. Declare it, or take it out and write the body through `thread create`.',
+      )
+    }
+  }
+  return found
+}
+
+function starter(row: Threaded): string {
+  const name = nameOf(row.at)
+  return `'use client'
+
+import { Box } from '${HOME}/elements/box'
+import { composition } from '${HOME}/wrappers'
+
+export const ${name} = composition('${name}', () => <Box.card />)
+`
+}
+
+export function seeds(rows: readonly Threaded[], held: (at: string) => boolean): readonly { readonly path: string; readonly content: string }[] {
+  return rows.filter((row) => !held(row.at)).map((row) => ({ path: row.at, content: starter(row) }))
+}
+
+function run(): number {
+  const tree = findTree()
+  const at = inTree(tree, 'compositions.ts')
+  if (!existsSync(at)) {
+    stdout.write(`thread: this tree has no ${tree.name}/${basename(at)}, so it declares no composition and there is nothing to seed or check.\n`)
+    return 0
+  }
+  const held = valuesIn(readFileSync(at)) as { COMPOSITION?: { readonly declares?: readonly Threaded[] } }
+
+  if (held.COMPOSITION === undefined) {
+    stdout.write(`thread: ${tree.name}/compositions.ts exports no \`COMPOSITION\`, so nothing declares a composition here.\n`)
+    return 1
+  }
+
+  const rows = held.COMPOSITION.declares ?? []
+  const checking = argv.includes('--check')
+  const made = seeds(rows, (where) => existsSync(join(tree.at, where)))
+
+  const unseeded = made[0]
+  if (checking && unseeded !== undefined) {
+    stdout.write(
+      `thread: ${unseeded.path} is declared and the file is not there yet. A row names a file, and ` +
+        '`--check` never writes one — run `thread compositions` and commit what it seeds.\n',
+    )
+    return 1
+  }
+
+  if (!checking) {
+    for (const one of made) {
+      writeFileSync(join(tree.at, one.path), one.content, 'utf8')
+      stdout.write(`thread: seeded ${one.path}\n`)
+    }
+  }
+
+  const parts = sheetOf(tree, 'elements.ts', 'ELEMENT', 'ELEMENTS')
+  const shipped = `node_modules/${packageOf('ui')}/dist/ui/`
+  const entries = [
+    ...RUNTIME,
+    ...parts.flatMap((one) =>
+      (one.at ?? '').startsWith(shipped) ? [(one.at ?? '').slice(shipped.length).replace(/\.js$/, '.tsx')] : [],
+    ),
+  ]
+  const kept = new Set<string>()
+  for (const one of sheetOf(tree, 'screens.ts', 'SCREEN', 'SCREENS')) {
+    if (one.at !== undefined && one.at !== '') kept.add(compiledAt(one.at))
+  }
+  const found = [
+    ...undeclared(tree, rows),
+    ...emitting(tree.at, entries, checking, kept),
+    ...settled(tree.at, rows, checking, 'thread compositions', kept),
+  ]
+  const loose = [...found, ...(found.length === 0 ? stale(tree.at, kept, checking) : [])]
+  for (const one of loose) stdout.write(`thread: ${one}\n`)
+
+  stdout.write(
+    `thread: ${String(rows.length)} composition(s) declared, ${String(made.length)} seeded, ` +
+      `${String(rows.length - made.length)} already written, ` +
+      `${loose.length === 0 ? 'none reaching anything undeclared' : `${String(loose.length)} reaching something undeclared`}\n`,
+  )
+  return loose.length === 0 ? 0 : 1
+}
+
+if (invoked(import.meta.url)) exit(run())

package/dist/ui/consent.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod'
+
+export const ConsentCategorySchema = z
+  .strictObject({
+    id: z
+      .string()
+      .regex(/^[a-z][a-z0-9_]*$/, 'a consent category id is lower_snake_case')
+      .describe('The id recorded in `thread.consent.categories`.'),
+    labelKey: z.string().min(1).describe('The category’s name, as a message key. Never a sentence.'),
+    describeKey: z.string().min(1).describe('What is collected under it, as a message key.'),
+
+    required: z.boolean().default(false).describe('True where the app cannot function without it.'),
+  })
+  .describe('One thing an app may ask permission to collect.')
+
+export type ConsentCategory = z.infer<typeof ConsentCategorySchema>
+
+const TELEMETRY: ConsentCategory = ConsentCategorySchema.parse({
+  id: 'telemetry',
+  labelKey: 'consent.telemetry.label',
+  describeKey: 'consent.telemetry.describe',
+})
+
+const REGISTRY = new Map<string, ConsentCategory>([[TELEMETRY.id, TELEMETRY]])
+
+export function defineConsentCategory(category: ConsentCategory): void {
+  const parsed = ConsentCategorySchema.parse(category)
+  if (REGISTRY.has(parsed.id)) throw new Error(`consent category "${parsed.id}" is already registered`)
+  REGISTRY.set(parsed.id, parsed)
+}
+
+export function consentCategories(): readonly ConsentCategory[] {
+  return [...REGISTRY.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+}
+
+export function consentCategory(id: string): ConsentCategory | undefined {
+  return REGISTRY.get(id)
+}
+
+export const ConsentDecisionSchema = z
+  .strictObject({
+    decision: z.enum(['accepted', 'declined', 'withdrawn']).describe('Withdrawal is a decision and is recorded like any other.'),
+
+    accepted: z.array(z.string()).describe('The category ids accepted.'),
+    offered: z.array(z.string()).describe('Every category shown at that moment, accepted or not.'),
+  })
+  .describe('One consent decision, with the choice set as it stood when it was made.')
+
+export type ConsentDecision = z.infer<typeof ConsentDecisionSchema>
+
+export function consentAllows(decision: ConsentDecision | undefined, categoryId: string): boolean {
+  if (consentCategory(categoryId)?.required === true) return true
+  if (decision === undefined || decision.decision !== 'accepted') return false
+  return decision.accepted.includes(categoryId)
+}