@weft-js/start 0.1.0 → 0.1.2

package/src/run/listeners.ts

@@ -0,0 +1,155 @@
+import { drain, wake } from '@weft-js/core/dom'
+import type { Held } from '../boot'
+import { client, peers } from '../router'
+import { admitLink, routeClicks } from './admission'
+import type { Navigation } from './navigation'
+
+type Hot = { on(event: string, on: (data: { queries: boolean }) => unknown): void }
+
+export function listeners(nav: Navigation, hot: () => Hot | undefined) {
+  addEventListener('online', nav.owing)
+  addEventListener('focus', nav.owing)
+  addEventListener('pagehide', nav.dispose)
+  // A page restored from the back/forward cache was disposed on the way out: let it prefetch again.
+  addEventListener('pageshow', (e) => e.persisted && nav.prefetch.resume())
+  // A cross-document transition's pagereveal and pageswap are settled from the head (page-stream.tsx `REVEAL`): the page
+  // reveals before this runs. One still going when it does is settled here too.
+  settle((document as Document & { activeViewTransition?: ViewTransition }).activeViewTransition)
+  if (hot()) hot()!.on('weft:refresh', (changed) => void nav.reloaded(changed))
+  client.invalidated = nav.invalidated
+  client.sessionChanged = nav.dispose
+  clicks(nav)
+  preload(nav)
+  history(nav)
+  peers?.addEventListener('message', (m) => {
+    if (!m.data) {
+      nav.dispose()
+      location.reload()
+    }
+  })
+  const q = (window as Window & { __wq?: Held }).__wq
+  if (q) {
+    q.w = wake
+    if (q.l) wake(q.l)
+    drain()
+  }
+}
+
+// A fade can intercept a click; replay it on the element underneath once the picture is gone.
+function clicks(nav: Navigation) {
+  routeClicks(document, nav.routes, (href) => nav.go(href))
+  let ended: Promise<unknown> | undefined
+  document.addEventListener(
+    'pointerdown',
+    () => {
+      ended = nav.fading?.finished.catch(() => {})
+      nav.fading?.skipTransition()
+      nav.fading = undefined
+    },
+    true,
+  )
+  document.addEventListener(
+    'click',
+    (e) => {
+      const gone = ended
+      ended = undefined
+      if (!gone || e.target !== document.documentElement) return
+      void gone.then(() => {
+        const under = document.elementFromPoint(e.clientX, e.clientY)
+        if (under !== document.documentElement) under?.dispatchEvent(new MouseEvent('click', e))
+      })
+    },
+    true,
+  )
+}
+
+// Only known-cost intent can start a bounded data request; no page module runs here.
+export function preload(nav: Navigation) {
+  let pending: ReturnType<typeof setTimeout> | undefined
+  const network = (
+    navigator as Navigator & {
+      connection?: {
+        saveData?: boolean
+        effectiveType?: string
+        addEventListener?: (type: string, fn: () => void) => void
+        removeEventListener?: (type: string, fn: () => void) => void
+      }
+    }
+  ).connection
+  const cancel = () => {
+    clearTimeout(pending)
+    nav.prefetch.cancel()
+  }
+  const intent = (e: Event) => {
+    clearTimeout(pending)
+    const target = e.target as Element | null
+    const admitted = admitLink(e, nav.routes)
+    if (
+      !admitted ||
+      admitted.noop ||
+      !target ||
+      target.closest('[data-preload="off"]') ||
+      target.closest('input,textarea,select,[contenteditable]:not([contenteditable="false"])')
+    )
+      return
+    pending = setTimeout(
+      () => {
+        if (document.hidden) return
+        const version = nav.cache.version
+        nav.cache.setBuild(nav.routes.build)
+        if (version !== nav.cache.version) nav.prefetch.cancel(true)
+        nav.prefetch.start(
+          admitted.url,
+          e.type === 'focusin' ? 'focus' : 'hover',
+          network,
+          navigator.onLine,
+        )
+      },
+      e.type === 'focusin' ? 0 : 80,
+    )
+  }
+  document.addEventListener('pointerover', intent)
+  document.addEventListener('focusin', intent)
+  document.addEventListener('pointerout', cancel)
+  document.addEventListener('focusout', cancel)
+  const visibility = () => {
+    if (document.hidden) cancel()
+  }
+  document.addEventListener('visibilitychange', visibility)
+  addEventListener('offline', cancel)
+  addEventListener('pagehide', cancel)
+  network?.addEventListener?.('change', cancel)
+  return () => {
+    cancel()
+    document.removeEventListener('pointerover', intent)
+    document.removeEventListener('focusin', intent)
+    document.removeEventListener('pointerout', cancel)
+    document.removeEventListener('focusout', cancel)
+    document.removeEventListener('visibilitychange', visibility)
+    removeEventListener('offline', cancel)
+    removeEventListener('pagehide', cancel)
+    network?.removeEventListener?.('change', cancel)
+  }
+}
+
+// An in-page anchor fires popstate too; only a changed path needs a navigation.
+function history(nav: Navigation) {
+  nav.at = location.pathname + location.search
+  addEventListener('popstate', () => {
+    if (location.pathname + location.search !== nav.at)
+      return void nav.go(location.href, { pop: true })
+    if (nav.current) {
+      nav.current.abort()
+      nav.settle()
+    }
+  })
+}
+
+/** Mark a transition's outcome as seen: a skipped one rejects all three of its promises. */
+function settle(t: ViewTransition | null | undefined) {
+  if (!t) return
+  const seen = () => {}
+  t.ready.catch(seen)
+  t.finished.catch(seen)
+  t.updateCallbackDone.catch(seen)
+}

package/src/run/navigation.ts

@@ -0,0 +1,382 @@
+import { flush } from '@weft-js/core'
+import { setHead } from '@weft-js/core/head'
+import {
+  applyMatches,
+  client,
+  type Level,
+  type NavigateOptions,
+  type RoutePayload,
+} from '../router'
+import type { ClientRoutes } from '../run'
+import { streamed, type mount } from './boot'
+import { matchingRouteAssets } from '../asset-receipt.mjs'
+import { ask, changedRouteParams, crossfade, current_, guess, revive } from './helpers'
+import { presentShape, type PreparedRouteShape } from './shape-preparation'
+import { retainSourceContext, type SourceContext } from './source-context'
+import { RouteCache, type Read } from './cache'
+import { Prefetch } from './prefetch'
+import { CachePresentation, retryDelay } from './cache-presentation'
+
+const RETRY = 1000,
+  RETRIES = 30_000
+
+type Options = NavigateOptions & { pop?: boolean; hops?: number }
+type Page = ReturnType<typeof mount>
+
+export class Navigation {
+  route: Page['route']
+  chunk: Page['chunk']
+  island: Page['island']
+  setBag: Page['setBag']
+  ready: Page['ready']
+  tags: Page['initialTags']
+  current: AbortController | undefined
+  refreshing: { ctrl: AbortController; tags: string[] } | undefined
+  /** Tags invalidated while a navigation was out: its route may read them, and that's only known when it lands. */
+  owed: string[] = []
+  again: ReturnType<typeof setTimeout> | undefined
+  tries = 0
+  prefetch: Prefetch
+  cache: RouteCache
+  presentation = new CachePresentation()
+  // A fade pictures the whole page twice, and the picture holds up every frame. Where that's slow, the page just changes.
+  fades = !(navigator.hardwareConcurrency <= 4)
+  fading: ViewTransition | undefined
+  painted = false
+  at!: string
+  shape: { outlet: Level; leases: PreparedRouteShape[] } | undefined
+  source: SourceContext | undefined
+  committedURL = location.href
+  committedBase = document.baseURI
+
+  constructor(
+    readonly routes: ClientRoutes,
+    page: Page,
+  ) {
+    this.cache = new RouteCache(routes.build)
+    this.prefetch = new Prefetch(this.cache, this.now, () => !!client.seed)
+    this.ready = page.ready
+    this.route = page.route
+    this.chunk = page.chunk
+    this.island = page.island
+    this.setBag = page.setBag
+    this.tags = page.initialTags
+    // Two frames in, the page has painted; a transition before then has no old picture to hold.
+    requestAnimationFrame(() => requestAnimationFrame(() => (this.painted = true)))
+  }
+
+  now = () => client.now?.() ?? 0
+  needs = (next: RoutePayload) =>
+    Promise.all([...next.m.map((m) => this.chunk(m.id)), ...(next.i ?? []).map(this.island)])
+  reads = (t: string[]) => this.tags.some((l) => l.some((x) => t.includes(x)))
+
+  /** The page moved on: drop old chunks and build held Boundaries from this data. */
+  release() {
+    const h = streamed.$wh || {}
+    for (const k of Object.keys(h)) {
+      const build = h[k]!
+      h[k] = () => {}
+      build()
+    }
+  }
+
+  apply(next: RoutePayload, url: URL, path: string, since: number, scroll: boolean) {
+    const owner = this.current
+    const current = () => this.current === owner && !owner?.signal.aborted
+    return () => {
+      if (!current()) return
+      this.at = path
+      if (next.c) client.seed ? client.seed(next.c, since) : (client.seeds ??= []).push(...next.c)
+      if (!current()) return
+      this.tags = next.m.map((m) => m.t ?? [])
+      this.route.assetBytes = matchingRouteAssets(next.a, this.routes.build)
+      this.setBag(next.b)
+      if (!current()) return
+      const source = this.source
+      this.source = undefined
+      source?.stop()
+      const old = this.detachShape()
+      const previousURL = this.committedURL
+      const previousBase = this.committedBase
+      this.committedURL = url.href
+      this.committedBase = document.baseURI
+      try {
+        applyMatches(this.route, next.m.map(revive), path, next.s)
+        if (!current()) return
+        if (next.m.some((m) => m.s)) current_(url.pathname)
+        if (!current()) return
+        if (next.h) setHead(next.h, url.pathname)
+        if (!current()) return
+        this.release()
+        if (!current()) return
+        flush()
+      } catch (error) {
+        if (current()) {
+          this.committedURL = previousURL
+          this.committedBase = previousBase
+        }
+        throw error
+      } finally {
+        old?.forEach((lease) => lease.release())
+        source?.release()
+      }
+      if (!current()) return
+      if (scroll) {
+        const target = url.hash && document.getElementById(decodeURIComponent(url.hash.slice(1)))
+        target ? target.scrollIntoView() : window.scrollTo(0, 0)
+      }
+    }
+  }
+
+  /** Find the first layout containing a changed parameter, or the leaf for a changed query. */
+  changedParams(ids: string[], url: URL) {
+    return changedRouteParams(this.routes, this.committedURL, ids, url)
+  }
+
+  /** Prepare all changed levels before replacing the current outlet. */
+  present(ids: string[], url: URL, force = false) {
+    return presentShape(this, ids, url, force)
+  }
+
+  detachShape() {
+    const shape = this.shape
+    if (!shape) return
+    this.shape = undefined
+    shape.outlet.shape.value = undefined
+    return shape.leases
+  }
+
+  clearShape() {
+    const leases = this.detachShape()
+    if (leases) {
+      try {
+        flush()
+      } finally {
+        leases.forEach((lease) => lease.release())
+      }
+    }
+  }
+
+  /** No navigation is out any more: what it left owed is for the page now showing. */
+  settle() {
+    // Every way a navigation ends comes through here, so its cached-presentation timer stops here too.
+    if (this.current) this.presentation.stop(this.current)
+    this.clearShape()
+    if (this.source && this.current?.signal.aborted) {
+      history.replaceState(history.state, '', this.committedURL)
+      const url = new URL(this.committedURL)
+      this.at = url.pathname + url.search
+      this.route.path.value = this.at
+      current_(url.pathname)
+      flush()
+    }
+    this.source?.release()
+    this.source = undefined
+    this.current = undefined
+    const t = this.owed
+    this.owed = []
+    if (this.reads(t)) void this.refresh(t)
+  }
+
+  dispose = () => {
+    this.cache.clear()
+    this.prefetch.stop()
+    if (this.current) this.presentation.stop(this.current)
+    this.current?.abort()
+    this.current = undefined
+    this.refreshing?.ctrl.abort()
+    this.refreshing = undefined
+    clearTimeout(this.again)
+    this.owed = []
+    this.clearShape()
+    this.source?.release()
+    this.source = undefined
+  }
+
+  go = async (href: string, opts: Options = {}) => {
+    const url = new URL(href, location.href)
+    if (url.origin !== location.origin) return location.assign(url.href)
+    if (!opts.pop && url.href === location.href) return
+    const buildVersion = this.cache.version
+    this.cache.setBuild(this.routes.build)
+    if (buildVersion !== this.cache.version) this.prefetch.cancel(true)
+    if (this.current) this.presentation.stop(this.current)
+    this.current?.abort()
+    if (this.refreshing) {
+      this.refreshing.ctrl.abort()
+      this.owed.push(...this.refreshing.tags)
+      this.refreshing = undefined
+    }
+    const ctrl = (this.current = new AbortController())
+    const path = url.pathname + url.search
+    try {
+      this.source ??=
+        retainSourceContext(document, this.committedURL, this.committedBase) ?? undefined
+      if (!this.source) return opts.pop ? location.replace(url.href) : location.assign(url.href)
+      if (!opts.pop && url.href !== location.href)
+        history[opts.replace ? 'replaceState' : 'pushState'](null, '', url.href)
+      this.at = path
+      this.route.path.value = path
+      current_(url.pathname)
+      flush()
+      const speculative = this.prefetch.claim(url, ctrl.signal)
+      this.prefetch.cancel()
+      const cached = opts.pop ? this.cache.peek(url, !!client.seed) : undefined
+      const shown = this.presentation.show(this, ctrl, url, cached)
+      if (ctrl.signal.aborted || this.current !== ctrl) return
+      if (!shown) this.present(guess(this.routes, url.pathname), url)
+      await this.travel(url, ctrl, opts, shown, speculative)
+    } finally {
+      this.presentation.stop(ctrl)
+      if (this.current === ctrl) this.settle()
+    }
+  }
+
+  async travel(
+    url: URL,
+    ctrl: AbortController,
+    opts: Options,
+    shown = false,
+    speculative?: Promise<Read | undefined>,
+  ) {
+    const path = url.pathname + url.search
+    for (const id of guess(this.routes, url.pathname)) void this.chunk(id).catch(() => {})
+    let next: RoutePayload
+    let since: number
+    let version: number
+    let retries = 0
+    for (;;) {
+      try {
+        const shared = speculative ? await speculative : undefined
+        speculative = undefined
+        const read =
+          shared && (!shared.next.c?.length || client.seed)
+            ? shared
+            : await this.cache.load({
+                url,
+                signal: ctrl.signal,
+                fetchRoute: ask,
+                now: this.now,
+                canSeed: () => !!client.seed,
+                onForget: shown ? () => this.presentation.check(this) : undefined,
+              })
+        this.cache.setBuild(this.routes.build)
+        if (ctrl.signal.aborted) return
+        if (read.version !== this.cache.version) continue
+        next = read.next
+        if (next.s === 401 || next.s === 403) this.prefetch.cancel(true)
+        since = read.since
+        version = read.version
+        if (next.r) {
+          const hops = (opts.hops ?? 0) + 1
+          return hops > 5 ? location.replace(next.r) : this.go(next.r, { replace: true, hops })
+        }
+        if (shown && (next.s === 401 || next.s === 403)) {
+          if (this.ready?.(next)) {
+            this.apply(next, url, path, since, false)()
+            return
+          }
+          this.presentation.check(this)
+          if (ctrl.signal.aborted) return
+        }
+        await this.needs(next)
+        this.cache.setBuild(this.routes.build)
+        if (ctrl.signal.aborted) return
+        if (read.version !== this.cache.version) continue
+        if (shown && read.notModified) return
+        break
+      } catch {
+        if (ctrl.signal.aborted) return
+        if (!shown) return location.replace(url.href)
+        if (!this.cache.peek(url, !!client.seed)) {
+          this.current = undefined
+          ctrl.abort()
+          return location.replace(url.href)
+        }
+        await retryDelay(ctrl.signal, Math.min(RETRIES, RETRY * 2 ** retries++))
+        continue
+      }
+    }
+    let swapped = false
+    const swap = () => {
+      swapped = true
+      this.cache.setBuild(this.routes.build)
+      if (ctrl.signal.aborted || this.current !== ctrl || this.cache.version !== version) return
+      this.apply(next, url, path, since, opts.scroll !== false && !opts.pop)()
+    }
+    await crossfade(this, swap, () => swapped)
+    if (!ctrl.signal.aborted && this.current === ctrl && this.cache.version !== version)
+      await this.travel(url, ctrl, opts, shown)
+  }
+
+  /** Fetch the page's data again in place, retrying a failed refresh. */
+  async refresh(t: string[]) {
+    t = [...new Set([...t, ...(this.refreshing?.tags ?? [])])]
+    this.refreshing?.ctrl.abort()
+    const self = (this.refreshing = { ctrl: new AbortController(), tags: t })
+    const url = new URL(location.href),
+      since = this.now()
+    try {
+      const next: RoutePayload = await ask(url, self.ctrl.signal).then((r) => r.json())
+      if (self.ctrl.signal.aborted) return
+      if (next.s === 401 || next.s === 403) {
+        this.cache.clear()
+        this.prefetch.cancel(true)
+      }
+      if (next.r && !self.ctrl.signal.aborted) {
+        this.refreshing = undefined
+        return void this.go(next.r, { replace: true })
+      }
+      await this.needs(next)
+      if (self.ctrl.signal.aborted) return
+      this.apply(next, url, url.pathname + url.search, since, false)()
+      this.tries = 0
+    } catch {
+      if (this.refreshing === self) {
+        this.owed.push(...t)
+        clearTimeout(this.again)
+        this.again = setTimeout(this.owing, Math.min(RETRIES, RETRY * 2 ** this.tries++))
+      }
+    }
+    if (this.refreshing === self) this.refreshing = undefined
+  }
+
+  owing = () => {
+    if (!this.current && !this.refreshing) this.settle()
+  }
+
+  reloaded = async ({ queries }: { queries: boolean }) => {
+    const owner = this.current
+    this.cache.clear()
+    this.prefetch.cancel(true)
+    const url = new URL(location.href),
+      since = this.now()
+    let version = this.cache.version
+    const res = await ask(url)
+    if (version !== this.cache.version || !res.ok) return
+    const next: RoutePayload = await res.clone().json()
+    this.cache.setBuild(this.routes.build)
+    if (version !== this.cache.version || next.s >= 500) return
+    if (next.s === 401 || next.s === 403) {
+      this.cache.clear()
+      version = this.cache.version
+    }
+    if (queries) client.refreshed?.()
+    this.cache.setBuild(this.routes.build)
+    if (version !== this.cache.version || this.current !== owner) return
+    if (next.r) return await this.go(next.r, { replace: true })
+    if (this.current) return await this.go(url.href, { pop: true })
+    await this.needs(next)
+    this.cache.setBuild(this.routes.build)
+    if (version !== this.cache.version || this.current !== owner) return
+    this.apply(next, url, url.pathname + url.search, since, false)()
+  }
+
+  invalidated = (t: string[]) => {
+    this.cache.invalidate(t)
+    this.presentation.check(this)
+    this.prefetch.cancel(true)
+    if (this.current) this.owed.push(...t)
+    else if (this.reads(t)) void this.refresh(t)
+  }
+}

package/src/run/page-skeleton.tsx

@@ -0,0 +1,35 @@
+// What navigation shows for a level whose generated shape has no structure of its own (`$weftShapeThin`): a route
+// whose markup is one component the compiler can't see into. A page gets a page's outline, a layout stands aside for
+// its page's. A route's own `export const skeleton` is what fits exactly; this keeps the outlet from going blank.
+
+/** One placeholder bar. The colour is the fallback without Warp; Warp's skeleton styles paint and shimmer it. */
+const bar = (height: string, width: string, gap = '0.75em') =>
+  `display:block;block-size:${height};inline-size:${width};margin-block-end:${gap};border-radius:0.375em;background:color-mix(in srgb,currentColor 9%,transparent)`
+
+/** A heading, a lede and a block of text, then a panel: the outline most pages share. */
+export function PageSkeleton() {
+  return (
+    <div
+      data-scope="skeleton-scope"
+      aria-busy="true"
+      role="status"
+      aria-label="Loading"
+      inert
+      data-weft-page-skeleton=""
+      style="display:block;min-inline-size:0;padding-block:clamp(1.5rem,4vw,2.5rem)"
+    >
+      <span data-skeleton style={bar('2.25em', 'min(22ch,60%)', '1.25em')}></span>
+      <span data-skeleton style={bar('1em', 'min(60ch,92%)')}></span>
+      <span data-skeleton style={bar('1em', 'min(48ch,74%)', '2em')}></span>
+      <span data-skeleton style={bar('0.9em', '100%')}></span>
+      <span data-skeleton style={bar('0.9em', '96%')}></span>
+      <span data-skeleton style={bar('0.9em', '88%', '2em')}></span>
+      <span data-skeleton style={bar('14em', '100%', '0')}></span>
+    </div>
+  )
+}
+
+/** A layout with nothing to show of its own: its page's skeleton, in place. */
+export function PassThroughSkeleton(props: { children?: unknown }) {
+  return <>{props.children}</>
+}

package/src/run/prefetch.ts

@@ -0,0 +1,128 @@
+import type { RouteCache, Read } from './cache'
+import { ask } from './helpers'
+
+type Intent = 'hover' | 'focus'
+type Network = { saveData?: boolean; effectiveType?: string }
+type Job = { ctrl: AbortController; promise: Promise<Read | undefined>; promoted: boolean }
+
+/** Buffer at most the reservation, canceling the response stream when it is exceeded. */
+async function limited(response: Response, limit: number, signal: AbortSignal): Promise<Response> {
+  if (signal.aborted) throw new DOMException('Aborted', 'AbortError')
+  if (!response.body) return response
+  const reader = response.body.getReader(),
+    chunks: Uint8Array[] = []
+  let bytes = 0
+  const abort = () => {
+    void reader.cancel().catch(() => {})
+  }
+  signal.addEventListener('abort', abort, { once: true })
+  try {
+    for (;;) {
+      const item = await reader.read()
+      if (signal.aborted) throw new DOMException('Aborted', 'AbortError')
+      if (item.done) break
+      bytes += item.value.byteLength
+      if (bytes > limit) {
+        abort()
+        throw new Error('Prefetch reservation exceeded')
+      }
+      chunks.push(item.value)
+    }
+  } finally {
+    signal.removeEventListener('abort', abort)
+    reader.releaseLock()
+  }
+  const body = new Uint8Array(bytes)
+  let offset = 0
+  for (const chunk of chunks) {
+    body.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  })
+}
+
+/** Admit and deduplicate bounded route-data speculation without evaluating route modules. */
+export class Prefetch {
+  private jobs = new Map<string, Job>()
+  private stopped = false
+  private used: { at: number; bytes: number }[] = []
+
+  constructor(
+    private cache: RouteCache,
+    private now: () => number,
+    private canSeed: () => boolean,
+  ) {}
+
+  get size() {
+    return this.jobs.size
+  }
+  private key(url: URL) {
+    return url.pathname + url.search
+  }
+
+  start(url: URL, intent: Intent, network: Network | undefined, online: boolean) {
+    const key = this.key(url)
+    if (this.stopped || this.jobs.has(key)) return
+    if (!online || network?.saveData) return
+    const kind = network?.effectiveType
+    const fast = kind === '4g',
+      slow = kind === '2g' || kind === 'slow-2g'
+    if (!fast && intent === 'hover') return
+    const cap = (fast ? 64 : slow ? 8 : 16) * 1024
+    const allowance = (fast ? 256 : slow ? 16 : 32) * 1024
+    const cost = this.cache.estimate(url)
+    if (!cost || cost.total > cap || this.jobs.size >= (fast ? 2 : 1)) return
+    const now = performance.now()
+    this.used = this.used.filter((entry) => now - entry.at < 30_000)
+    if (this.used.reduce((sum, entry) => sum + entry.bytes, 0) + cost.total > allowance) return
+    this.used.push({ at: now, bytes: cost.total })
+    const ctrl = new AbortController()
+    const job: Job = { ctrl, promoted: false, promise: Promise.resolve(undefined) }
+    this.jobs.set(key, job)
+    const version = this.cache.version
+    const fetchRoute = async (target: URL, signal: AbortSignal, tag?: string) => {
+      if (version !== this.cache.version) throw new DOMException('Aborted', 'AbortError')
+      return limited(await ask(target, signal, tag), cost.data, signal)
+    }
+    job.promise = this.cache
+      .read(url, ctrl.signal, fetchRoute, this.now, this.canSeed)
+      .then((result) =>
+        ctrl.signal.aborted || version !== this.cache.version ? undefined : result,
+      )
+      .catch(() => undefined)
+      .finally(() => {
+        if (this.jobs.get(key) === job) this.jobs.delete(key)
+      })
+  }
+
+  /** Promote an in-flight speculative request to demand without a second fetch. */
+  claim(url: URL, signal: AbortSignal): Promise<Read | undefined> | undefined {
+    const job = this.jobs.get(this.key(url))
+    if (!job || job.ctrl.signal.aborted) return undefined
+    job.promoted = true
+    const abort = () => job.ctrl.abort()
+    if (signal.aborted) abort()
+    else signal.addEventListener('abort', abort, { once: true })
+    return job.promise.finally(() => signal.removeEventListener('abort', abort))
+  }
+
+  /** Stop this owner's pending speculation and prevent further scheduling. */
+  stop() {
+    this.stopped = true
+    this.cancel(true)
+  }
+
+  /** Schedule again after stop(): the page came back from the back/forward cache. */
+  resume() {
+    this.stopped = false
+  }
+
+  /** Cancel pending speculation, optionally including work promoted to demand. */
+  cancel(all = false) {
+    for (const job of this.jobs.values()) if (all || !job.promoted) job.ctrl.abort()
+  }
+}