one 1.2.79 → 1.2.81

package/src/link/prefetchIntent.ts

@@ -0,0 +1,174 @@
+/**
+ * Intent-based link prefetching using mouse trajectory prediction.
+ *
+ * Uses ray-casting to detect when the user is moving toward a link,
+ * scoring by distance + perpendicular offset. Winner-takes-all prevents
+ * over-fetching when multiple links are in the path.
+ *
+ * Key features:
+ * - Batched IntersectionObserver for efficient rect measurement (300ms intervals)
+ * - Velocity smoothing to filter jitter
+ * - Prefetched links removed from future checks
+ * - Debounce between consecutive prefetches
+ */
+
+export type PrefetchIntentOptions = {
+  onPrefetch: (href: string) => void
+  /** Max distance to consider (default: 600px) */
+  maxReach?: number
+  /** Penalty multiplier for off-axis aim (default: 4) */
+  perpWeight?: number
+  /** Min mouse speed to trigger (default: 6px/frame) */
+  minSpeed?: number
+}
+
+type RectEntry = { r: DOMRectReadOnly; h: string }
+
+export function createPrefetchIntent(options: PrefetchIntentOptions) {
+  const { onPrefetch, maxReach = 500, perpWeight = 5, minSpeed = 8 } = options
+
+  const done = new Set<string>()
+  let rects: RectEntry[] = []
+  let px = 0,
+    py = 0,
+    vx = 0,
+    vy = 0
+  let moveCount = 0
+  let lastPrefetchMove = 0
+
+  function setRects(newRects: RectEntry[]) {
+    rects = newRects.filter((r) => !done.has(r.h))
+  }
+
+  function move(x: number, y: number, dx: number, dy: number) {
+    moveCount++
+    // less smoothing on first few moves to build velocity faster
+    const smooth = moveCount < 3 ? 0.3 : 0.6
+    vx = vx * smooth + dx * (1 - smooth)
+    vy = vy * smooth + dy * (1 - smooth)
+    px = x
+    py = y
+
+    const speed = Math.sqrt(vx * vx + vy * vy)
+    if (speed < minSpeed) return
+
+    // normalize velocity to unit vector
+    const ux = vx / speed
+    const uy = vy / speed
+
+    let best = Infinity
+    let href = ''
+
+    for (const { r, h } of rects) {
+      // vector from cursor to link center
+      const cx = (r.left + r.right) / 2 - px
+      const cy = (r.top + r.bottom) / 2 - py
+      const dist = Math.sqrt(cx * cx + cy * cy)
+
+      // project center onto velocity ray: how far along the ray?
+      const along = cx * ux + cy * uy
+      if (along < 0) continue // behind us
+
+      // perpendicular distance from ray to center
+      const perpX = cx - along * ux
+      const perpY = cy - along * uy
+      const perp = Math.sqrt(perpX * perpX + perpY * perpY)
+
+      // miss if perpendicular distance > half the link size + margin
+      // scale margin by distance - farther = need tighter aim
+      const baseRadius = Math.max(r.width, r.height) / 2 + 30
+      const distanceFactor = Math.max(0.2, 1 - dist / 1000)
+      const radius = baseRadius * distanceFactor + 20
+      if (perp > radius) continue
+
+      // score: balance distance and aim quality
+      // absolute perp matters more than relative - being 70px off at any distance is worse than 20px off
+      // score = distance + perp * perpWeight (lower is better)
+      const score = along + perp * perpWeight
+      if (score < best) {
+        best = score
+        href = h
+      }
+    }
+
+    // winner takes all with max reach
+    // debounce: skip if we just prefetched on previous move
+    if (href && best < maxReach && moveCount - lastPrefetchMove > 1) {
+      done.add(href)
+      rects = rects.filter((r) => r.h !== href)
+      lastPrefetchMove = moveCount
+      onPrefetch(href)
+    }
+  }
+
+  // for integration with DOM
+  const nodes = new Map<HTMLElement, string>()
+
+  function observe(el: HTMLElement, href: string) {
+    nodes.set(el, href)
+    return () => {
+      nodes.delete(el)
+      done.delete(href)
+    }
+  }
+
+  return { setRects, move, observe, nodes, done }
+}
+
+// singleton for actual DOM usage
+let instance: ReturnType<typeof createPrefetchIntent> | null = null
+let started = false
+
+export function startPrefetchIntent(onPrefetch: (href: string) => void) {
+  if (started) return instance!
+  started = true
+
+  instance = createPrefetchIntent({ onPrefetch })
+
+  let frame = 0
+  let px = 0,
+    py = 0
+
+  // batch measure all nodes using single IntersectionObserver
+  function measure() {
+    if (!instance!.nodes.size) return setTimeout(measure, 300)
+    const io = new IntersectionObserver((entries) => {
+      io.disconnect()
+      instance!.setRects(
+        entries
+          .filter((e) => e.isIntersecting)
+          .map((e) => ({
+            r: e.boundingClientRect,
+            h: instance!.nodes.get(e.target as HTMLElement)!,
+          }))
+          .filter((x) => x.h)
+      )
+      setTimeout(measure, 300)
+    })
+    instance!.nodes.forEach((_, el) => io.observe(el))
+  }
+  measure()
+
+  document.addEventListener(
+    'mousemove',
+    (e) => {
+      // throttle to every 4th frame (~66ms at 60fps)
+      if (++frame % 4) return
+
+      const dx = e.clientX - px
+      const dy = e.clientY - py
+      px = e.clientX
+      py = e.clientY
+
+      instance!.move(px, py, dx, dy)
+    },
+    { passive: true }
+  )
+
+  return instance
+}
+
+export function observePrefetchIntent(el: HTMLElement, href: string) {
+  if (!instance) return () => {}
+  return instance.observe(el, href)
+}

package/src/link/prefetchViewport.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it, beforeEach, vi } from 'vitest'
+import { createPrefetchViewport } from './prefetchViewport'
+
+// mock IntersectionObserver
+let mockIOCallback: IntersectionObserverCallback
+const mockObserved = new Set<Element>()
+
+vi.stubGlobal(
+  'IntersectionObserver',
+  class {
+    constructor(callback: IntersectionObserverCallback) {
+      mockIOCallback = callback
+    }
+    observe(el: Element) {
+      mockObserved.add(el)
+    }
+    unobserve(el: Element) {
+      mockObserved.delete(el)
+    }
+    disconnect() {
+      mockObserved.clear()
+    }
+  }
+)
+
+function simulateIntersect(el: Element, isIntersecting: boolean) {
+  mockIOCallback(
+    [{ target: el, isIntersecting } as IntersectionObserverEntry],
+    {} as IntersectionObserver
+  )
+}
+
+describe('prefetchViewport', () => {
+  let prefetched: string[]
+  let vp: ReturnType<typeof createPrefetchViewport>
+
+  beforeEach(() => {
+    prefetched = []
+    mockObserved.clear()
+    vp = createPrefetchViewport()
+    vp.start((href) => prefetched.push(href))
+  })
+
+  it('prefetches when link enters viewport', () => {
+    const el = {} as HTMLElement
+    vp.observe(el, '/about')
+
+    simulateIntersect(el, true)
+    expect(prefetched).toEqual(['/about'])
+  })
+
+  it('does not prefetch when link exits viewport', () => {
+    const el = {} as HTMLElement
+    vp.observe(el, '/about')
+
+    simulateIntersect(el, false)
+    expect(prefetched).toEqual([])
+  })
+
+  it('only prefetches each href once', () => {
+    const el = {} as HTMLElement
+    vp.observe(el, '/about')
+
+    simulateIntersect(el, true)
+    simulateIntersect(el, false)
+    simulateIntersect(el, true)
+
+    expect(prefetched).toEqual(['/about'])
+  })
+
+  it('cleanup re-enables prefetch for href', () => {
+    const el = {} as HTMLElement
+    const cleanup = vp.observe(el, '/about')
+
+    simulateIntersect(el, true)
+    expect(prefetched).toEqual(['/about'])
+
+    cleanup()
+    prefetched.length = 0
+
+    // re-observe same href after cleanup
+    vp.observe(el, '/about')
+    simulateIntersect(el, true)
+    expect(prefetched).toEqual(['/about'])
+  })
+
+  describe('memory and performance', () => {
+    it('does not leak elements after cleanup', () => {
+      const elements: HTMLElement[] = []
+      const cleanups: (() => void)[] = []
+
+      // add 100 elements
+      for (let i = 0; i < 100; i++) {
+        const el = {} as HTMLElement
+        elements.push(el)
+        cleanups.push(vp.observe(el, `/page-${i}`))
+      }
+
+      expect(vp.nodes.size).toBe(100)
+
+      // cleanup all
+      cleanups.forEach((c) => c())
+
+      expect(vp.nodes.size).toBe(0)
+      expect(vp.done.size).toBe(0)
+    })
+
+    it('handles rapid observe/unobserve cycles', () => {
+      const el = {} as HTMLElement
+
+      for (let i = 0; i < 100; i++) {
+        const cleanup = vp.observe(el, '/test')
+        cleanup()
+      }
+
+      // should not leak
+      expect(vp.nodes.size).toBe(0)
+    })
+  })
+})

package/src/link/prefetchViewport.ts

@@ -0,0 +1,62 @@
+/**
+ * Viewport-based link prefetching using IntersectionObserver.
+ *
+ * Prefetches links when they enter the viewport with 100px margin.
+ * Lighter weight than intent-based, good for content-heavy pages.
+ */
+
+export type ViewportPrefetcher = ReturnType<typeof createPrefetchViewport>
+
+export function createPrefetchViewport() {
+  const done = new Set<string>()
+  const nodes = new Map<HTMLElement, string>()
+  let io: IntersectionObserver | null = null
+  let onPrefetch: ((href: string) => void) | null = null
+
+  function getObserver() {
+    if (io) return io
+    io = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (!entry.isIntersecting) continue
+          const href = nodes.get(entry.target as HTMLElement)
+          if (href && !done.has(href)) {
+            done.add(href)
+            onPrefetch?.(href)
+          }
+        }
+      },
+      { threshold: 0.5 } // fires when mostly visible
+    )
+    return io
+  }
+
+  function start(prefetch: (href: string) => void) {
+    onPrefetch = prefetch
+  }
+
+  function observe(el: HTMLElement, href: string) {
+    nodes.set(el, href)
+    getObserver().observe(el)
+    return () => {
+      nodes.delete(el)
+      io?.unobserve(el)
+      done.delete(href)
+    }
+  }
+
+  return { start, observe, done, nodes }
+}
+
+// singleton for actual DOM usage
+let instance: ViewportPrefetcher | null = null
+
+export function startPrefetchViewport(prefetch: (href: string) => void) {
+  if (!instance) instance = createPrefetchViewport()
+  instance.start(prefetch)
+}
+
+export function observePrefetchViewport(el: HTMLElement, href: string) {
+  if (!instance) instance = createPrefetchViewport()
+  return instance.observe(el, href)
+}

package/src/router/findRouteNode.ts

@@ -125,3 +125,70 @@ export function extractPathnameFromHref(href: string): string {
 
   return href.slice(0, endIndex)
 }
+
+/**
+ * Find all route nodes from root to the current page based on navigation state.
+ * Returns an array of RouteNodes in order from root layout to the page.
+ * This is used on native to build the full matches array including layouts.
+ */
+export function findAllRouteNodesFromState(
+  state: { routes: Array<{ name: string; state?: any }> } | undefined,
+  rootNode: RouteNode | null
+): RouteNode[] {
+  if (!state || !rootNode) {
+    return []
+  }
+
+  const nodes: RouteNode[] = []
+
+  function collectNodes(
+    currentState: { routes: Array<{ name: string; state?: any; params?: Record<string, any> }> } | undefined,
+    parentNode: RouteNode | null
+  ) {
+    if (!currentState || !parentNode) {
+      return
+    }
+
+    // get the current route from state (the active one based on index)
+    const currentRoute = currentState.routes[currentState.routes.length - 1]
+    if (!currentRoute) {
+      return
+    }
+
+    // find the matching child node
+    const matchingNode = findNodeByRouteName(parentNode, currentRoute.name)
+    if (!matchingNode) {
+      if (process.env.NODE_ENV === 'development') {
+        console.log('[one] findAllRouteNodesFromState: could not find node for', currentRoute.name, 'in', parentNode.route)
+      }
+      return
+    }
+
+    // add this node to the list
+    nodes.push(matchingNode)
+
+    // if there's a nested state, continue recursively
+    if (currentRoute.state && currentRoute.state.routes) {
+      collectNodes(currentRoute.state, matchingNode)
+    } else if (currentRoute.params?.screen) {
+      // react navigation uses params.screen to specify child route when state isn't created yet
+      // this happens on initial render before the nested navigator mounts
+      const childRouteName = currentRoute.params.screen as string
+      const childNode = matchingNode.children.find((c) => c.route === childRouteName)
+      if (childNode) {
+        nodes.push(childNode)
+        // if there are nested params, continue recursively
+        if (currentRoute.params.params && (currentRoute.params.params as any).screen) {
+          collectNodes(
+            { routes: [{ name: childRouteName, params: currentRoute.params.params }] },
+            childNode
+          )
+        }
+      }
+    }
+  }
+
+  collectNodes(state, rootNode)
+  return nodes
+}
+

package/src/router/router.ts

@@ -37,6 +37,7 @@ import {
   extractPathnameFromHref,
   extractSearchFromHref,
   findRouteNodeFromState,
+  findAllRouteNodesFromState,
 } from './findRouteNode'
 import type { UrlObject } from './getNormalizedStatePath'
 import { getRouteInfo } from './getRouteInfo'
@@ -399,6 +400,16 @@ export function updateState(state: OneRouter.ResultState, nextStateParam = state
       console.info(`[one] 🧭 ${from} → ${to}`, params ? { params } : '')
     }
     routeInfo = nextRouteInfo
+
+    // On native, update client matches when route changes
+    // This enables useMatches to work for initial route and navigation
+    // Loader data will be undefined initially (fetched by useLoader)
+    if (process.env.TAMAGUI_TARGET === 'native') {
+      const params = extractParamsFromState(state)
+      const newMatches = buildNativeMatches(state, nextRouteInfo.pathname, params)
+      currentMatches = newMatches
+      setClientMatches(newMatches)
+    }
   }
 
   // Expose devtools API in development
@@ -717,45 +728,43 @@ export function getPreloadHistory(): PreloadEntry[] {
 }
 
 export function preloadRoute(href: string, injectCSS = false): Promise<any> | undefined {
-  if (process.env.TAMAGUI_TARGET === 'native') {
-    return
-  }
+  if (process.env.TAMAGUI_TARGET !== 'native') {
+    // in dev mode, use a simpler preload that just fetches the loader directly
+    // this avoids issues with production-only preload paths while still ensuring
+    // loader data is available before navigation completes
+    if (process.env.NODE_ENV === 'development') {
+      // normalize the path to match what useLoader uses for cache keys
+      const normalizedHref = normalizeLoaderPath(href)
+      if (!preloadingLoader[normalizedHref]) {
+        preloadingLoader[normalizedHref] = doPreloadDev(href).then((data) => {
+          preloadedLoaderData[normalizedHref] = data
+          return data
+        })
+      }
+      return preloadingLoader[normalizedHref]
+    }
 
-  // in dev mode, use a simpler preload that just fetches the loader directly
-  // this avoids issues with production-only preload paths while still ensuring
-  // loader data is available before navigation completes
-  if (process.env.NODE_ENV === 'development') {
-    // normalize the path to match what useLoader uses for cache keys
-    const normalizedHref = normalizeLoaderPath(href)
-    if (!preloadingLoader[normalizedHref]) {
-      preloadingLoader[normalizedHref] = doPreloadDev(href).then((data) => {
-        preloadedLoaderData[normalizedHref] = data
+    if (!preloadingLoader[href]) {
+      preloadingLoader[href] = doPreload(href).then((data) => {
+        // Store the resolved data for synchronous access
+        preloadedLoaderData[href] = data
         return data
       })
     }
-    return preloadingLoader[normalizedHref]
-  }
 
-  if (!preloadingLoader[href]) {
-    preloadingLoader[href] = doPreload(href).then((data) => {
-      // Store the resolved data for synchronous access
-      preloadedLoaderData[href] = data
-      return data
-    })
-  }
+    if (injectCSS) {
+      // Wait for preload to populate cssInjectFunctions, then inject CSS (max 800ms)
+      return preloadingLoader[href]?.then(async (data) => {
+        const inject = cssInjectFunctions[href]
+        if (inject) {
+          await Promise.race([inject(), new Promise((r) => setTimeout(r, 800))])
+        }
+        return data
+      })
+    }
 
-  if (injectCSS) {
-    // Wait for preload to populate cssInjectFunctions, then inject CSS (max 500ms)
-    return preloadingLoader[href]?.then(async (data) => {
-      const inject = cssInjectFunctions[href]
-      if (inject) {
-        await Promise.race([inject(), new Promise((r) => setTimeout(r, 500))])
-      }
-      return data
-    })
+    return preloadingLoader[href]
   }
-
-  return preloadingLoader[href]
 }
 
 // normalize path to match what useLoader uses for currentPath
@@ -797,6 +806,25 @@ function buildClientMatches(
   return [...layoutMatches, pageMatch]
 }
 
+/**
+ * Build all matches for native, including layouts and page.
+ * Unlike web which preserves SSR-hydrated layouts, native builds fresh
+ * since there's no SSR context to hydrate from.
+ */
+function buildNativeMatches(
+  state: OneRouter.ResultState,
+  pathname: string,
+  params: Record<string, string | string[]>
+): RouteMatch[] {
+  const allNodes = findAllRouteNodesFromState(state, routeNode)
+  return allNodes.map((node) => ({
+    routeId: node.contextKey || pathname,
+    pathname,
+    params,
+    loaderData: undefined, // loader data is fetched async by useLoader on native
+  }))
+}
+
 /**
  * Initialize client matches from server context during hydration.
  * Called from createApp when hydrating.
@@ -958,15 +986,14 @@ export async function linkTo(
   }
 
   // Update client matches for useMatches hook
-  // This runs after preload so loaderData is available
-  if (process.env.TAMAGUI_TARGET !== 'native') {
-    const normalizedPath = normalizeLoaderPath(href)
-    const loaderData = preloadedLoaderData[normalizedPath]
-    const params = extractParamsFromState(state)
-    const newMatches = buildClientMatches(href, matchingRouteNode, params, loaderData)
-    currentMatches = newMatches
-    setClientMatches(newMatches)
-  }
+  // On web: runs after preload so loaderData is available
+  // On native: runs without preloaded data (loaders are fetched by useLoader)
+  const normalizedPath = normalizeLoaderPath(href)
+  const loaderData = preloadedLoaderData[normalizedPath]
+  const params = extractParamsFromState(state)
+  const newMatches = buildClientMatches(href, matchingRouteNode, params, loaderData)
+  currentMatches = newMatches
+  setClientMatches(newMatches)
 
   const rootState = navigationRef.getRootState()