@pyreon/core 0.16.0 → 0.19.0

package/src/jsx-runtime.ts

@@ -25,19 +25,57 @@ export function jsx(
   props: Props & { children?: VNodeChild | VNodeChild[] },
   key?: string | number | null,
 ): VNode {
-  const { children, ...rest } = props
-  const propsWithKey = (key != null ? { ...rest, key } : rest) as Props
+  // Build the destructured props object by copying own property
+  // DESCRIPTORS, not values. Compiler-emitted reactive props (`_rp(() =>
+  // signal())` wrappers converted to getter properties by
+  // `makeReactiveProps` in mount.ts) MUST survive the destructure with
+  // their getters intact. A plain `{ children, ...rest } = props`
+  // destructure fires every getter on `props` and stores the resolved
+  // value, breaking signal-driven reactivity for any downstream
+  // consumer that reads `props.x` in a tracking scope.
+  //
+  // Fast path: if `props` has no own property descriptors with `get`
+  // accessors, we can use the original value-copy shape (cheap object
+  // literal allocation). This is the 99% case — only framework wrappers
+  // (rocketstyle attrs HOC, Wrapper, styled) and direct signal props
+  // produce getter-shaped descriptors.
+  const descriptors = Object.getOwnPropertyDescriptors(props)
+  let hasGetter = false
+  for (const k in descriptors) {
+    if (descriptors[k]!.get) {
+      hasGetter = true
+      break
+    }
+  }
+  const children = props.children
+
+  if (!hasGetter) {
+    const { children: _ignored, ...rest } = props
+    const propsWithKey = (key != null ? { ...rest, key } : rest) as Props
+    if (typeof type === 'function') {
+      const componentProps = children !== undefined ? { ...propsWithKey, children } : propsWithKey
+      return h(type, componentProps)
+    }
+    const childArray = children === undefined ? [] : Array.isArray(children) ? children : [children]
+    return h(type, propsWithKey, ...(childArray as VNodeChild[]))
+  }
+
+  // Slow path: at least one getter descriptor present — preserve
+  // descriptors during the destructure.
+  const propsWithKey: Record<string, unknown> = {}
+  for (const k in descriptors) {
+    if (k === 'children') continue
+    Object.defineProperty(propsWithKey, k, descriptors[k]!)
+  }
+  if (key != null) propsWithKey.key = key as unknown
 
   if (typeof type === 'function') {
-    // Component: keep children in props.children so the component function can access them.
-    // Children must NOT be spread as h() rest args because mountComponent only passes vnode.props.
-    const componentProps = children !== undefined ? { ...propsWithKey, children } : propsWithKey
-    return h(type, componentProps)
+    if (children !== undefined) propsWithKey.children = children
+    return h(type, propsWithKey as Props)
   }
 
-  // DOM element or symbol (Fragment, ForSymbol): children go in vnode.children
   const childArray = children === undefined ? [] : Array.isArray(children) ? children : [children]
-  return h(type, propsWithKey, ...(childArray as VNodeChild[]))
+  return h(type, propsWithKey as Props, ...(childArray as VNodeChild[]))
 }
 
 // jsxs is called when there are multiple static children — same signature

package/src/lifecycle.ts

@@ -59,12 +59,14 @@ function captureCallSite(): string {
 function warnOutsideSetup(hookName: string): void {
   if (__DEV__ && !_current) {
     const callSite = captureCallSite()
-    const location = callSite ? `\n  Called from: ${callSite}` : ''
+    // Local name must NOT shadow the `location` browser global (poor
+    // hygiene + trips SSR static analysis into a false positive).
+    const callSiteSuffix = callSite ? `\n  Called from: ${callSite}` : ''
     // oxlint-disable-next-line no-console
     console.warn(
       `[Pyreon] ${hookName}() called outside component setup. ` +
         "Lifecycle hooks must be called synchronously during a component's setup function." +
-        location +
+        callSiteSuffix +
         (hookName === 'onUnmount'
           ? '\n  Hint: `provide()` internally calls onUnmount(). If you use provide(), ensure it runs during synchronous component setup — not inside effects, callbacks, or after awaits.'
           : ''),

package/src/props.ts

@@ -140,6 +140,65 @@ export function _rp<T>(fn: () => T): () => T {
   return fn
 }
 
+/**
+ * Wrap a JSX spread source so its getter-shaped reactive props survive
+ * the JS-level object spread that esbuild's automatic JSX runtime emits
+ * for `<Comp {...source}>`.
+ *
+ * Without this wrapper, esbuild compiles `<Comp {...source}>` to
+ * `jsx(Comp, { ...source })` — and JS spread fires every getter on
+ * `source`, storing the resolved values as plain data properties. Any
+ * compiler-emitted reactive prop (`_rp(() => signal())` converted to a
+ * getter by `makeReactiveProps`) on `source` is collapsed to its
+ * initial value before the receiving component ever sees it.
+ *
+ * `_wrapSpread(source)` walks `source`'s own keys via `Reflect.ownKeys`
+ * (no getter firing) and returns a new object whose values are
+ * `_rp`-branded thunks `() => source[key]`. When `{ ..._wrapSpread(s) }`
+ * is spread by esbuild, the thunks are stored as plain data property
+ * values (no getters to fire), then `makeReactiveProps` in `mount.ts`
+ * converts the brands back into getters that lazily read from the
+ * original `source` — preserving the reactive subscription end-to-end.
+ *
+ * Fast path: when `source` has no getter descriptors, return the
+ * source object unchanged. JS spread will work correctly in that case
+ * because there's nothing reactive to preserve. Saves N thunk
+ * allocations per component render in the 99% case.
+ *
+ * Emitted by the compiler — not generally meant for hand-written code.
+ */
+export function _wrapSpread(
+  source: Record<string, unknown> | null | undefined,
+): Record<string, unknown> | null | undefined {
+  if (!source || typeof source !== 'object') return source
+  const descriptors = Object.getOwnPropertyDescriptors(source)
+  let hasGetter = false
+  for (const k in descriptors) {
+    if (descriptors[k]!.get) {
+      hasGetter = true
+      break
+    }
+  }
+  if (!hasGetter) return source
+
+  const result: Record<string, unknown> = {}
+  // Reflect.ownKeys covers symbol keys too — REACTIVE_PROP brands and
+  // other framework symbols must round-trip through the wrap.
+  for (const key of Reflect.ownKeys(source)) {
+    const desc = descriptors[key as string]
+    if (!desc) continue
+    if (desc.get) {
+      const fn: () => unknown = () => source[key as string]
+      ;(fn as unknown as Record<symbol, boolean>)[REACTIVE_PROP] = true
+      result[key as string] = fn
+    } else {
+      // Static data property — copy through as-is.
+      result[key as string] = desc.value
+    }
+  }
+  return result
+}
+
 /**
  * Convert compiler-emitted `_rp(() => expr)` prop values into getter properties.
  *

package/src/telemetry.ts

@@ -16,6 +16,13 @@
  * })
  */
 
+import { getReactiveTrace, type ReactiveTraceEntry } from '@pyreon/reactivity'
+
+// Bundler-agnostic dev gate (see pyreon/no-process-dev-gate).
+const __DEV__ = process.env.NODE_ENV !== 'production'
+
+export type { ReactiveTraceEntry }
+
 export interface ErrorContext {
   /** Component function name, "Anonymous", or "Effect" for reactive effects */
   component: string
@@ -27,6 +34,22 @@ export interface ErrorContext {
   timestamp: number
   /** Component props at the time of the error */
   props?: Record<string, unknown>
+  /**
+   * The last N signal writes (chronological, oldest → newest) leading
+   * up to the error — the causal sequence of reactive state changes,
+   * not a point-in-time snapshot. Each entry is `{ name, prev, next,
+   * timestamp }` with `prev` / `next` as bounded string previews.
+   *
+   * Populated automatically in development from `@pyreon/reactivity`'s
+   * dev-only ring buffer. **`undefined` in production** — the recorder
+   * feeding the buffer tree-shakes out of prod bundles, so the cost is
+   * zero and the field is simply absent.
+   *
+   * For a signal framework this answers the first question a crash
+   * raises — "what reactive state changed in the run-up?" — that the
+   * thrown value + stack alone can't.
+   */
+  reactiveTrace?: ReactiveTraceEntry[]
 }
 
 export type ErrorHandler = (ctx: ErrorContext) => void
@@ -56,6 +79,20 @@ export function registerErrorHandler(handler: ErrorHandler): () => void {
  * Existing console.error calls are preserved; this is additive.
  */
 export function reportError(ctx: ErrorContext): void {
+  // Enrich with the recent-signal-write trace so every handler (Sentry,
+  // Datadog, console) gets the causal reactive sequence for free. Only
+  // when the caller didn't already supply one, and only in dev — the
+  // gate lets the `getReactiveTrace` call (and the buffer behind it)
+  // tree-shake out of production. A throwing/empty trace must never
+  // block error reporting, so it's best-effort.
+  if (__DEV__ && ctx.reactiveTrace === undefined) {
+    try {
+      const trace = getReactiveTrace()
+      if (trace.length > 0) ctx.reactiveTrace = trace
+    } catch {
+      // Trace capture is diagnostic — never let it swallow the real error.
+    }
+  }
   for (const h of _handlers) {
     try {
       h(ctx)

package/src/tests/compat-shared.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest'
+import { mapCompatDomProps, shallowEqualProps } from '../compat-shared'
+
+describe('shallowEqualProps', () => {
+  it('equal for same-key same-value objects', () => {
+    expect(shallowEqualProps({ a: 1, b: 'x' }, { a: 1, b: 'x' })).toBe(true)
+  })
+
+  it('not equal when a value differs', () => {
+    expect(shallowEqualProps({ a: 1 }, { a: 2 })).toBe(false)
+  })
+
+  it('not equal when key counts differ', () => {
+    expect(shallowEqualProps({ a: 1 }, { a: 1, b: 2 })).toBe(false)
+  })
+
+  it('uses Object.is semantics (NaN equal, ±0 distinct)', () => {
+    expect(shallowEqualProps({ n: NaN }, { n: NaN })).toBe(true)
+    expect(shallowEqualProps({ z: 0 }, { z: -0 })).toBe(false)
+  })
+
+  it('empty objects are equal', () => {
+    expect(shallowEqualProps({}, {})).toBe(true)
+  })
+})
+
+describe('mapCompatDomProps', () => {
+  it('no-op for component (non-string) type', () => {
+    const Comp = () => null
+    const p: Record<string, unknown> = { className: 'x', htmlFor: 'y' }
+    mapCompatDomProps(p, Comp)
+    expect(p).toEqual({ className: 'x', htmlFor: 'y' })
+  })
+
+  it('className → class, htmlFor → for', () => {
+    const p: Record<string, unknown> = { className: 'btn', htmlFor: 'email' }
+    mapCompatDomProps(p, 'label')
+    expect(p).toEqual({ class: 'btn', for: 'email' })
+  })
+
+  it('onChange → onInput on input/textarea/select', () => {
+    for (const tag of ['input', 'textarea', 'select']) {
+      const fn = () => {}
+      const p: Record<string, unknown> = { onChange: fn }
+      mapCompatDomProps(p, tag)
+      expect(p).toEqual({ onInput: fn })
+    }
+  })
+
+  it('onChange does not clobber an explicit onInput', () => {
+    const onChange = () => {}
+    const onInput = () => {}
+    const p: Record<string, unknown> = { onChange, onInput }
+    mapCompatDomProps(p, 'input')
+    expect(p).toEqual({ onInput })
+  })
+
+  it('onChange left alone on non-form elements', () => {
+    const onChange = () => {}
+    const p: Record<string, unknown> = { onChange }
+    mapCompatDomProps(p, 'div')
+    expect(p).toEqual({ onChange })
+  })
+
+  it('autoFocus → autofocus', () => {
+    const p: Record<string, unknown> = { autoFocus: true }
+    mapCompatDomProps(p, 'input')
+    expect(p).toEqual({ autofocus: true })
+  })
+
+  it('defaultValue/defaultChecked → value/checked only when uncontrolled', () => {
+    const a: Record<string, unknown> = { defaultValue: 'd', defaultChecked: true }
+    mapCompatDomProps(a, 'input')
+    expect(a).toEqual({ value: 'd', checked: true })
+
+    const b: Record<string, unknown> = {
+      defaultValue: 'd',
+      value: 'controlled',
+      defaultChecked: true,
+      checked: false,
+    }
+    mapCompatDomProps(b, 'input')
+    expect(b).toEqual({
+      defaultValue: 'd',
+      value: 'controlled',
+      defaultChecked: true,
+      checked: false,
+    })
+  })
+
+  it('strips authoring-only props with no DOM equivalent', () => {
+    const p: Record<string, unknown> = {
+      suppressHydrationWarning: true,
+      suppressContentEditableWarning: true,
+    }
+    mapCompatDomProps(p, 'div')
+    expect(p).toEqual({})
+  })
+})

package/src/tests/defer.test.ts

@@ -0,0 +1,359 @@
+import { signal } from '@pyreon/reactivity'
+import { _setupIdleTrigger, _setupVisibleTrigger, Defer } from '../defer'
+import { Fragment, h } from '../h'
+import type { ComponentFn, Props, VNode } from '../types'
+
+// Helper: pull the render-callback out of Defer's returned VNode shape.
+// `when` and `idle` modes return a Fragment whose `children[0]` is a
+// thunk. `visible` mode returns a div whose `children[0]` is the same
+// thunk. Both shapes return the same `renderContent` accessor.
+function getRenderThunk(vnode: VNode): () => unknown {
+  const children = vnode.children as unknown[]
+  const thunk = children[0]
+  if (typeof thunk !== 'function') throw new Error('Expected render thunk')
+  return thunk as () => unknown
+}
+
+describe('Defer — common shape', () => {
+  test('returns a VNode (Fragment or wrapper div per trigger mode)', () => {
+    const result = Defer({
+      chunk: () => new Promise<{ default: ComponentFn<Props> }>(() => {}),
+      when: () => false,
+    })
+    expect(result).toBeDefined()
+    expect((result as VNode).type).toBe(Fragment)
+  })
+
+  test('renders fallback before chunk resolves', () => {
+    const fallback = h('span', null, 'loading…')
+    const vnode = Defer<Props>({
+      chunk: () => new Promise<{ default: ComponentFn<Props> }>(() => {}), // never resolves
+      when: () => true,
+      fallback,
+    })
+    expect(getRenderThunk(vnode)()).toBe(fallback)
+  })
+
+  test('renders null when no fallback and chunk has not resolved', () => {
+    const vnode = Defer<Props>({
+      chunk: () => new Promise<{ default: ComponentFn<Props> }>(() => {}),
+      when: () => true,
+    })
+    expect(getRenderThunk(vnode)()).toBeNull()
+  })
+})
+
+describe('Defer — when (signal-driven)', () => {
+  test('does NOT load chunk while when is false', () => {
+    let calls = 0
+    const chunkFn = () => {
+      calls++
+      return Promise.resolve({ default: (() => null) as ComponentFn<Props> })
+    }
+    const flag = signal(false)
+    Defer<Props>({ chunk: chunkFn, when: flag })
+    expect(calls).toBe(0)
+  })
+
+  test('loads chunk when when flips to true', async () => {
+    const Inner: ComponentFn<{ msg: string }> = (p) => h('div', null, p.msg)
+    let calls = 0
+    const chunkFn = () => {
+      calls++
+      return Promise.resolve({ default: Inner })
+    }
+    const flag = signal(false)
+    const vnode = Defer<{ msg: string }>({
+      chunk: chunkFn,
+      when: flag,
+      children: (Comp) => h(Comp, { msg: 'hi' }),
+    })
+    expect(calls).toBe(0)
+    flag.set(true)
+    // Effect schedules synchronously; chunk fetch is microtask-resolved.
+    expect(calls).toBe(1)
+    await new Promise((r) => setTimeout(r, 0))
+    const result = getRenderThunk(vnode)() as VNode
+    expect(result.type).toBe(Inner)
+    expect(result.props).toEqual({ msg: 'hi' })
+  })
+
+  test('loads chunk EXACTLY ONCE when signal oscillates', async () => {
+    let calls = 0
+    const chunkFn = () => {
+      calls++
+      return Promise.resolve({ default: (() => null) as ComponentFn<Props> })
+    }
+    const flag = signal(false)
+    Defer<Props>({ chunk: chunkFn, when: flag })
+    flag.set(true)
+    flag.set(false)
+    flag.set(true)
+    flag.set(false)
+    flag.set(true)
+    await new Promise((r) => setTimeout(r, 0))
+    expect(calls).toBe(1)
+  })
+
+  test('accepts component re-exports without default wrapper', async () => {
+    const Inner: ComponentFn = () => h('span', null, 'ok')
+    const flag = signal(true)
+    const vnode = Defer<Props>({
+      chunk: () => Promise.resolve(Inner), // bare ComponentFn
+      when: flag,
+      children: (Comp) => h(Comp, {}),
+    })
+    await new Promise((r) => setTimeout(r, 0))
+    const result = getRenderThunk(vnode)() as VNode
+    expect(result.type).toBe(Inner)
+  })
+
+  test('throws when chunk() rejects (Suspense-style error propagation)', async () => {
+    const consoleSpy = (() => {
+      const orig = console.error
+      console.error = () => {} // silence dev-mode error log
+      return () => {
+        console.error = orig
+      }
+    })()
+    try {
+      const flag = signal(true)
+      const vnode = Defer<Props>({
+        chunk: () => Promise.reject(new Error('chunk boom')),
+        when: flag,
+      })
+      await new Promise((r) => setTimeout(r, 0))
+      expect(() => getRenderThunk(vnode)()).toThrow('chunk boom')
+    } finally {
+      consoleSpy()
+    }
+  })
+
+  test('renders default <Comp /> when children render-prop omitted', async () => {
+    const Inner: ComponentFn = () => h('div', null, 'no-children-prop')
+    const flag = signal(true)
+    const vnode = Defer<Props>({
+      chunk: () => Promise.resolve({ default: Inner }),
+      when: flag,
+    })
+    await new Promise((r) => setTimeout(r, 0))
+    const result = getRenderThunk(vnode)() as VNode
+    expect(result.type).toBe(Inner)
+    expect(result.props).toEqual({})
+  })
+})
+
+describe('Defer — on="visible"', () => {
+  test('returns a div wrapper with data-pyreon-defer="visible"', () => {
+    const vnode = Defer<Props>({
+      chunk: () => new Promise<{ default: ComponentFn<Props> }>(() => {}),
+      on: 'visible',
+    })
+    expect((vnode as VNode).type).toBe('div')
+    expect((vnode as VNode).props['data-pyreon-defer']).toBe('visible')
+  })
+
+  test('uses display: contents so wrapper is layout-transparent', () => {
+    const vnode = Defer<Props>({
+      chunk: () => new Promise<{ default: ComponentFn<Props> }>(() => {}),
+      on: 'visible',
+    })
+    expect((vnode as VNode).props.style).toBe('display: contents')
+  })
+
+  test('default rootMargin is 200px (not exposed via prop spread)', () => {
+    // The rootMargin is consumed by onMount; we can't directly observe
+    // it from the returned VNode. This test documents the default and
+    // would catch a regression in the constant.
+    const vnode = Defer<Props>({
+      chunk: () => new Promise<{ default: ComponentFn<Props> }>(() => {}),
+      on: 'visible',
+    })
+    // Wrapper has the structural attrs but no rootMargin leak to DOM.
+    expect((vnode as VNode).props.rootMargin).toBeUndefined()
+  })
+})
+
+describe('Defer — on="idle"', () => {
+  test('returns a Fragment (no wrapper element)', () => {
+    const vnode = Defer<Props>({
+      chunk: () => new Promise<{ default: ComponentFn<Props> }>(() => {}),
+      on: 'idle',
+    })
+    expect((vnode as VNode).type).toBe(Fragment)
+  })
+})
+
+// Browser-API helpers extracted from the onMount callbacks so they're
+// directly testable without happy-dom (core tests run in Node). The
+// onMount wrappers in `defer.ts` just delegate to these.
+describe('_setupIdleTrigger', () => {
+  // Use `Reflect.has` + property descriptors instead of plain assignment
+  // so the restore is symmetric — if the global wasn't defined at test
+  // start (Node), `delete` cleanly returns to the original state.
+  const orig = {
+    ric: (globalThis as { requestIdleCallback?: unknown }).requestIdleCallback,
+    cic: (globalThis as { cancelIdleCallback?: unknown }).cancelIdleCallback,
+  }
+  afterEach(() => {
+    if (orig.ric === undefined) delete (globalThis as { requestIdleCallback?: unknown }).requestIdleCallback
+    else (globalThis as { requestIdleCallback?: unknown }).requestIdleCallback = orig.ric
+    if (orig.cic === undefined) delete (globalThis as { cancelIdleCallback?: unknown }).cancelIdleCallback
+    else (globalThis as { cancelIdleCallback?: unknown }).cancelIdleCallback = orig.cic
+  })
+
+  test('uses requestIdleCallback when available', () => {
+    let captured: (() => void) | null = null
+    ;(globalThis as { requestIdleCallback?: unknown }).requestIdleCallback = (
+      cb: () => void,
+    ): number => {
+      captured = cb
+      return 42
+    }
+    let cancelledId: number | null = null
+    ;(globalThis as { cancelIdleCallback?: unknown }).cancelIdleCallback = (
+      id: number,
+    ): void => {
+      cancelledId = id
+    }
+    const startLoad = () => {}
+    const teardown = _setupIdleTrigger(startLoad)
+    expect(captured).toBe(startLoad)
+    teardown()
+    expect(cancelledId).toBe(42)
+  })
+
+  test('teardown is no-op when cancelIdleCallback is missing', () => {
+    ;(globalThis as { requestIdleCallback?: unknown }).requestIdleCallback = (
+      _cb: () => void,
+    ): number => 99
+    delete (globalThis as { cancelIdleCallback?: unknown }).cancelIdleCallback
+    const teardown = _setupIdleTrigger(() => {})
+    expect(() => teardown()).not.toThrow()
+  })
+
+  test('falls back to setTimeout when requestIdleCallback is absent', async () => {
+    delete (globalThis as { requestIdleCallback?: unknown }).requestIdleCallback
+    let loaded = false
+    const teardown = _setupIdleTrigger(() => {
+      loaded = true
+    })
+    // setTimeout(fn, 1) fires after a tick — await to observe.
+    await new Promise((r) => setTimeout(r, 5))
+    expect(loaded).toBe(true)
+    teardown() // safe to call after the timer fired
+  })
+
+  test('setTimeout fallback cancels via clearTimeout when teardown fires before tick', () => {
+    delete (globalThis as { requestIdleCallback?: unknown }).requestIdleCallback
+    let loaded = false
+    const teardown = _setupIdleTrigger(() => {
+      loaded = true
+    })
+    teardown() // cancel before the timer fires
+    return new Promise<void>((r) =>
+      setTimeout(() => {
+        expect(loaded).toBe(false)
+        r()
+      }, 10),
+    )
+  })
+})
+
+describe('_setupVisibleTrigger', () => {
+  const origObs = (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver
+  afterEach(() => {
+    if (origObs === undefined) delete (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver
+    else (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver = origObs
+  })
+
+  test('loads immediately when el is null', () => {
+    let loaded = false
+    const teardown = _setupVisibleTrigger(null, () => {
+      loaded = true
+    }, '200px')
+    expect(loaded).toBe(true)
+    expect(typeof teardown).toBe('function')
+  })
+
+  test('loads immediately when IntersectionObserver is unavailable', () => {
+    delete (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver
+    // Pass a stub element; without the global the trigger should bail early.
+    const stubEl = {} as unknown as HTMLElement
+    let loaded = false
+    _setupVisibleTrigger(stubEl, () => {
+      loaded = true
+    }, '200px')
+    expect(loaded).toBe(true)
+  })
+
+  test('creates an observer with the configured rootMargin', () => {
+    let capturedOptions: IntersectionObserverInit | undefined
+    let observed: Element | null = null
+    let disconnected = false
+    class StubObserver {
+      callback: IntersectionObserverCallback
+      constructor(cb: IntersectionObserverCallback, opts?: IntersectionObserverInit) {
+        this.callback = cb
+        capturedOptions = opts
+      }
+      observe(el: Element) {
+        observed = el
+      }
+      disconnect() {
+        disconnected = true
+      }
+      unobserve() {}
+      takeRecords() {
+        return []
+      }
+    }
+    ;(globalThis as { IntersectionObserver?: unknown }).IntersectionObserver = StubObserver
+    const stubEl = { tagName: 'DIV' } as unknown as HTMLElement
+    const teardown = _setupVisibleTrigger(stubEl, () => {}, '300px')
+    expect(observed).toBe(stubEl)
+    expect(capturedOptions?.rootMargin).toBe('300px')
+    teardown()
+    expect(disconnected).toBe(true)
+  })
+
+  test('fires startLoad on intersection, then disconnects', () => {
+    let captured: IntersectionObserverCallback | null = null
+    let disconnected = false
+    class StubObserver {
+      constructor(cb: IntersectionObserverCallback) {
+        captured = cb
+      }
+      observe() {}
+      disconnect() {
+        disconnected = true
+      }
+      unobserve() {}
+      takeRecords() {
+        return []
+      }
+    }
+    ;(globalThis as { IntersectionObserver?: unknown }).IntersectionObserver = StubObserver
+    let loaded = false
+    const stubEl = {} as unknown as HTMLElement
+    _setupVisibleTrigger(stubEl, () => {
+      loaded = true
+    }, '0px')
+
+    // Simulate non-intersecting entry — should NOT fire.
+    captured!(
+      [{ isIntersecting: false } as unknown as IntersectionObserverEntry],
+      {} as IntersectionObserver,
+    )
+    expect(loaded).toBe(false)
+    expect(disconnected).toBe(false)
+
+    // Simulate intersecting entry — fires and disconnects.
+    captured!(
+      [{ isIntersecting: true } as unknown as IntersectionObserverEntry],
+      {} as IntersectionObserver,
+    )
+    expect(loaded).toBe(true)
+    expect(disconnected).toBe(true)
+  })
+})