chore: import upstream snapshot with attribution

apps/sim/hooks/use-stable-flag.test.ts

@@ -0,0 +1,163 @@
+/**
+ * @vitest-environment node
+ *
+ * Tests for the `createStableFlagController` state machine behind `useStableFlag`.
+ * The controller is framework-agnostic so the anti-flicker timing can be driven
+ * with fake timers and no DOM; the thin React wrapper is covered by manual QA.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createStableFlagController } from '@/hooks/use-stable-flag'
+
+const DELAY_MS = 2000
+const MIN_VISIBLE_MS = 1500
+
+function setup(options = { delayMs: DELAY_MS, minVisibleMs: MIN_VISIBLE_MS }) {
+  const states: boolean[] = []
+  let active = false
+  const controller = createStableFlagController((next) => {
+    active = next
+    states.push(next)
+  }, options)
+  return {
+    controller,
+    states,
+    get active() {
+      return active
+    },
+  }
+}
+
+describe('createStableFlagController', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.clearAllTimers()
+    vi.useRealTimers()
+  })
+
+  it('suppresses a blip that heals before the delay (flash-on)', () => {
+    const probe = setup()
+
+    probe.controller.setValue(true)
+    vi.advanceTimersByTime(DELAY_MS - 1)
+    probe.controller.setValue(false)
+    vi.advanceTimersByTime(10_000)
+
+    expect(probe.states).toEqual([])
+    expect(probe.active).toBe(false)
+  })
+
+  it('does not turn on one tick before the delay boundary', () => {
+    const probe = setup()
+
+    probe.controller.setValue(true)
+    vi.advanceTimersByTime(DELAY_MS - 1)
+
+    expect(probe.active).toBe(false)
+    expect(probe.states).toEqual([])
+  })
+
+  it('turns on exactly at the delay boundary', () => {
+    const probe = setup()
+
+    probe.controller.setValue(true)
+    vi.advanceTimersByTime(DELAY_MS)
+
+    expect(probe.states).toEqual([true])
+    expect(probe.active).toBe(true)
+  })
+
+  it('holds the flag on for the minimum-visible window (flash-off)', () => {
+    const probe = setup()
+
+    probe.controller.setValue(true)
+    vi.advanceTimersByTime(DELAY_MS) // shown
+    expect(probe.active).toBe(true)
+
+    // Value clears almost immediately after showing.
+    vi.advanceTimersByTime(100)
+    probe.controller.setValue(false)
+    expect(probe.active).toBe(true) // still held
+
+    vi.advanceTimersByTime(MIN_VISIBLE_MS - 100 - 1)
+    expect(probe.active).toBe(true)
+
+    vi.advanceTimersByTime(1)
+    expect(probe.active).toBe(false)
+    expect(probe.states).toEqual([true, false])
+  })
+
+  it('clears immediately when the value has already been visible past the minimum', () => {
+    const probe = setup()
+
+    probe.controller.setValue(true)
+    vi.advanceTimersByTime(DELAY_MS)
+    vi.advanceTimersByTime(MIN_VISIBLE_MS + 500) // well past the floor
+    probe.controller.setValue(false)
+
+    expect(probe.active).toBe(false)
+    expect(probe.states).toEqual([true, false])
+  })
+
+  it('keeps the flag on through a flap while held, without re-delaying', () => {
+    const probe = setup()
+
+    probe.controller.setValue(true)
+    vi.advanceTimersByTime(DELAY_MS) // shown
+    probe.controller.setValue(false) // schedules hide
+    vi.advanceTimersByTime(500)
+    probe.controller.setValue(true) // reconnect flaps back before hide fires
+
+    vi.advanceTimersByTime(10_000)
+    expect(probe.active).toBe(true)
+    expect(probe.states).toEqual([true])
+  })
+
+  it('is idempotent on repeated setValue(true) — schedules a single show', () => {
+    const probe = setup()
+
+    probe.controller.setValue(true)
+    vi.advanceTimersByTime(500)
+    probe.controller.setValue(true)
+    probe.controller.setValue(true)
+
+    vi.advanceTimersByTime(DELAY_MS - 500)
+    expect(probe.states).toEqual([true]) // exactly one transition, fired at the original deadline
+  })
+
+  it('dispose cancels a pending show', () => {
+    const probe = setup()
+
+    probe.controller.setValue(true)
+    probe.controller.dispose()
+    vi.advanceTimersByTime(10_000)
+
+    expect(probe.states).toEqual([])
+  })
+
+  it('dispose cancels a pending hide', () => {
+    const probe = setup()
+
+    probe.controller.setValue(true)
+    vi.advanceTimersByTime(DELAY_MS)
+    probe.controller.setValue(false) // schedules hide within min-visible window
+    probe.controller.dispose()
+    vi.advanceTimersByTime(10_000)
+
+    expect(probe.states).toEqual([true]) // hide never fired
+  })
+
+  it('with zero options, mirrors the value on the next tick', () => {
+    const probe = setup({ delayMs: 0, minVisibleMs: 0 })
+
+    probe.controller.setValue(true)
+    vi.advanceTimersByTime(0)
+    expect(probe.active).toBe(true)
+
+    probe.controller.setValue(false)
+    expect(probe.active).toBe(false)
+    expect(probe.states).toEqual([true, false])
+  })
+})