react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.20

package/src/features/remoteControls.ts

@@ -53,90 +53,11 @@ export interface RemoteSkipEvent {
   index: number
 }
 
-// MARK: - Default Handlers
-
-// Install remote control handlers with default behavior immediately when module loads
-// Custom handlers can override the defaults using handleRemote* functions
-
-// Basic playback controls
-// AudioBrowser.onRemotePlay(() => {
-//   const customHandler = customHandlers.get('play')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     play()
-//   }
-// })
-
-// AudioBrowser.onRemotePause(() => {
-//   const customHandler = customHandlers.get('pause')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     pause()
-//   }
-// })
-
-// AudioBrowser.onRemoteNext(() => {
-//   const customHandler = customHandlers.get('next')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     skipToNext()
-//   }
-// })
-
-// AudioBrowser.onRemotePrevious(() => {
-//   const customHandler = customHandlers.get('previous')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     skipToPrevious()
-//   }
-// })
-
-// AudioBrowser.onRemoteStop(() => {
-//   const customHandler = customHandlers.get('stop')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     stop()
-//   }
-// })
-
-// // Seek controls
-// AudioBrowser.onRemoteSeek((event: any) => {
-//   const customHandler = customHandlers.get('seek')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekTo(event.position)
-//   }
-// })
-
-// AudioBrowser.onRemoteJumpForward((event: any) => {
-//   const customHandler = customHandlers.get('jumpForward')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekBy(event.interval)
-//   }
-// })
-
-// AudioBrowser.onRemoteJumpBackward((event: any) => {
-//   const customHandler = customHandlers.get('jumpBackward')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekBy(-event.interval)
-//   }
-// })
-
 // MARK: - Handler Override Functions
 //
 // Use these functions when you want to OVERRIDE the default remote control behavior.
 // These will replace the default handlers with your custom logic.
-// If you just want to listen to events for debugging/logging, use the onRemote* functions below.
+// If you just want to listen to events for debugging/logging, use the onRemote* emitters below.
 
 /**
  * Sets a custom handler for remote play events, overriding the default behavior.
@@ -210,7 +131,7 @@ export function handleRemoteJumpBackward(
 
 // MARK: - Event Callbacks (for listening/debugging only)
 //
-// Use these functions when you want to LISTEN to remote control events without overriding
+// Use these emitters when you want to LISTEN to remote control events without overriding
 // the default behavior. These are perfect for logging, analytics, or debugging.
 // Multiple listeners can be registered for the same event.
 // To override the default behavior, use the handleRemote* functions above.
@@ -218,7 +139,7 @@ export function handleRemoteJumpBackward(
 /**
  * Subscribes to remote jump backward events.
  * @param callback - Called when the user presses the jump backward button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteJumpBackward =
   LazyNativeEmitter.emitterize<RemoteJumpBackwardEvent>(
@@ -228,7 +149,7 @@ export const onRemoteJumpBackward =
 /**
  * Subscribes to remote jump forward events.
  * @param callback - Called when the user presses the jump forward button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteJumpForward =
   LazyNativeEmitter.emitterize<RemoteJumpForwardEvent>(
@@ -238,7 +159,7 @@ export const onRemoteJumpForward =
 /**
  * Subscribes to remote next events.
  * @param callback - Called when the user presses the next track button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemoteNext = cb)
@@ -247,7 +168,7 @@ export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote pause events.
  * @param callback - Called when the user presses the pause button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePause = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePause = cb)
@@ -256,7 +177,7 @@ export const onRemotePause = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote play events.
  * @param callback - Called when the user presses the play button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePlay = cb)
@@ -265,7 +186,7 @@ export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote play ID events (Android only).
  * @param callback - Called when the user selects a track from an external device
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
   (cb) => (nativeBrowser.onRemotePlayId = cb)
@@ -274,7 +195,7 @@ export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
 /**
  * Subscribes to remote play search events (Android only).
  * @param callback - Called when the user searches for a track (usually voice search)
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlaySearch =
   LazyNativeEmitter.emitterize<RemotePlaySearchEvent>(
@@ -284,7 +205,7 @@ export const onRemotePlaySearch =
 /**
  * Subscribes to remote previous events.
  * @param callback - Called when the user presses the previous track button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePrevious = cb)
@@ -293,7 +214,7 @@ export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote seek events.
  * @param callback - Called when the user changes the position of the timeline
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteSeek = LazyNativeEmitter.emitterize<RemoteSeekEvent>(
   (cb) => (nativeBrowser.onRemoteSeek = cb)
@@ -302,7 +223,7 @@ export const onRemoteSeek = LazyNativeEmitter.emitterize<RemoteSeekEvent>(
 /**
  * Subscribes to remote skip events (Android only).
  * @param callback - Called when the user presses the skip button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
   (cb) => (nativeBrowser.onRemoteSkip = cb)
@@ -311,7 +232,7 @@ export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
 /**
  * Subscribes to remote stop events.
  * @param callback - Called when the user presses the stop button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteStop = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemoteStop = cb)

package/src/features/sleepTimer.test.ts

@@ -0,0 +1,172 @@
+/** @vitest-environment happy-dom */
+
+import { renderHook, act, cleanup } from '@testing-library/react'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import type { SleepTimer } from './sleepTimer'
+
+const native = vi.hoisted(() => ({
+  getSleepTimer: vi.fn<() => SleepTimer>(() => null),
+  // The single callback slot `NativeUpdatedValue` claims at module load.
+  onSleepTimerChanged: undefined as ((timer: SleepTimer) => void) | undefined
+}))
+
+vi.mock('../native', () => ({ nativeBrowser: native }))
+
+const { onSleepTimerChanged, useSleepTimer, useSleepTimerActive } =
+  await import('./sleepTimer')
+
+/** Push a value the way native would. */
+const fire = (timer: SleepTimer) =>
+  act(() => native.onSleepTimerChanged?.(timer))
+
+/**
+ * The emitter is a module-level singleton, so `lastValue` outlives each test.
+ * `undefined` is its pre-native state and distinct from `null`, which is a real
+ * value meaning "no timer" — the distinction the re-sync gate turns on.
+ */
+beforeEach(() => {
+  onSleepTimerChanged.lastValue = undefined
+  native.getSleepTimer.mockReturnValue(null)
+})
+afterEach(cleanup)
+
+describe('useSleepTimerActive', () => {
+  it('reads the getter when nothing has fired yet', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(true)
+  })
+
+  it('tracks timers being set and cleared', () => {
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(false)
+    fire({ time: Date.now() + 60_000 })
+    expect(result.current).toBe(true)
+    fire(null)
+    expect(result.current).toBe(false)
+  })
+
+  it('treats an end-of-track timer as active', () => {
+    const { result } = renderHook(() => useSleepTimerActive())
+    fire({ sleepWhenPlayedToEnd: true })
+    expect(result.current).toBe(true)
+  })
+
+  // The regression from f7a25040. The getter ran during render and saw a live
+  // timer; the clear landed before the effect subscribed. Without the re-sync
+  // the UI shows a running timer that is already gone — permanently, since
+  // nothing reads it again until the next native event.
+  it('re-syncs a clear that landed between the render read and the effect', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    onSleepTimerChanged.lastValue = null
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(false)
+  })
+
+  // The gate is `!== undefined`, not truthiness: `undefined` means native has
+  // never spoken, so the getter's answer must stand.
+  it('keeps the getter value when native has not fired at all', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(true)
+  })
+
+  it('stops tracking after unmount', () => {
+    const { result, unmount } = renderHook(() => useSleepTimerActive())
+    unmount()
+    fire({ time: Date.now() + 60_000 })
+    expect(result.current).toBe(false)
+  })
+})
+
+describe('useSleepTimer', () => {
+  it('is undefined when no timer is set', () => {
+    const { result } = renderHook(() => useSleepTimer())
+    expect(result.current).toBeUndefined()
+  })
+
+  it('reports secondsLeft for a time-based timer', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 30_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      expect(result.current).toEqual({
+        time: 1_000_000_030_000,
+        secondsLeft: 30
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('passes an end-of-track timer through without secondsLeft', () => {
+    const { result } = renderHook(() => useSleepTimer())
+    fire({ sleepWhenPlayedToEnd: true })
+    expect(result.current).toEqual({ sleepWhenPlayedToEnd: true })
+  })
+
+  it('counts down as time passes', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 5_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      expect(result.current).toMatchObject({ secondsLeft: 5 })
+      act(() => {
+        vi.advanceTimersByTime(2_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 3 })
+      act(() => {
+        vi.advanceTimersByTime(3_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('stops the countdown once it reaches zero', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 2_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      act(() => {
+        vi.advanceTimersByTime(2_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+      // Clamped at zero rather than running negative.
+      act(() => {
+        vi.advanceTimersByTime(10_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('does not tick while inactive', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+      const { result } = renderHook(() => useSleepTimer({ inactive: true }))
+      expect(result.current).toMatchObject({ secondsLeft: 60 })
+      act(() => {
+        vi.advanceTimersByTime(10_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 60 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  // Same race as useSleepTimerActive, and the reason both hooks carry the gate.
+  it('re-syncs a clear that landed between the render read and the effect', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    onSleepTimerChanged.lastValue = null
+    const { result } = renderHook(() => useSleepTimer())
+    expect(result.current).toBeUndefined()
+  })
+})

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([])
+  })
+})