@weft-js/start 0.1.0 → 0.1.2

package/src/run/boot.tsx

@@ -0,0 +1,115 @@
+import { enter, hydrate, hydration, level as staticLevel } from '@weft-js/core/dom'
+import { client, createRouteState, type Component, type RoutePayload } from '../router'
+import { App } from '../view'
+import { ErrorPage, NotFoundPage } from '../builtin'
+import { matchingRouteAssets } from '../asset-receipt.mjs'
+import type { ClientRoutes } from '../run'
+import { deferred, routeCodeReady } from './helpers'
+
+/** What the stream's scripts leave on `globalThis`: each chunk's data as it lands, and what a held Boundary builds with. */
+export const streamed = globalThis as typeof globalThis & {
+  $wc?: { r?: object; b?: object; s?: object }[]
+  $wh?: Record<string, () => void> | 0
+}
+
+export function prepare(routes: ClientRoutes, options: { container?: Element }) {
+  const container = options.container ?? document.getElementById('app')!
+  const page: RoutePayload = JSON.parse(document.getElementById('weft-route')!.textContent)
+  const data = JSON.parse(document.getElementById('weft-data')?.textContent ?? 'null')
+  const tags = page.m.map((m) => m.t ?? [])
+  const comps: Record<string, Component> = {}
+  // The built-in 404 and error pages stand in only when the app has no route file for them.
+  const builtin: Record<string, Component> = { 404: NotFoundPage, error: ErrorPage }
+  const chunk = (id: string) =>
+    comps[id]
+      ? Promise.resolve()
+      : routes.load[id]
+        ? routes.load[id]().then((m) => {
+            if (m.default) comps[id] = m.default
+          })
+        : Promise.resolve(builtin[id] && (comps[id] = builtin[id]))
+  const islands: Record<string, Component> = {}
+  const island = (id: string) =>
+    islands[id]
+      ? undefined
+      : routes.islands![id]!().then((m) => {
+          islands[id] = m.default
+        })
+  const loads = [
+    ...page.m.filter((m) => !m.s).map((m) => chunk(m.id)),
+    ...(page.i ?? []).map(island),
+  ] as Promise<void>[]
+  return { container, page, data, tags, comps, chunk, islands, island, loads, build: routes.build }
+}
+
+export function mount({
+  container,
+  page,
+  data,
+  tags,
+  comps,
+  chunk,
+  islands,
+  island,
+  build,
+}: ReturnType<typeof prepare>) {
+  page.m.forEach((m, i) => {
+    for (const k of m.d ?? [])
+      if (!m.s) (m.data as Record<string, unknown>)[k] = deferred(page.p, i, k)
+  })
+  const route = createRouteState(page, comps)
+  route.assetBytes = matchingRouteAssets(page.a, build)
+  let bag: RoutePayload['b']
+  route.mount = (html, depth, next) =>
+    staticLevel(
+      html,
+      depth,
+      next,
+      (id) => islands[id]! as never,
+      bag ?? undefined,
+      (id) => Promise.resolve(island(id)),
+    )
+  route.around = (_d, _id, body) => enter(body)
+  // What landed while the chunks loaded: from here on, a Boundary that's still out is held, and its chunk builds it.
+  if (data)
+    for (const l of streamed.$wc ?? []) {
+      Object.assign(data.r, l.r)
+      Object.assign(data.b, l.b)
+      if (l.s) Object.assign((data.s ??= {}), l.s)
+    }
+  // What a Boundary still out claims its chunk with, once it lands: a claim like this one, of nodes that came after it.
+  if (data?.w)
+    data.w = (root: Element, fn: () => void) => {
+      for (const el of root.querySelectorAll('[wk]'))
+        hydration.registry.set(el.getAttribute('wk')!, el)
+      try {
+        fn()
+      } finally {
+        hydration.registry.clear()
+        const list = hydration.trash.splice(0)
+        setTimeout(() => {
+          for (const n of list) n.nodeType === 1 ? (n as Element).removeAttribute('wk') : n.remove()
+        })
+      }
+    }
+  hydrate(() => <App route={route} />, container, { data })
+  client.route = route
+  // The stream broke or failed before its last script: what's held takes its default, not a skeleton for good.
+  if (data?.w) {
+    const over = () => {
+      const h = streamed.$wh || {}
+      streamed.$wh = 0
+      for (const k in h) h[k]!()
+    }
+    document.readyState === 'complete' ? over() : addEventListener('load', over, { once: true })
+  }
+
+  return {
+    route,
+    chunk,
+    island,
+    ready: (next: RoutePayload) => routeCodeReady(next, comps, islands),
+    initialTags: tags,
+    setBag: (next: RoutePayload['b']) => (bag = next),
+  }
+}

package/src/run/cache-presentation.ts

@@ -0,0 +1,67 @@
+import { client } from '../router'
+import { guess } from './helpers'
+import type { RouteCache } from './cache'
+import type { Navigation } from './navigation'
+
+type Cached = NonNullable<ReturnType<RouteCache['peek']>>
+
+/** Own the one provisional history presentation and its expiry timer. */
+export class CachePresentation {
+  private pending:
+    | { ctrl: AbortController; url: URL; timer: ReturnType<typeof setTimeout> }
+    | undefined
+
+  show(nav: Navigation, ctrl: AbortController, url: URL, cached: Cached | undefined) {
+    if (!cached || !nav.ready?.(cached.next)) return false
+    nav.cache.setBuild(nav.routes.build)
+    if (cached.version !== nav.cache.version || ctrl.signal.aborted || nav.current !== ctrl)
+      return false
+    nav.apply(cached.next, url, url.pathname + url.search, cached.since, false)()
+    nav.cache.setBuild(nav.routes.build)
+    if (ctrl.signal.aborted || nav.current !== ctrl) return false
+    if (this.pending) clearTimeout(this.pending.timer)
+    const timer = setTimeout(() => this.check(nav), Math.max(0, cached.until! - performance.now()))
+    this.pending = { ctrl, url, timer }
+    this.check(nav)
+    return true
+  }
+
+  check(nav: Navigation) {
+    const pending = this.pending
+    if (!pending || nav.current !== pending.ctrl || pending.ctrl.signal.aborted) return
+    const cached = nav.cache.peek(pending.url, !!client.seed)
+    if (cached) {
+      clearTimeout(pending.timer)
+      pending.timer = setTimeout(
+        () => this.check(nav),
+        Math.max(1, Math.ceil(cached.until! - performance.now())),
+      )
+      return
+    }
+    if (!nav.present(guess(nav.routes, pending.url.pathname), pending.url, true)) {
+      nav.current = undefined
+      pending.ctrl.abort()
+      location.replace(pending.url.href)
+    }
+  }
+
+  stop(ctrl: AbortController) {
+    if (this.pending?.ctrl !== ctrl) return
+    clearTimeout(this.pending.timer)
+    this.pending = undefined
+  }
+}
+
+/** Wait for one retry, or stop promptly when a newer navigation cancels it. */
+export function retryDelay(signal: AbortSignal, ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const finish = () => {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', finish)
+      resolve()
+    }
+    const timer = setTimeout(finish, ms)
+    if (signal.aborted) finish()
+    else signal.addEventListener('abort', finish, { once: true })
+  })
+}

package/src/run/cache.ts

@@ -0,0 +1,254 @@
+import type { RoutePayload } from '../router'
+
+const LIMIT = 32
+const BYTES = 4 * 1024 * 1024
+
+type Entry = {
+  body: string
+  bytes: number
+  tag: string
+  tags: string[]
+  since: number
+  until: number
+}
+export type Read = {
+  next: RoutePayload
+  since: number
+  version: number
+  notModified?: boolean
+  until?: number
+}
+type FetchRoute = (url: URL, signal: AbortSignal, tag?: string) => Promise<Response>
+
+/** Bounded route bodies for conditional validation; never serves unvalidated content. */
+export class RouteCache {
+  private entries = new Map<string, Entry>()
+  private bytes = 0
+  private epoch = 0
+  version = 0
+
+  constructor(private build: string | null | undefined) {}
+
+  /** Drop old validators when the client build identity changes. */
+  setBuild(build: string | null | undefined) {
+    if (this.build === build) return
+    this.clear()
+    this.build = build
+  }
+
+  private key(url: URL) {
+    return this.build
+      ? JSON.stringify([this.build, this.epoch, url.pathname + url.search])
+      : undefined
+  }
+
+  private remove(key: string) {
+    const old = this.entries.get(key)
+    if (old) this.bytes -= old.bytes
+    this.entries.delete(key)
+  }
+
+  /** Forget affected loader data and invalidate every request already in flight. */
+  invalidate(tags: string[]) {
+    this.version++
+    for (const [key, value] of this.entries)
+      if (value.tags.some((tag) => tags.includes(tag))) this.remove(key)
+  }
+
+  /** Drop all build/session-dependent bodies and validators. */
+  clear() {
+    this.version++
+    this.epoch++
+    this.entries.clear()
+    this.bytes = 0
+  }
+
+  private allowed(response: Response) {
+    const policy = response.headers.get('cache-control') ?? ''
+    const directives = policy.split(',').map((part) => part.trim().toLowerCase())
+    const vary = (response.headers.get('vary') ?? '')
+      .split(',')
+      .map((part) => part.trim().toLowerCase())
+    return (
+      directives.includes('private') &&
+      !directives.some((part) => /^no-store(?:\s*=|$)/.test(part)) &&
+      !response.headers.has('set-cookie') &&
+      ['accept', 'cookie', 'authorization'].every((v) => vary.includes(v)) &&
+      vary.every((v) => ['accept', 'cookie', 'authorization'].includes(v))
+    )
+  }
+
+  private until(response: Response, started: number) {
+    if (!this.allowed(response)) return 0
+    const parts = (response.headers.get('cache-control') ?? '')
+      .split(',')
+      .map((s) => s.trim().toLowerCase())
+    if (parts.some((s) => /^(?:no-cache|must-revalidate|proxy-revalidate)(?:\s*=|$)/.test(s)))
+      return 0
+    const max = parts.filter((s) => /^max-age=\d+$/.test(s))
+    const stale = parts.filter((s) => /^stale-while-revalidate=\d+$/.test(s))
+    if (
+      max.length !== 1 ||
+      stale.length > 1 ||
+      parts.some(
+        (s) =>
+          /^(?:max-age|stale-while-revalidate)\s*=/.test(s) &&
+          !/^(?:max-age|stale-while-revalidate)=\d+$/.test(s),
+      )
+    )
+      return 0
+    const age = response.headers.get('age')
+    if (age !== null && !/^\d+$/.test(age)) return 0
+    const date = response.headers.get('date')
+    const sent = date === null ? Date.now() : Date.parse(date)
+    if (!Number.isFinite(sent)) return 0
+    const seconds = Number(max[0]!.slice(8)) + Math.min(30, Number(stale[0]?.split('=')[1] ?? 0))
+    const now = performance.now()
+    const transit = Math.max(0, now - started)
+    const elapsed = Math.max(Number(age ?? 0) * 1000 + transit, Date.now() - sent, transit)
+    return now + Math.max(0, Math.min(30_000, seconds * 1000 - elapsed))
+  }
+
+  /** Read only a still-permitted body; callers must also prove its code is loaded. */
+  peek(url: URL, canSeed: boolean): Read | undefined {
+    const key = this.key(url),
+      entry = key && this.entries.get(key)
+    if (!key || !entry || performance.now() >= entry.until) return undefined
+    const next = JSON.parse(entry.body) as RoutePayload
+    if (next.c?.length && !canSeed) return undefined
+    this.entries.delete(key)
+    this.entries.set(key, entry)
+    return { next, since: entry.since, version: this.version, until: entry.until }
+  }
+
+  /** Conservative known route cost; unknown or mismatched receipts cannot be speculated. */
+  estimate(url: URL) {
+    const key = this.key(url),
+      entry = key && this.entries.get(key)
+    if (!entry) return undefined
+    const next = JSON.parse(entry.body) as RoutePayload
+    const cost = next.a
+    if (
+      !cost ||
+      cost.build !== this.build ||
+      cost.scope !== 'vite-static-closure' ||
+      typeof cost.routeBytes !== 'number' ||
+      !Number.isSafeInteger(cost.routeBytes) ||
+      cost.routeBytes < 0
+    )
+      return undefined
+    const data = Math.max(entry.bytes, 8 * 1024)
+    const total = data + cost.routeBytes
+    return Number.isSafeInteger(total) ? { data, total } : undefined
+  }
+
+  private store(
+    key: string | undefined,
+    response: Response,
+    body: string,
+    next: RoutePayload,
+    seed: { since: number; canSeed: boolean; started: number },
+  ) {
+    const { since, canSeed, started } = seed
+    if (!key) return
+    this.remove(key)
+    const tag = response.headers.get('etag')
+    const bytes = new TextEncoder().encode(body).byteLength
+    if (
+      response.status !== 200 ||
+      next.s !== 200 ||
+      next.r ||
+      !tag ||
+      !this.allowed(response) ||
+      (next.c?.length && !canSeed) ||
+      bytes > BYTES
+    )
+      return
+    const tags = [...new Set(next.m.flatMap((match) => match.t ?? []))]
+    this.entries.set(key, { body, bytes, tag, tags, since, until: this.until(response, started) })
+    this.bytes += bytes
+    while (this.entries.size > LIMIT || this.bytes > BYTES)
+      this.remove(this.entries.keys().next().value!)
+  }
+
+  read(
+    url: URL,
+    signal: AbortSignal,
+    fetchRoute: FetchRoute,
+    now: () => number,
+    canSeed: () => boolean,
+  ): Promise<Read> {
+    return this.load({ url, signal, fetchRoute, now, canSeed })
+  }
+
+  /** Fetch or validate a body against the current generation before returning it. */
+  async load(o: {
+    url: URL
+    signal: AbortSignal
+    fetchRoute: FetchRoute
+    now: () => number
+    canSeed: () => boolean
+    onForget?: (() => void) | undefined
+  }): Promise<Read> {
+    const { url, signal, fetchRoute, now, canSeed, onForget } = o
+    let allowTag = true
+    for (;;) {
+      if (signal.aborted) throw new DOMException('Aborted', 'AbortError')
+      const version = this.version,
+        key = this.key(url)
+      const cached = key && allowTag ? this.entries.get(key) : undefined
+      let since = now()
+      const started = performance.now()
+      const response = await fetchRoute(url, signal, cached?.tag)
+      if (signal.aborted) throw new DOMException('Aborted', 'AbortError')
+      if (version !== this.version) continue
+      if (response.status === 401 || response.status === 403) {
+        this.clear()
+        onForget?.()
+        throw new Error('Route authorization failed')
+      }
+      let body: string
+      if (response.status === 304) {
+        if (
+          !cached ||
+          !key ||
+          !this.allowed(response) ||
+          response.headers.get('etag') !== cached.tag ||
+          this.entries.get(key) !== cached
+        ) {
+          if (key) this.remove(key)
+          onForget?.()
+          if (!allowTag) throw new Error('Unexpected route 304')
+          allowTag = false
+          continue
+        }
+        body = cached.body
+        since = cached.since
+        cached.until = this.until(response, started)
+        this.entries.delete(key)
+        this.entries.set(key, cached)
+      } else {
+        body = await response.text()
+        if (signal.aborted) throw new DOMException('Aborted', 'AbortError')
+        if (version !== this.version) continue
+      }
+      const next = JSON.parse(body) as RoutePayload
+      if (next.s === 401 || next.s === 403) {
+        this.clear()
+        return { next, since, version: this.version }
+      }
+      if (response.status === 304 && next.c?.length && !canSeed()) {
+        if (key) this.remove(key)
+        onForget?.()
+        allowTag = false
+        continue
+      }
+      if (response.status !== 304) {
+        if (next.p !== url.pathname + url.search && key) this.remove(key)
+        else this.store(key, response, body, next, { since, canSeed: canSeed(), started })
+        if (!next.r && !this.peek(url, canSeed())) onForget?.()
+      }
+      return { next, since, version, notModified: response.status === 304 }
+    }
+  }
+}

package/src/run/helpers.ts

@@ -0,0 +1,197 @@
+import { flush } from '@weft-js/core'
+import { rt } from '@weft-js/core/internal'
+import type { Component, Match, RoutePayload } from '../router'
+import type { ClientRoutes } from '../run'
+import type { Navigation } from './navigation'
+
+/**
+ * A deferred field on a page that loaded with its value still out. A chunk brings what's rendered from it; this is for
+ * the render that hasn't one, a Boundary's retry or one the stream gave up on. The route has it, and only that asks.
+ */
+export function deferred(path: string, level: number, key: string): PromiseLike<unknown> {
+  let got: Promise<unknown> | undefined
+  const value = () => {
+    if (rt.probe) return new Promise(() => {}) // a hydrate run only tracks its reads, and nothing waits on what it gets
+    if (!got) {
+      got = ask(new URL(path, location.href))
+        .then((r) => (r.ok ? r.json() : Promise.reject(new Error('Server function failed.'))))
+        .then((next: RoutePayload) => (next.m[level]!.data as Record<string, unknown>)[key])
+      got.catch(() => (got = undefined))
+    }
+    return got
+  }
+  return {
+    // oxlint-disable-next-line unicorn/no-thenable -- it is a promise, one that asks the server only once something awaits it
+    then: (ok, no) => value().then(ok, no),
+    catch: (no?: (e: unknown) => unknown) => value().catch(no),
+    finally: (fn?: () => void) => value().finally(fn),
+  } as PromiseLike<unknown>
+}
+
+export const ask = (url: URL, signal?: AbortSignal, tag?: string) =>
+  fetch(`/_weft/data${url.pathname === '/' ? '' : url.pathname}${url.search}`, {
+    signal: signal ?? null,
+    cache: 'no-cache',
+    headers: { accept: 'application/json', ...(tag && { 'if-none-match': tag }) },
+  })
+
+/** Whether every client component and island required by a route is already loaded. */
+export function routeCodeReady(
+  next: RoutePayload,
+  comps: Record<string, Component>,
+  islands: Record<string, Component>,
+) {
+  return next.m.every((m) => m.s || !!comps[m.id]) && (next.i ?? []).every((id) => !!islands[id])
+}
+
+/** The URL a client navigation would take from this event's link, or nothing for a link the browser should follow. */
+export function ours(target: EventTarget | null) {
+  const a = (target as Element | null)?.closest?.('a')
+  if (
+    !a ||
+    (a.target && a.target.toLowerCase() !== '_self') ||
+    a.hasAttribute('download') ||
+    [...a.relList].some((token) => token.toLowerCase() === 'external')
+  )
+    return
+  const url = new URL(a.href, location.href)
+  if (url.origin !== location.origin || url.pathname.startsWith('/_weft/')) return
+  return url.pathname === location.pathname && url.search === location.search && url.hash
+    ? undefined
+    : url // not an in-page anchor
+}
+
+/** A kept static level has no binding for its links' current-page state: the same rule as `Link`, after the swap. */
+export function current_(path: string) {
+  flush()
+  for (const a of document.querySelectorAll<HTMLAnchorElement>('a[href]')) {
+    let match = false
+    try {
+      const url = new URL(a.href)
+      const section = a.dataset.match === 'section'
+      match =
+        url.origin === location.origin &&
+        !url.search &&
+        !url.hash &&
+        (url.pathname === path ||
+          (section &&
+            url.pathname !== '/' &&
+            path.startsWith(`${url.pathname.replace(/\/$/, '')}/`)))
+    } catch {
+      /* malformed links cannot match */
+    }
+    if (match && !a.hasAttribute('aria-current')) a.setAttribute('aria-current', 'page')
+    else if (!match && a.getAttribute('aria-current') === 'page') a.removeAttribute('aria-current')
+  }
+}
+
+/** Deferred fields arrive resolved on navigation: they become settled promises again, so resources read them alike. */
+export function revive(m: Match): Match {
+  if (!m.d?.length) return m
+  const data = { ...(m.data as Record<string, unknown>) }
+  for (const k of m.d) data[k] = Promise.resolve(data[k])
+  return { ...m, data }
+}
+
+/** The route ids `pathname` probably needs (its layouts and page), from the table; the server's answer decides. */
+export function guess(routes: ClientRoutes, pathname: string): string[] {
+  // A server load canonicalizes trailing slashes before it has a page match.
+  if (pathname.length > 1 && pathname.endsWith('/')) return []
+  let parts: string[]
+  try {
+    const path = pathname.replace(/^\/+|\/+$/g, '')
+    parts = path ? path.split('/').map(decodeURIComponent) : []
+  } catch {
+    return []
+  }
+  for (const r of routes.table) {
+    const segs = r.pattern.split('/').filter(Boolean)
+    const splat = segs.at(-1) === '$'
+    if (splat ? parts.length < segs.length - 1 : parts.length !== segs.length) continue
+    if (
+      segs.every(
+        (s, i) =>
+          s === '$' ||
+          (s.startsWith('$') ? !!parts[i] : s.toLowerCase() === parts[i]?.toLowerCase()),
+      )
+    )
+      return [...r.layouts, r.id]
+  }
+  return []
+}
+
+/** Find the outlet whose route parameter changed against the committed URL. */
+export function changedRouteParams(
+  routes: ClientRoutes,
+  committedURL: string,
+  ids: string[],
+  url: URL,
+) {
+  const from = new URL(committedURL)
+  if (from.pathname === url.pathname && from.search === url.search) return -1
+  const route = routes.table.find((item) => item.id === ids.at(-1))
+  if (!route || guess(routes, from.pathname).join('\0') !== ids.join('\0')) return -1
+  try {
+    const partsOf = (path: string) => {
+      const trimmed = path.replace(/^\/+|\/+$/g, '')
+      return trimmed ? trimmed.split('/').map(decodeURIComponent) : []
+    }
+    const before = partsOf(from.pathname)
+    const after = partsOf(url.pathname)
+    const parts = route.pattern.split('/').filter(Boolean)
+    const changed = parts.findIndex(
+      (part, index) =>
+        part.startsWith('$') &&
+        (part === '$'
+          ? JSON.stringify(before.slice(index)) !== JSON.stringify(after.slice(index))
+          : before[index] !== after[index]),
+    )
+    if (changed >= 0) {
+      const layout = ids.findIndex(
+        (id, depth) =>
+          depth < ids.length - 1 &&
+          id.startsWith('layout:') &&
+          id.slice(7).split('/').filter(Boolean).length > changed,
+      )
+      return layout < 0 ? ids.length - 1 : layout
+    }
+    return from.search !== url.search ? ids.length - 1 : -1
+  } catch {
+    return -1
+  }
+}
+
+const SLOW_FADE = 100
+
+/** Swaps inside a view transition when the page can take one, and plainly when not. */
+export async function crossfade(
+  nav: Pick<Navigation, 'fades' | 'painted' | 'fading'>,
+  swap: () => void,
+  swapped: () => boolean,
+) {
+  if (
+    !(
+      nav.fades &&
+      nav.painted &&
+      'startViewTransition' in document &&
+      !document.hidden &&
+      !matchMedia('(prefers-reduced-motion: reduce)').matches
+    )
+  )
+    return swap()
+  const started = performance.now()
+  const fade = (nav.fading = document.startViewTransition(swap))
+  void fade.ready
+    .then(() => {
+      if (performance.now() - started > SLOW_FADE) nav.fades = false
+      return fade.finished
+    })
+    .catch(() => {})
+    .then(() => {
+      if (nav.fading === fade) nav.fading = undefined
+    })
+  // A transition the browser aborts rejects `finished`: the page already swapped.
+  void fade.finished.catch(() => {})
+  // Aborted before its update ran ("invalid state"): swap without the fade.
+  await fade.updateCallbackDone.catch(() => swapped() || swap())
+}