@abide/abide 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # abide
 
+## 0.46.0
+
+### Minor Changes
+
+- 162296f: wake a below-the-fold deferred {#await cache()} on visible, not idle ([`193ff2f`](https://github.com/briancray/abide/commit/193ff2f7ad4a40f3dde39537260d76e7317a6013))
+- 162296f: client:idle / client:visible island directive on components ([`a50f0bc`](https://github.com/briancray/abide/commit/a50f0bce451f00f292eea90419feaa6ff1a708bd))
+- 162296f: wake deferred {#await cache()} on idle + size-gate the defer decision ([`a5a1a7f`](https://github.com/briancray/abide/commit/a5a1a7fea3dfe35cad08ea17fad7016fb8cca6cb))
+- 162296f: component-island hydration boundary (mountRange) + shared wake helpers ([`e0ed9ba`](https://github.com/briancray/abide/commit/e0ed9ba58d41ad7d1605717b1f4ec9207d2454a5))
+
+### Patch Changes
+
+- 162296f: rename shadowed `constructor` local in whenVisible ([`2f25fdf`](https://github.com/briancray/abide/commit/2f25fdfcb21e05807dd26c876acd8cd9f49d3004))
+- 162296f: shared observer + frame-budgeted wake flush for islands at scale ([`3c2db3b`](https://github.com/briancray/abide/commit/3c2db3bce43ad8cc30b6cab279246a033db4bd61))
+- 162296f: apply formatter to drifted files ([`5960d3c`](https://github.com/briancray/abide/commit/5960d3c5db44c925cf3c1fc9566156a8886db195))
+- 162296f: restore multi-line union wrapping in generateBuild ([`92ce908`](https://github.com/briancray/abide/commit/92ce908c3369759d8b55c695ed2deed410be1ef5))
+
 ## 0.45.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.45.0",
+    "version": "0.46.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",

package/src/lib/server/rpc/defineRpc.ts

@@ -161,7 +161,8 @@ export function defineRpc<Args, Return>(
     /* Abort the controller parseArgsForFetch stashed on store.req; a no-op when none was stashed (SSR cache reads). */
     function abortRpcTimeout(): void {
         const req = requestContext.getStore()?.req as
-            (Request & { [RPC_TIMEOUT_ABORT]?: AbortController }) | undefined
+            | (Request & { [RPC_TIMEOUT_ABORT]?: AbortController })
+            | undefined
         req?.[RPC_TIMEOUT_ABORT]?.abort(new DOMException('handler timeout', 'TimeoutError'))
     }
 

package/src/lib/shared/DEFER_MIN_ARRAY_LENGTH.ts

@@ -0,0 +1,14 @@
+/*
+The array-length above which a blocking `{#await cache()}` value is worth deferring (shipped
+inert, materialized on idle) rather than inlined and hydrated eagerly at boot. Deferral trades
+a live boot for a cheaper one; below this many rows the boot decode is cheap enough that the
+trade doesn't pay, so the block stays eager — fully interactive from the first frame, no wake
+needed. Only genuinely large grids cross it and take the inert-then-idle-wake path.
+
+An O(1) `.length` heuristic (measured on the resolved value, before serialization): array-shaped
+cache reads — lists, grids, tables — are the payloads big enough to matter, and the ones the
+inert path was built for. Non-array values never defer. A deliberately generous default: with
+idle-wake, a deferred block is interactive anyway (live before a human acts), so this is a
+boot-performance knob, not a correctness one — set high so eager-and-simple is the common case.
+*/
+export const DEFER_MIN_ARRAY_LENGTH = 500

package/src/lib/ui/compile/generateBuild.ts

@@ -558,7 +558,11 @@ export function generateBuild(
         parentVar: string,
         before: string,
     ): string {
-        return `$$mountChild(${parentVar}, ${node.name}, ${propsArg(node)}, ${before}, ${JSON.stringify(node.name)});\n`
+        /* `client:idle`/`client:visible` → the island trigger, the 6th mountChild arg. Omitted
+           (the common case) leaves the call byte-identical to before — eager hydration. */
+        const trigger =
+            node.clientTrigger !== undefined ? `, ${JSON.stringify(node.clientTrigger)}` : ''
+        return `$$mountChild(${parentVar}, ${node.name}, ${propsArg(node)}, ${before}, ${JSON.stringify(node.name)}${trigger});\n`
     }
 
     /* An await block: pending → resolved(value) / error branches. Each branch is a

package/src/lib/ui/compile/parseTemplate.ts

@@ -640,12 +640,25 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
            its children become slot content (rendered where the child puts <slot>). */
         if (UPPERCASE_START.test(tag)) {
             const slotted = selfClosing ? [] : readChildren(tag)
+            /* `client:idle` / `client:visible` are island directives (bare) — pull them out of
+               the attributes so they never round-trip as props; only the build back-end reads
+               the trigger. Any other `client:*` falls through as a prop (a prop-check error). */
+            const clientAttr = attrs.find(
+                (attr) =>
+                    attr.kind === 'static' &&
+                    (attr.name === 'client:idle' || attr.name === 'client:visible'),
+            )
+            const clientTrigger =
+                clientAttr?.kind === 'static'
+                    ? (clientAttr.name.slice('client:'.length) as 'idle' | 'visible')
+                    : undefined
             return {
                 kind: 'component',
                 name: tag,
                 loc: baseOffset + tagStart,
-                props: toProps(attrs),
+                props: toProps(attrs.filter((attr) => attr !== clientAttr)),
                 children: slotted,
+                clientTrigger,
             }
         }
         /* `{...expr}` spreads onto a component (its props) or a native element (its

package/src/lib/ui/compile/types/TemplateNode.ts

@@ -80,6 +80,11 @@ export type TemplateNode =
              the prop name's source offset — the anchor for an excess-prop diagnostic. */
           props: { name: string; code: string; loc?: number; nameLoc?: number; spread?: boolean }[]
           children: TemplateNode[]
+          /* `client:idle` / `client:visible` on the tag → hydrate this child as an island
+             (server markup kept, build deferred to the trigger). Extracted from the attributes
+             so it never becomes a prop; the build back-end passes it to `mountChild`, SSR and
+             the prop check ignore it (an island renders fully on the server). */
+          clientTrigger?: 'idle' | 'visible'
       }
     | { kind: 'switch'; subject: string; children: TemplateNode[]; loc?: number }
     /* A branch of a `<template switch>` (`match` set) or `<template if>` chain. Inside an

package/src/lib/ui/deferResume.ts

@@ -1,5 +1,6 @@
 import { activeCacheStore } from '../shared/activeCacheStore.ts'
 import { cacheKeyOf } from '../shared/cacheKeyOf.ts'
+import { DEFER_MIN_ARRAY_LENGTH } from '../shared/DEFER_MIN_ARRAY_LENGTH.ts'
 import { snapshotShippable } from '../shared/snapshotShippable.ts'
 import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
 
@@ -24,6 +25,12 @@ export function deferResume(promise: unknown, value: unknown): ResumeEntry | Def
     if (entry === undefined || !snapshotShippable(entry)) {
         return { ok: true, value }
     }
+    /* Only defer a genuinely large grid: below the threshold, inline the value and hydrate
+       eagerly — the block is interactive from the first frame, no inert phase, no wake. This is
+       what keeps a modest searchable list live instead of frozen-until-idle (the reported gap). */
+    if (!Array.isArray(value) || value.length < DEFER_MIN_ARRAY_LENGTH) {
+        return { ok: true, value }
+    }
     entry.deferred = true
     return { defer: true, key }
 }

package/src/lib/ui/dom/awaitBlock.ts

@@ -7,12 +7,14 @@ import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import type { DeferMarker, ResumeEntry } from '../runtime/RESUME.ts'
 import { RESUME } from '../runtime/RESUME.ts'
+import { scheduleWake } from '../runtime/scheduleWake.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
 import type { State } from '../runtime/types/State.ts'
 import { state } from '../state.ts'
 import { buildDetachedRange } from './buildDetachedRange.ts'
 import { discardBoundary } from './discardBoundary.ts'
+import { firstElementBetween } from './firstElementBetween.ts'
 import { removeRange } from './removeRange.ts'
 
 /*
@@ -58,11 +60,20 @@ export function awaitBlock(
     let active: { start: Comment; end: Comment; dispose: () => void } | undefined
     let anchor: Node | undefined
     let first = true
+    /* A deferred (inert-adopted) block schedules a wake (idle or visible); cancel it if the
+       owner tears the block out before it fires, so no late re-run touches a detached anchor. */
+    let cancelWake: (() => void) | undefined
     /* Bumped each run so a prior run's in-flight promise can't clobber a newer one, AND on
        owner teardown so an in-flight promise that settles AFTER the enclosing `{#if}`/
        `{#for}`/component tears this block out is abandoned — otherwise its settle runs
-       `place` on the block's now-detached anchor and `insertBefore` throws NotFoundError. */
-    const guard = generationGuard()
+       `place` on the block's now-detached anchor and `insertBefore` throws NotFoundError.
+       The teardown also cancels a pending wake (above). */
+    const guard = generationGuard(() => cancelWake?.())
+    /* Flipped by a deferred block's wake. Read at the top of the effect so the block subscribes
+       to it and re-runs when it flips — the same re-run path an invalidate takes, so wake needs
+       no bespoke build logic. Never flips for a non-deferred block, so it costs one inert read
+       per run there. */
+    const woken = state(false)
     /* The resolved value, held as a reactive cell so the then-branch reads it through its
        own effects. A re-run that resolves to a NEW value SETS this cell instead of rebuilding
        the branch — the branch (and any keyed `each` inside it) survives and updates in place,
@@ -215,6 +226,17 @@ export function awaitBlock(
         /* Subscribe without a value read: no clone, no decode, no fetch — just the key, so
            cache.invalidate re-runs this effect (createSubscriber ties it to the running scope). */
         activeCacheStore().subscribe(key)
+        /* Wake the inert branch — it's a boot-frame optimization, never a lasting mode. The
+           wake flips `woken`, re-running the effect through its normal `render` path: the
+           lazily-seeded cache reads warm, so the branch materializes live and interactive with
+           no fetch. Closes the "deferred grid stays inert until invalidate" gap.
+
+           Position picks the trigger ('auto'): a branch with an element wakes on VISIBLE (a
+           below-the-fold grid decodes only when scrolled to, one never reached costs nothing);
+           an empty branch or a DOM with no observer wakes on IDLE — never lingering inert. */
+        cancelWake = scheduleWake('auto', firstElementBetween(firstKept, close), () => {
+            woken.value = true
+        })
     }
 
     /* Discard the SSR boundary and (re)build the block from the live promise, fresh
@@ -332,6 +354,9 @@ export function awaitBlock(
     }
 
     effect(() => {
+        /* Subscribe to the wake cell every run (including the first, before it can flip) so a
+           deferred block's idle wake re-runs this effect. Inert for non-deferred blocks. */
+        woken.value
         guard.renew()
         if (first) {
             first = false

package/src/lib/ui/dom/firstElementBetween.ts

@@ -0,0 +1,14 @@
+import { isElement } from './isElement.ts'
+
+/* The first Element in the sibling run `[start, end)` — the node a visible-wake observes for a
+   deferred region (await branch or component island). Undefined when the run holds no element
+   (text/comment only), so the caller falls back to an idle wake. Element detection is
+   method-based (`isElement`), not `nodeType`, so the walk runs under the test mini-dom too. */
+export function firstElementBetween(start: Node | null, end: Node | null): Element | undefined {
+    for (let node = start; node !== null && node !== end; node = node.nextSibling) {
+        if (isElement(node)) {
+            return node
+        }
+    }
+    return undefined
+}

package/src/lib/ui/dom/mountChild.ts

@@ -29,16 +29,19 @@ export function mountChild(
     props: Parameters<UiComponent>[1],
     before: Node | null = null,
     label?: string,
+    /* `client:idle` / `client:visible` on the tag → hydrate this child as an island (server
+       markup kept, build deferred to the trigger). Undefined = hydrate eagerly, as before. */
+    clientTrigger?: 'idle' | 'visible',
 ): void {
     const moduleId = factory.__abideId
     if (!__ABIDE_DEV__ || !hotReloadEnabled.current || moduleId === undefined) {
-        mountRange(parent, factory.build, props, before, label)
+        mountRange(parent, factory.build, props, before, label, clientTrigger)
         return
     }
     /* Capture the component's model alongside its mount handle, so a later swap can
        carry its state across (see `hotReplace`). */
     const { value: handle, model } = captureModelDoc(() =>
-        mountRange(parent, factory.build, props, before, label),
+        mountRange(parent, factory.build, props, before, label, clientTrigger),
     )
     const instance = {
         factory,

package/src/lib/ui/dom/mountRange.ts

@@ -1,9 +1,15 @@
+import { claimChild } from '../runtime/claimChild.ts'
 import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
+import { scheduleWake } from '../runtime/scheduleWake.ts'
 import { scope } from '../runtime/scope.ts'
 import type { UiProps } from '../runtime/types/UiProps.ts'
+import { clearBetween } from './clearBetween.ts'
+import { commentData } from './commentData.ts'
 import { disposeRange } from './disposeRange.ts'
 import { fillRange } from './fillRange.ts'
+import { firstElementBetween } from './firstElementBetween.ts'
+import { markerDepthDelta } from './markerDepthDelta.ts'
 import { openMarker } from './openMarker.ts'
 import { withScope } from './withScope.ts'
 
@@ -22,6 +28,12 @@ marker — mirrors `mountSlot`/`when`). `before` (a skeleton-located node, the b
 `anchorCursor`) places the range among static siblings on create; hydrate ignores it
 (the claim cursor drives placement). Returns the markers + a disposer so the hot path
 can rebuild in place.
+
+`clientTrigger` marks the component an ISLAND: on hydrate its server markup is kept
+verbatim and its build is SKIPPED, then run on the trigger (`'idle'`/`'visible'`) —
+so a below-the-fold widget ships as HTML and wires no effects until scrolled to (or
+the first idle gap), off the critical boot path. Create ignores it (there is no server
+markup to keep — an island is a hydration-cost optimization). See `adoptIsland`.
 */
 // @documentation plumbing
 export function mountRange(
@@ -30,6 +42,7 @@ export function mountRange(
     props: UiProps | undefined,
     before: Node | null = null,
     label: string | undefined = undefined,
+    clientTrigger: 'idle' | 'visible' | undefined = undefined,
 ): { start: Comment; end: Comment; dispose: () => void } {
     const hydration = RENDER.hydration
     const start = openMarker(parent, RANGE_OPEN, before)
@@ -37,6 +50,9 @@ export function mountRange(
         const end = openMarker(parent, RANGE_CLOSE, before)
         return fillRange(start, end, build, props, label)
     }
+    if (clientTrigger !== undefined) {
+        return adoptIsland(parent, start, build, props, label, clientTrigger, hydration)
+    }
     /* Hydrate: adopt the server range in place. Establish the child's lexical scope
        and render pass (same as `fillRange`), build claiming the existing nodes, then
        claim the end marker the build's content stops before. */
@@ -44,3 +60,62 @@ export function mountRange(
     const end = openMarker(parent, RANGE_CLOSE)
     return { start, end, dispose: disposeRange(scoped, start, end) }
 }
+
+/*
+Island hydration: keep the server markup, skip the build, wake it later on the trigger. Scan the
+child's server nodes to THIS range's depth-matched close (`markerDepthDelta` balances nested
+`[`…`]` / `abide:` ranges) — keeping them and advancing the claim cursor past them, so the rest
+of the page hydrates around the skipped subtree — then claim the close marker. No scope is built,
+so the inert disposer only clears the kept nodes; the wake clears them and builds the child fresh
+(hydration off) between the same markers, exactly like a create-path mount.
+*/
+function adoptIsland(
+    parent: Node,
+    start: Comment,
+    build: (host: Node, props?: UiProps) => void,
+    props: UiProps | undefined,
+    label: string | undefined,
+    trigger: 'idle' | 'visible',
+    hydration: NonNullable<(typeof RENDER)['hydration']>,
+): { start: Comment; end: Comment; dispose: () => void } {
+    const firstKept = claimChild(hydration, parent)
+    let node = firstKept
+    let depth = 0
+    while (node !== null) {
+        const data = commentData(node)
+        if (data !== undefined) {
+            const delta = markerDepthDelta(data)
+            /* A depth-0 close is THIS range's own; anything nested balances out first. */
+            if (delta === -1 && depth === 0) {
+                break
+            }
+            depth += delta
+        }
+        node = node.nextSibling
+    }
+    hydration.next.set(parent, node)
+    const end = openMarker(parent, RANGE_CLOSE)
+
+    /* Inert: no scope/effects for the kept nodes, so disposal only evicts the range. The wake
+       swaps in a real build whose own disposer replaces this one. */
+    let disposeContent = (): void => clearBetween(start, end)
+    const wake = (): void => {
+        disposeContent()
+        const previous = RENDER.hydration
+        RENDER.hydration = undefined
+        try {
+            disposeContent = fillRange(start, end, build, props, label).dispose
+        } finally {
+            RENDER.hydration = previous
+        }
+    }
+    const cancelWake = scheduleWake(trigger, firstElementBetween(firstKept, end), wake)
+    return {
+        start,
+        end,
+        dispose: () => {
+            cancelWake()
+            disposeContent()
+        },
+    }
+}

package/src/lib/ui/installHotBridge.ts

@@ -1,4 +1,5 @@
 import { snippet } from '../shared/snippet.ts'
+import { deferResume } from './deferResume.ts'
 import { anchorCursor } from './dom/anchorCursor.ts'
 import { appendSnippet } from './dom/appendSnippet.ts'
 import { appendStatic } from './dom/appendStatic.ts'
@@ -25,7 +26,6 @@ import { spreadProps } from './dom/spreadProps.ts'
 import { switchBlock } from './dom/switchBlock.ts'
 import { tryBlock } from './dom/tryBlock.ts'
 import { when } from './dom/when.ts'
-import { deferResume } from './deferResume.ts'
 import { effect } from './effect.ts'
 import { enterScope } from './enterScope.ts'
 import { exitScope } from './exitScope.ts'

package/src/lib/ui/runtime/scheduleWake.ts

@@ -0,0 +1,28 @@
+import { whenIdle } from './whenIdle.ts'
+import { whenVisible } from './whenVisible.ts'
+
+/*
+Schedule a one-shot wake for a deferred (inert-hydrated) region by trigger — the single
+trigger-selection both the await block and component islands share. `'visible'` (and `'auto'`)
+wake on scroll-in when the DOM can be measured (a real IntersectionObserver) and the region has
+an element to observe: a below-the-fold region decodes only when reached, one never scrolled to
+costs nothing. Otherwise — `'idle'`, no observer, or an empty branch — wake on idle: off the
+critical boot path but soon, so the region never lingers inert. Returns a cancel to drop a
+pending wake on teardown.
+
+`'auto'` is the await block's policy (defer decides, position decides trigger); `'idle'` /
+`'visible'` are an island's explicit `client:` choice.
+*/
+export function scheduleWake(
+    trigger: 'idle' | 'visible' | 'auto',
+    element: Element | undefined,
+    wake: () => void,
+): () => void {
+    const hasObserver =
+        typeof (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver ===
+        'function'
+    if (trigger !== 'idle' && hasObserver && element !== undefined) {
+        return whenVisible(element, wake)
+    }
+    return whenIdle(wake)
+}

package/src/lib/ui/runtime/whenIdle.ts

@@ -0,0 +1,21 @@
+/*
+Run `callback` once, in the first idle gap after the current frame — the client-side
+trigger a deferred (inert-hydrated) region uses to wake itself: boot stays cheap (no
+decode, no effects), then the region belatedly comes alive off the critical path,
+before a human can act on it. `requestIdleCallback` when the runtime has it (a `timeout`
+guarantees it fires even under sustained load); a `setTimeout(0)` macrotask otherwise
+(Safari < 16.4, test DOMs), which still clears the boot frame. Returns a cancel to drop
+the pending wake on teardown, so a region torn down before idle does no late work.
+*/
+export function whenIdle(callback: () => void, timeoutMs = 200): () => void {
+    const globalWithIdle = globalThis as {
+        requestIdleCallback?: (cb: () => void, options?: { timeout: number }) => number
+        cancelIdleCallback?: (handle: number) => void
+    }
+    if (typeof globalWithIdle.requestIdleCallback === 'function') {
+        const handle = globalWithIdle.requestIdleCallback(callback, { timeout: timeoutMs })
+        return () => globalWithIdle.cancelIdleCallback?.(handle)
+    }
+    const handle = setTimeout(callback, 0)
+    return () => clearTimeout(handle)
+}

package/src/lib/ui/runtime/whenVisible.ts

@@ -0,0 +1,105 @@
+/*
+Run `callback` once, the first time `element` enters (or is already within) the viewport —
+the trigger a below-the-fold deferred region uses to wake only when scrolled into view, so a
+grid the user never reaches costs nothing. A synchronous fire where the observer is absent
+(SSR/test DOMs), which keeps the region from staying inert where visibility can't be measured.
+Returns a cancel to drop a pending watch on teardown. Fires at most once.
+
+ONE shared IntersectionObserver backs every watcher (a grid of N islands registers N elements
+on one observer, not N observers), and wakes are BATCHED off the observer callback into a
+frame-flush capped at `WAKE_BUDGET_PER_FRAME`: a wake rebuilds DOM, so running it inside the
+observer callback would force a synchronous layout that shifts other elements across the
+margin and re-fires the observer — a cascade that locks the main thread at grid scale. Queuing
+to a rAF and spending a bounded number per frame breaks that loop and keeps each frame cheap;
+overflow spills to the next frame, so even a whole grid scrolled into view at once stays
+responsive.
+*/
+// A screenful of margin so a region is live by the time it's actually read.
+const ROOT_MARGIN = '256px'
+// Max wakes (DOM rebuilds) per frame — the ceiling that keeps a flush off the critical path.
+const WAKE_BUDGET_PER_FRAME = 40
+
+let sharedObserver: IntersectionObserver | undefined
+/* The IntersectionObserver constructor `sharedObserver` was built from. Identity only changes
+   when a test swaps `globalThis.IntersectionObserver`; on a change the observer + its pending
+   registrations are rebuilt, so module state doesn't leak across tests. */
+let sharedObserverCtor: unknown
+const wakeByElement = new Map<Element, () => void>()
+const readyWakes = new Set<() => void>()
+let flushScheduled = false
+
+/* Next animation frame (browser) or macrotask (test/SSR) — the flush cadence. */
+function scheduleFrame(run: () => void): void {
+    const globalWithRaf = globalThis as { requestAnimationFrame?: (cb: () => void) => number }
+    if (typeof globalWithRaf.requestAnimationFrame === 'function') {
+        globalWithRaf.requestAnimationFrame(run)
+    } else {
+        setTimeout(run, 0)
+    }
+}
+
+/* Spend up to the per-frame budget of queued wakes; reschedule if any remain. */
+function flushWakes(): void {
+    flushScheduled = false
+    let processed = 0
+    for (const wake of readyWakes) {
+        readyWakes.delete(wake)
+        wake()
+        processed += 1
+        if (processed >= WAKE_BUDGET_PER_FRAME) {
+            break
+        }
+    }
+    scheduleFlush()
+}
+
+function scheduleFlush(): void {
+    if (flushScheduled || readyWakes.size === 0) {
+        return
+    }
+    flushScheduled = true
+    scheduleFrame(flushWakes)
+}
+
+/* Queue every newly-intersecting element's wake — never run it here (see the cascade note). */
+function onIntersections(entries: IntersectionObserverEntry[]): void {
+    for (const entry of entries) {
+        if (entry.isIntersecting) {
+            const wake = wakeByElement.get(entry.target)
+            if (wake !== undefined) {
+                wakeByElement.delete(entry.target)
+                sharedObserver?.unobserve(entry.target)
+                readyWakes.add(wake)
+            }
+        }
+    }
+    scheduleFlush()
+}
+
+function observerFor(observerConstructor: typeof IntersectionObserver): IntersectionObserver {
+    if (sharedObserver === undefined || sharedObserverCtor !== observerConstructor) {
+        wakeByElement.clear()
+        readyWakes.clear()
+        sharedObserver = new observerConstructor(onIntersections, { rootMargin: ROOT_MARGIN })
+        sharedObserverCtor = observerConstructor
+    }
+    return sharedObserver
+}
+
+export function whenVisible(element: Element, callback: () => void): () => void {
+    const observerConstructor = (
+        globalThis as { IntersectionObserver?: typeof IntersectionObserver }
+    ).IntersectionObserver
+    if (typeof observerConstructor !== 'function') {
+        callback()
+        return () => undefined
+    }
+    const observer = observerFor(observerConstructor)
+    wakeByElement.set(element, callback)
+    observer.observe(element)
+    return () => {
+        wakeByElement.delete(element)
+        readyWakes.delete(callback)
+        observer.unobserve(element)
+    }
+}