react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.31

package/src/features/sleepTimer.ts

@@ -86,7 +86,7 @@ export function clearSleepTimer(): boolean {
 /**
  * Subscribes to sleep timer changes.
  * @param callback - Called when the sleep timer state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onSleepTimerChanged = NativeUpdatedValue.emitterize<SleepTimer>(
   (cb) => (nativeBrowser.onSleepTimerChanged = cb)
@@ -104,6 +104,11 @@ export function useSleepTimerActive(): boolean {
   const [isActive, setIsActive] = useState(() => getSleepTimer() !== null)
 
   useEffect(() => {
+    // Re-sync before subscribing: a change between the initial read above and this effect would
+    // otherwise be missed for good. `undefined` means nothing has fired yet, whereas `null` is a
+    // real value — the timer being cleared — so it has to re-sync too.
+    const { lastValue } = onSleepTimerChanged
+    if (lastValue !== undefined) setIsActive(lastValue !== null)
     return onSleepTimerChanged.addListener((timer) => {
       setIsActive(timer !== null)
     })
@@ -137,6 +142,9 @@ export function useSleepTimer(params?: {
   const time = state && 'time' in state ? state.time : undefined
 
   useEffect(() => {
+    // Re-sync before subscribing — see useSleepTimerActive.
+    const { lastValue } = onSleepTimerChanged
+    if (lastValue !== undefined) setState(addSecondsLeft(lastValue))
     return onSleepTimerChanged.addListener((event) => {
       setState(addSecondsLeft(event))
     })

package/src/nitro-stub-drift.test.ts

@@ -0,0 +1,277 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, it, expect } from 'vitest'
+
+/**
+ * Drift guard for `ios/Model/NitroTypeStubs.swift`.
+ *
+ * The generated Nitro Swift types are `typealias`es onto C++ structs
+ * (`margelo.nitro.audiobrowser.*`), so SwiftPM cannot compile them without the
+ * whole Nitro C++ core — which is why the SPM test target substitutes
+ * hand-written stubs behind `#if !canImport(NitroModules)`. The cost of that
+ * trick is that the stubs can disagree with the real types, and when they do
+ * `swift test` still passes while the app build breaks. That has already
+ * happened once (1d2edade, "restore the SPM test-stub build after the artwork
+ * variants change").
+ *
+ * Neither native CI job can catch it: the Swift job only ever sees the stubs,
+ * and the app build only ever sees the generated types. This test is the one
+ * place both files are readable at once, so the check lives here.
+ *
+ * The rule is subset-with-exact-types. A stub may declare FEWER properties than
+ * the real type — shared `ios/` sources can only use what the stub declares, so
+ * an omission is safe. What is not safe is a property the real type spells
+ * differently: `var id: String` against a generated `id: String?` compiles under
+ * test and fails to compile in the app.
+ */
+const ROOT = process.cwd()
+const STUBS = join(ROOT, 'ios', 'Model', 'NitroTypeStubs.swift')
+const GENERATED = join(ROOT, 'nitrogen', 'generated', 'ios', 'swift')
+
+/**
+ * Stubbed types with no generated counterpart, and why. Anything else missing
+ * from `nitrogen/generated/ios/swift/` is a stub for a type that no longer
+ * exists — the loudest kind of drift.
+ */
+const NOT_GENERATED: Record<string, string> = {
+  // Nitro core type (`nitro::NullType`), shipped by NitroModules rather than
+  // emitted per-project, so there is no file of ours to compare against.
+  NullType: 'provided by NitroModules core'
+}
+
+type Struct = { kind: 'struct'; members: Map<string, string> }
+type Enum = { kind: 'enum'; members: Map<string, string> }
+type Shape = Struct | Enum
+
+/** Splits a parameter/case list on top-level commas, ignoring `[]`, `()`, `<>`. */
+function splitTopLevel(text: string): string[] {
+  const parts: string[] = []
+  let depth = 0
+  let current = ''
+  for (const char of text) {
+    if (char === '[' || char === '(' || char === '<') depth++
+    else if (char === ']' || char === ')' || char === '>') depth--
+    if (char === ',' && depth === 0) {
+      parts.push(current)
+      current = ''
+    } else current += char
+  }
+  if (current.trim()) parts.push(current)
+  return parts.map((part) => part.trim()).filter(Boolean)
+}
+
+/** `label: Type` → [label, Type]. Splits on the FIRST colon (`[String: String]`). */
+function splitLabelled(part: string): [string, string] | null {
+  const colon = part.indexOf(':')
+  if (colon < 0) return null
+  const label = part.slice(0, colon).trim()
+  // A generated init can carry both an argument label and a parameter name
+  // (`for value: String`); the property name is the last word before the colon.
+  const name = label.split(/\s+/).pop()!
+  return [name, part.slice(colon + 1).trim()]
+}
+
+const DECL =
+  /^\s*(?:(?:public|@frozen|indirect|final)\s+)*(struct|enum)\s+([A-Za-z_]\w*)\s*(?::[^{]*)?\{/
+
+/** Parses every top-level `struct`/`enum` in a Swift file into its member map. */
+function parseSwiftDecls(source: string): Map<string, Shape> {
+  const shapes = new Map<string, Shape>()
+  const lines = source.split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const decl = DECL.exec(lines[i]!)
+    if (!decl) continue
+    const keyword = decl[1]!
+    const name = decl[2]!
+    const members = new Map<string, string>()
+    let depth = 1
+
+    for (let j = i + 1; j < lines.length && depth > 0; j++) {
+      const body = lines[j]!.replace(/\/\/.*$/, '')
+
+      if (depth === 1) {
+        // Stored property: `var name: Type`, but not a computed one (`{` after).
+        const prop =
+          /^\s*(?:public\s+)?var\s+([A-Za-z_]\w*)\s*:\s*([^={]+?)\s*(?:=|$)/.exec(
+            body
+          )
+        if (prop && !/\{\s*$/.test(body)) members.set(prop[1]!, prop[2]!.trim())
+
+        // `case a`, `case a(T)`, `case a, b`
+        const enumCase = /^\s*case\s+(.+)$/.exec(body)
+        if (enumCase && keyword === 'enum') {
+          for (const one of splitTopLevel(enumCase[1]!)) {
+            const withPayload = /^([A-Za-z_]\w*)\s*\((.*)\)$/.exec(one)
+            if (withPayload)
+              members.set(withPayload[1]!, withPayload[2]!.trim())
+            else if (/^[A-Za-z_]\w*$/.test(one)) members.set(one, '')
+          }
+        }
+      }
+
+      for (const char of body) {
+        if (char === '{') depth++
+        else if (char === '}') depth--
+      }
+    }
+
+    shapes.set(name, {
+      kind: keyword === 'struct' ? 'struct' : 'enum',
+      members
+    } as Shape)
+  }
+  return shapes
+}
+
+/**
+ * Reads the real shape of a generated type. Nitro emits three forms: a struct
+ * (memberwise `init`), a string-backed enum (`init?(fromString:)`), and a
+ * variant (a plain `enum` with `first`/`second`/… payload cases).
+ */
+function parseGenerated(name: string): Shape | null {
+  let source: string
+  try {
+    source = readFileSync(join(GENERATED, `${name}.swift`), 'utf8')
+  } catch {
+    return null
+  }
+
+  // Variant enums are declared outright, so the generic parser sees them.
+  const declared = parseSwiftDecls(source).get(name)
+  if (declared && declared.members.size > 0) return declared
+
+  // String-backed enum. Read the case names off the `stringValue` switch, which
+  // spells them out (`case .get: return "GET"`), rather than deriving them from
+  // the JS values — nitrogen's casing rule is not ours to reimplement.
+  if (source.includes('var stringValue: String')) {
+    const members = new Map<string, string>()
+    for (const match of source.matchAll(/case\s+\.(\w+)\s*:/g))
+      members.set(match[1]!, '')
+    return { kind: 'enum', members }
+  }
+
+  const init = /^\s*init\((.*)\)\s*\{/m.exec(source)
+  if (init) {
+    const members = new Map<string, string>()
+    for (const part of splitTopLevel(init[1]!)) {
+      const labelled = splitLabelled(part)
+      if (labelled) members.set(labelled[0], labelled[1])
+    }
+    return { kind: 'struct', members }
+  }
+
+  return null
+}
+
+/**
+ * Sugared and desugared spellings are the same Swift type — nitrogen emits
+ * `Dictionary<String, String>` where the stubs write `[String: String]`.
+ */
+function normalizeType(type: string): string {
+  let previous: string
+  let current = type.replace(/\s+/g, ' ').trim()
+  do {
+    previous = current
+    current = current
+      .replace(/\bDictionary<([^<>]+),\s*([^<>]+)>/g, '[$1: $2]')
+      .replace(/\bArray<([^<>]+)>/g, '[$1]')
+      .replace(/\bOptional<([^<>]+)>/g, '$1?')
+  } while (current !== previous)
+  return current
+}
+
+describe('NitroTypeStubs mirror the generated Nitro types', () => {
+  const stubs = parseSwiftDecls(readFileSync(STUBS, 'utf8'))
+
+  it('parses the stub file', () => {
+    // A parser that silently matches nothing would make every check below pass.
+    expect(stubs.size).toBeGreaterThan(20)
+    expect(stubs.get('Track')?.members.get('src')).toBe('String?')
+  })
+
+  it('stubs only types that Nitro actually generates', () => {
+    const orphans = [...stubs.keys()].filter(
+      (name) => !(name in NOT_GENERATED) && parseGenerated(name) == null
+    )
+    expect(
+      orphans,
+      `Stubbed with no generated counterpart in nitrogen/generated/ios/swift — the type was ` +
+        `renamed or removed from the Nitro spec, so the stub is standing in for nothing:\n` +
+        orphans.join('\n')
+    ).toEqual([])
+  })
+
+  it('declares every stubbed property with the generated type', () => {
+    const drift: string[] = []
+
+    for (const [name, stub] of stubs) {
+      if (name in NOT_GENERATED) continue
+      const real = parseGenerated(name)
+      if (real == null) continue // reported by the previous test
+
+      for (const [member, stubType] of stub.members) {
+        const realType = real.members.get(member)
+        const what = real.kind === 'enum' ? 'case' : 'property'
+        if (realType == null) {
+          drift.push(
+            `${name}.${member}: stub declares a ${what} the generated type does not have`
+          )
+        } else if (normalizeType(realType) !== normalizeType(stubType)) {
+          drift.push(
+            `${name}.${member}: stub \`${stubType || '(no payload)'}\`, ` +
+              `generated \`${realType || '(no payload)'}\``
+          )
+        }
+      }
+    }
+
+    expect(
+      drift,
+      `ios/Model/NitroTypeStubs.swift disagrees with nitrogen/generated/ios/swift. ` +
+        `\`swift test\` compiles against the stub and will not catch this; the app build ` +
+        `compiles against the generated type and will fail. Fix the stub to match:\n` +
+        drift.join('\n')
+    ).toEqual([])
+  })
+
+  it('declares struct members in the generated initializer order', () => {
+    // Name/type parity is not enough: the stub struct's memberwise init must
+    // accept the same ARGUMENT ORDER as the generated labelled init, or shared
+    // sources compile under `swift test` and fail in the app build with
+    // "argument 'x' must precede argument 'y'" (nitrogen flattens `extends`
+    // own-properties-first, which is easy to get backwards — SectionStyle did).
+    // A stub may omit members; the ones it declares must be a subsequence of
+    // the generated order.
+    const misordered: string[] = []
+
+    for (const [name, stub] of stubs) {
+      if (name in NOT_GENERATED || stub.kind !== 'struct') continue
+      const real = parseGenerated(name)
+      if (real == null || real.kind !== 'struct') continue
+
+      const realOrder = [...real.members.keys()]
+      const stubOrder = [...stub.members.keys()].filter((member) =>
+        real.members.has(member)
+      )
+      let cursor = -1
+      for (const member of stubOrder) {
+        const index = realOrder.indexOf(member)
+        if (index < cursor) {
+          misordered.push(
+            `${name}: stub declares [${stubOrder.join(', ')}], ` +
+              `generated init order is [${realOrder.join(', ')}]`
+          )
+          break
+        }
+        cursor = index
+      }
+    }
+
+    expect(
+      misordered,
+      `Stub struct members are out of order relative to the generated init:\n` +
+        misordered.join('\n')
+    ).toEqual([])
+  })
+})

package/src/public-surface.test.ts

@@ -0,0 +1,147 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { describe, it, expect } from 'vitest'
+
+/**
+ * Guard on what `import { … } from 'react-native-audio-browser'` can reach.
+ *
+ * `@internal` hides a value from the published types but not from the bundle:
+ * Metro resolves `"react-native": "src/index"` and compiles the source, where
+ * `stripInternal` never ran. Types are exempt — they have no runtime form.
+ * `CLAUDE.md` in this directory has the full rule.
+ */
+const SRC = join(process.cwd(), 'src')
+const ENTRY = join(SRC, 'index.ts')
+
+const VALUE_KINDS = new Set([
+  'const',
+  'let',
+  'var',
+  'function',
+  'class',
+  'enum'
+])
+
+function resolveModule(fromFile: string, spec: string): string | undefined {
+  const base = resolve(dirname(fromFile), spec.replace(/\.tsx?$/, ''))
+  return [`${base}.ts`, `${base}.tsx`, join(base, 'index.ts')].find(existsSync)
+}
+
+interface Export {
+  name: string
+  file: string
+  internal: boolean
+}
+
+/** Walks the `export *` graph from `entry`, collecting every reachable value export. */
+function collectValueExports(entry: string): Export[] {
+  const found: Export[] = []
+  const seen = new Set<string>()
+
+  const visit = (file: string) => {
+    if (seen.has(file)) return
+    seen.add(file)
+    const source = readFileSync(file, 'utf8')
+
+    for (const [, spec] of source.matchAll(/^export \* from ['"](.+?)['"]/gm)) {
+      const target = resolveModule(file, spec!)
+      if (target) visit(target)
+    }
+
+    const declaration =
+      /^export (?:declare )?(?:async )?(?:abstract )?(const|let|var|function|class|enum) (\w+)/gm
+    for (const match of source.matchAll(declaration)) {
+      if (!VALUE_KINDS.has(match[1]!)) continue
+      // The JSDoc block, if any, is whatever sits directly above the export.
+      const preceding = source.slice(0, match.index)
+      const doc = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/.exec(preceding)?.[0] ?? ''
+      found.push({
+        name: match[2]!,
+        file: relative(SRC, file),
+        internal: /@internal\b/.test(doc)
+      })
+    }
+  }
+
+  visit(entry)
+  return found
+}
+
+describe('public surface', () => {
+  const exports = collectValueExports(ENTRY)
+
+  it('reaches the feature modules at all (the walker still works)', () => {
+    // Cheap canary: if the barrel structure changes shape and the walker stops
+    // resolving, every other assertion here would pass vacuously.
+    expect(exports.map((e) => e.name)).toContain('trackPlaybackTime')
+    expect(exports.length).toBeGreaterThan(100)
+  })
+
+  it('exposes no value marked @internal', () => {
+    const leaked = exports
+      .filter((e) => e.internal)
+      .map((e) => `${e.name}  (${e.file})`)
+    expect(
+      leaked,
+      'Reachable from the package root at runtime despite @internal. Move each ' +
+        'to a module the barrels skip, and import it directly:\n' +
+        leaked.join('\n')
+    ).toEqual([])
+  })
+
+  it('exposes no __-prefixed test hook', () => {
+    const hooks = exports
+      .filter((e) => e.name.startsWith('__'))
+      .map((e) => `${e.name}  (${e.file})`)
+    expect(
+      hooks,
+      'Test-only exports ship to consumers. Drive the unit through a seam it ' +
+        'already has — a mocked native slot, say:\n' +
+        hooks.join('\n')
+    ).toEqual([])
+  })
+
+  it('does not re-export the raw Nitro object', () => {
+    expect(exports.map((e) => e.name)).not.toContain('nativeBrowser')
+  })
+
+  it('every public module is covered by the typedoc entry points', () => {
+    // The API reference documents entryPoints, not the export graph — a public
+    // module missing from website/typedoc.json ships undocumented.
+    const config = JSON.parse(
+      readFileSync(join(process.cwd(), 'website', 'typedoc.json'), 'utf8')
+    ) as { entryPoints: string[] }
+    const entries = config.entryPoints.map(
+      (glob) =>
+        new RegExp(
+          '^' +
+            glob
+              .replace(/^\.\.\/src\//, '')
+              .replace(/[.]/g, '\\.')
+              .replace(/\*/g, '[^/]+') +
+            '$'
+        )
+    )
+    const covered = (file: string): boolean => {
+      if (entries.some((e) => e.test(file))) return true
+      // A directory barrel entry (…/index.ts) documents what it re-exports.
+      const dir = file.split('/').slice(0, -1)
+      while (dir.length > 0) {
+        if (entries.some((e) => e.test([...dir, 'index.ts'].join('/'))))
+          return true
+        dir.pop()
+      }
+      return false
+    }
+    const uncovered = [...new Set(exports.map((e) => e.file))].filter(
+      (file) => !covered(file)
+    )
+    expect(
+      uncovered,
+      'Exported to consumers but absent from the API reference. Add each ' +
+        'module (or its directory barrel) to website/typedoc.json ' +
+        'entryPoints:\n' +
+        uncovered.join('\n')
+    ).toEqual([])
+  })
+})

package/src/specs/audio-browser.nitro.ts

@@ -115,7 +115,7 @@ export interface AudioBrowser extends HybridObject<{
   tabs: Track[] | undefined
   navigatePath(path: string): void
   navigateTrack(track: Track): void
-  onSearch(query: string): Promise<Track[]>
+  search(query: string): Promise<Track[]>
   getContent(): ResolvedTrack | undefined
   onPathChanged: (path: string) => void
   onContentChanged: (content: ResolvedTrack | undefined) => void
@@ -229,9 +229,10 @@ export interface AudioBrowser extends HybridObject<{
   seekTo(position: number): void
   seekBy(offset: number): void
   /**
-   * Jump to the live edge of the current track. No-op for non-live tracks.
-   * Live with a seekable window (HLS): seeks to the window end. Live without a
-   * window (non-seekable, e.g. ICY): reconnects to rejoin live.
+   * Jump to the live edge of the current track; no-op unless the track
+   * declares `live: true`. A stream with a seekable live window (HLS) seeks
+   * to the window's edge; a non-seekable stream (e.g. ICY radio) reconnects
+   * to rejoin live — an expired URL re-resolves through `media.resolve`.
    */
   seekToLiveEdge(): void
   setVolume(level: number): void

package/src/style-resolution.test.ts

@@ -0,0 +1,210 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Completeness guards for the style declaration block (ADR 0011) — the checks
+ * Nitro's `extends`-flattening took out of the type system, in two parts:
+ * every key must be *resolved* by each platform's `StyleResolver`, and every
+ * key must be *accounted for* by each platform's `InertStyleDiagnostic`.
+ *
+ * Part one — inheritance completeness.
+ *
+ * `SectionStyle extends TrackStyle` in the spec, but Nitro flattens `extends`
+ * into independent structs on every platform — so nothing in any type system
+ * forces a platform's `StyleResolver` to read a newly added style key. A key
+ * the resolver forgets is silently dead: declared by consumers, decoded on the
+ * wire, never rendered. This test is the compile-time check the flattening
+ * took away:
+ *
+ * - every `SectionStyle` key must appear in each platform's
+ *   `sectionStyle(section, page)` merge;
+ * - every inherited `TrackStyle` key must appear in each platform's
+ *   `trackStyle(track, section)` merge;
+ * - `display` is positional (the deny-list): the track merge must resolve it
+ *   to nil/null and must not read it from any level.
+ */
+
+const ROOT = process.cwd()
+
+const RESOLVERS = [
+  {
+    file: 'ios/Browser/StyleResolver.swift',
+    sectionMarker: 'static func sectionStyle',
+    trackMarker: 'static func trackStyle',
+    positionalNil: 'display: nil'
+  },
+  {
+    file: 'android/src/main/java/com/audiobrowser/browser/StyleResolver.kt',
+    sectionMarker: 'fun sectionStyle',
+    trackMarker: 'fun trackStyle',
+    positionalNil: 'display = null'
+  }
+]
+
+/** Keys the spec deliberately excludes from item inheritance. */
+const POSITIONAL = ['display']
+
+function interfaceKeys(source: string, name: string): string[] {
+  const start = source.indexOf(`export interface ${name} `)
+  expect(
+    start,
+    `interface ${name} not found in browser-nodes.ts`
+  ).toBeGreaterThan(-1)
+  const end = source.indexOf('\n}', start)
+  const body = source.slice(start, end)
+  return [...body.matchAll(/^ {2}(\w+)\??:/gm)].flatMap((match) =>
+    match[1] === undefined ? [] : [match[1]]
+  )
+}
+
+/**
+ * The function's text from `marker` to the next function declaration (or end
+ * of file) — brace-agnostic, since Kotlin expression bodies have no braces.
+ */
+function functionBody(source: string, marker: string, file: string): string {
+  const start = source.indexOf(marker)
+  expect(start, `${marker} not found in ${file}`).toBeGreaterThan(-1)
+  const rest = source.slice(start + marker.length)
+  const next = rest.search(/\n\s*(?:static func|func|fun)\s/)
+  return marker + (next === -1 ? rest : rest.slice(0, next))
+}
+
+/** Comment-free view, so prose about a key doesn't count as reading it. */
+function stripComments(code: string): string {
+  return code
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .split('\n')
+    .map((line) => line.replace(/\/\/.*$/, ''))
+    .join('\n')
+}
+
+const nodes = readFileSync(
+  join(ROOT, 'src', 'types', 'browser-nodes.ts'),
+  'utf8'
+)
+const trackKeys = interfaceKeys(nodes, 'TrackStyle')
+const sectionKeys = [...trackKeys, ...interfaceKeys(nodes, 'SectionStyle')]
+const inheritedKeys = trackKeys.filter((key) => !POSITIONAL.includes(key))
+
+describe('style block shape', () => {
+  it('has the positional key and at least one inherited key', () => {
+    expect(trackKeys).toContain('display')
+    expect(inheritedKeys.length).toBeGreaterThan(0)
+  })
+})
+
+for (const resolver of RESOLVERS) {
+  describe(resolver.file, () => {
+    const source = readFileSync(join(ROOT, resolver.file), 'utf8')
+    const sectionBody = stripComments(
+      functionBody(source, resolver.sectionMarker, resolver.file)
+    )
+    const trackBody = stripComments(
+      functionBody(source, resolver.trackMarker, resolver.file)
+    )
+
+    // Containment of `holder?.key` for BOTH holders — `display =
+    // section?.display` with the page half dropped must fail — AND in
+    // precedence order: the narrower holder must be read first, or the
+    // scope-override/inheritance direction is inverted (`page ?? section`
+    // would pass a bare containment check).
+    it.each(sectionKeys)('sectionStyle merges %s (section ?? page)', (key) => {
+      const section = sectionBody.indexOf(`section?.${key}`)
+      const page = sectionBody.indexOf(`page?.${key}`)
+      expect(section, `section?.${key} not read`).toBeGreaterThan(-1)
+      expect(page, `page?.${key} not read`).toBeGreaterThan(-1)
+      expect(section, `section?.${key} must precede page?.${key}`).toBeLessThan(
+        page
+      )
+    })
+
+    it.each(inheritedKeys)(
+      'trackStyle inherits %s (track ?? section)',
+      (key) => {
+        const track = trackBody.indexOf(`track?.${key}`)
+        const section = trackBody.indexOf(`section?.${key}`)
+        expect(track, `track?.${key} not read`).toBeGreaterThan(-1)
+        expect(section, `section?.${key} not read`).toBeGreaterThan(-1)
+        expect(
+          track,
+          `track?.${key} must precede section?.${key}`
+        ).toBeLessThan(section)
+      }
+    )
+
+    it('trackStyle excludes the positional display (deny-list)', () => {
+      expect(trackBody).toContain(resolver.positionalNil)
+      // The nil assignment must be the ONLY mention: reading display from any
+      // level here would item-inherit a positional key.
+      const mentions = trackBody.match(/display/g) ?? []
+      expect(mentions).toHaveLength(1)
+    })
+  })
+}
+
+/**
+ * Part two — diagnostic completeness.
+ *
+ * The block model traded compile-time invalid-combination errors for
+ * inertness, and the dev-mode `InertStyleDiagnostic` is the recovery. It is
+ * exposed to the same flattening problem as the resolvers, one level up: a
+ * key added to the spec has no type-system tie to the diagnostic's rule set,
+ * so a property could ship whose inert combinations nobody is warned about.
+ *
+ * Each platform therefore dispositions the whole vocabulary — every key is a
+ * `Property` with an inertness rule, `alwaysRenderable`, or `positional` —
+ * and this test reads those three declarations and asserts set equality with
+ * the spec, both directions: a new key must be dispositioned, and a key
+ * deleted from the spec must not linger in the rule set.
+ */
+const DIAGNOSTICS = [
+  {
+    file: 'ios/Browser/InertStyleDiagnostic.swift',
+    // `case gridWrap`, up to the first member after the case list.
+    ruled: (source: string) =>
+      keysIn(
+        source,
+        /enum Property[\s\S]*?var isItemProperty/,
+        /^\s*case (\w+)$/gm
+      )
+  },
+  {
+    file: 'android/src/main/java/com/audiobrowser/browser/InertStyleDiagnostic.kt',
+    // `GRID_WRAP("gridWrap", …)`, up to the `;` that ends the entry list.
+    ruled: (source: string) =>
+      keysIn(source, /enum class Property[\s\S]*?;/, /\w+\("(\w+)"/g)
+  }
+]
+
+/** The capture group of every `pattern` match within the first `region`. */
+function keysIn(source: string, region: RegExp, pattern: RegExp): string[] {
+  const found = region.exec(source)
+  expect(found, `region ${region} not found`).not.toBeNull()
+  return [...found![0].matchAll(pattern)].flatMap((match) =>
+    match[1] === undefined ? [] : [match[1]]
+  )
+}
+
+for (const diagnostic of DIAGNOSTICS) {
+  describe(diagnostic.file, () => {
+    // Comment-free, so prose naming a key doesn't pass for dispositioning it.
+    const source = stripComments(
+      readFileSync(join(ROOT, diagnostic.file), 'utf8')
+    )
+    // The two lists are spelled `alwaysRenderable`/`positional` in Swift and
+    // SCREAMING_CASE in Kotlin; both hold bare string literals.
+    const listed = [
+      ...source.matchAll(
+        /(?:alwaysRenderable|ALWAYS_RENDERABLE|positional|POSITIONAL)\s*=[^\n]*/gi
+      )
+    ].flatMap((match) =>
+      [...match[0].matchAll(/"(\w+)"/g)].map((key) => key[1])
+    )
+
+    it('dispositions every key of the block, and only those', () => {
+      const dispositioned = [...diagnostic.ruled(source), ...listed]
+      expect(new Set(dispositioned)).toEqual(new Set(sectionKeys))
+    })
+  })
+}