@weft-js/start 0.1.0 → 0.1.2

package/src/og/index.mjs

@@ -1,4 +1,4 @@
-// renderCard for weft (research 20 §4, §9; promoted from spikes/og/card): weft SSR HTML → PNG/JPEG/WebP/SVG, on
+// renderCard for weft (research 20 §4, §9; promoted from archive/evals-2026-11:spikes/og/card): weft SSR HTML → PNG/JPEG/WebP/SVG, on
 // Takumi, with what Satori did better added around it:
 //   - strict styles: every declaration is checked once against the renderer (an invalid value would fail the whole
 //     card, an unknown property is silently dropped) and reported as H005; production drops the bad declaration and
@@ -19,8 +19,9 @@ export const PREFLIGHT = '*,*::before,*::after{box-sizing:border-box}'
 export const SIZE = { width: 1200, height: 630 }
 const TYPES = { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp', svg: 'image/svg+xml' }
 
-const stripComments = html => html.replace(/<!--[\s\S]*?-->/g, '')
-const kebab = k => k.replace(/^Webkit/, '-webkit-').replace(/[A-Z]/g, c => '-' + c.toLowerCase())
+const stripComments = (html) => html.replace(/<!--[\s\S]*?-->/g, '')
+const kebab = (k) =>
+  k.replace(/^Webkit/, '-webkit-').replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())
 // A value no CSS grammar accepts: a property the renderer knows rejects it, and one it doesn't know takes anything.
 // (An identifier won't do: `text-overflow`, `grid-template-columns` and `font-family` accept custom idents.)
 const PROBE = '}{'
@@ -37,10 +38,21 @@ const renderers = new Map() // fonts array → the renderer registered with them
  * @param {{ name: string; data: Uint8Array; weight?: number; style?: 'normal' | 'italic' }[]} [fonts]
  * @param {{ strict?: boolean; onDiagnostic?: (d: { code: string; severity: string; message: string }) => void; images?: unknown }} [options]
  */
-export async function renderCard(html, size = SIZE, fonts = [], { strict = false, onDiagnostic, images } = {}) {
+export async function renderCard(
+  html,
+  size = SIZE,
+  fonts = [],
+  { strict = false, onDiagnostic, images } = {},
+) {
   let r = renderers.get(fonts)
-  if (!r) renderers.set(fonts, (r = native().then(backend => createCardRenderer({ backend, fonts, images }))))
-  const out = await (await r).render(html, { width: size.width ?? SIZE.width, height: size.height ?? SIZE.height, strict })
+  if (!r)
+    renderers.set(
+      fonts,
+      (r = native().then((backend) => createCardRenderer({ backend, fonts, images }))),
+    )
+  const out = await (
+    await r
+  ).render(html, { width: size.width ?? SIZE.width, height: size.height ?? SIZE.height, strict })
   for (const d of out.diagnostics) onDiagnostic?.(d)
   return out.body
 }
@@ -53,19 +65,97 @@ export async function createCardRenderer({ backend, fonts = [], images: imageOpt
   const renderer = new backend.Renderer()
   for (const font of await normalizeFonts(fonts)) await renderer.registerFont(font)
   const cache = imageCache(imageOptions.cacheBytes)
+  const prepare = createPreparation(renderer)
+
+  return {
+    /** Diagnostics only (`weft check`, dev): nothing is fetched or rasterized. */
+    async check(html) {
+      return (await prepare(html)).diagnostics
+    },
+
+    /**
+     * Renders a card. Never throws on a card's styles or images: those come back as diagnostics, and the card renders
+     * without them. `strict` (dev, `weft build`) throws on any error-severity diagnostic instead.
+     */
+    async render(
+      html,
+      { width = SIZE.width, height = SIZE.height, format = 'png', quality, strict = false } = {},
+    ) {
+      const { node, css, diagnostics, imageNodes } = await prepare(html)
+      const { images, failed } = await loadImages(
+        imageNodes.map((n) => n.src),
+        { cache, ...imageOptions },
+      )
+      for (const f of failed) {
+        diagnostics.push({
+          code: 'H008',
+          severity: 'warning',
+          message: `Card image ${f.src} didn't load (${f.reason}); the card renders without it.`,
+        })
+        for (const n of imageNodes)
+          if (n.src === f.src)
+            Object.assign(n, {
+              type: 'container',
+              src: undefined,
+              style: {
+                width: n.width && `${n.width}px`,
+                height: n.height && `${n.height}px`,
+                ...n.style,
+              },
+            })
+      }
+      if (strict && diagnostics.some((d) => d.severity === 'error')) {
+        throw Object.assign(
+          new Error(
+            diagnostics
+              .filter((d) => d.severity === 'error')
+              .map((d) => `${d.code} ${d.message} (${d.element})`)
+              .join('\n'),
+          ),
+          { diagnostics },
+        )
+      }
+      const options = { width, height, images, css: [PREFLIGHT, ...css] }
+      const body =
+        format === 'svg'
+          ? await renderer.renderSvg(node, options)
+          : new Uint8Array(
+              await renderer.render(node, {
+                ...options,
+                format,
+                ...(quality != null && { quality }),
+              }),
+            )
+      return { body, type: TYPES[format], diagnostics }
+    },
+  }
+}
+
+function createPreparation(renderer) {
   const verdicts = new Map() // `${prop}\0${value}` → null (fine) | { severity, message }
 
-  const accepts = async style => {
-    try { await renderer.measure({ type: 'container', style }, { width: 1, height: 1 }); return true } catch { return false }
+  const accepts = async (style) => {
+    try {
+      await renderer.measure({ type: 'container', style }, { width: 1, height: 1 })
+      return true
+    } catch {
+      return false
+    }
   }
   async function judge(prop, value) {
     const key = `${prop}\0${value}`
     if (verdicts.has(key)) return verdicts.get(key)
     let v = null
     if (!(await accepts({ [prop]: value }))) {
-      v = { severity: 'error', message: `\`${kebab(prop)}: ${value}\` isn't a value the card renderer accepts; the declaration is dropped.` }
+      v = {
+        severity: 'error',
+        message: `\`${kebab(prop)}: ${value}\` isn't a value the card renderer accepts; the declaration is dropped.`,
+      }
     } else if (await accepts({ [prop]: PROBE })) {
-      v = { severity: 'warning', message: `\`${kebab(prop)}\` isn't a property the card renderer supports; it has no effect.` }
+      v = {
+        severity: 'warning',
+        message: `\`${kebab(prop)}\` isn't a property the card renderer supports; it has no effect.`,
+      }
     }
     verdicts.set(key, v)
     return v
@@ -74,7 +164,8 @@ export async function createCardRenderer({ backend, fonts = [], images: imageOpt
   /** Walks the tree: checks styles (dropping invalid declarations), and collects image nodes. */
   async function prepare(html) {
     const { node, css } = fromHtml(stripComments(html))
-    const diagnostics = [], imageNodes = []
+    const diagnostics = [],
+      imageNodes = []
     const walk = async (n, path) => {
       if (n.type === 'image') imageNodes.push(n)
       for (const [prop, value] of Object.entries(n.style ?? {})) {
@@ -83,39 +174,14 @@ export async function createCardRenderer({ backend, fonts = [], images: imageOpt
         diagnostics.push({ code: 'H005', severity: v.severity, message: v.message, element: path })
         if (v.severity === 'error') delete n.style[prop]
       }
-      for (const [i, c] of (n.children ?? []).entries()) await walk(c, `${path} > ${c.tagName ?? c.type}:nth-child(${i + 1})`)
+      for (const [i, c] of (n.children ?? []).entries())
+        await walk(c, `${path} > ${c.tagName ?? c.type}:nth-child(${i + 1})`)
     }
     await walk(node, node.tagName ?? node.type)
     return { node, css, diagnostics, imageNodes }
   }
 
-  return {
-    /** Diagnostics only (`weft check`, dev): nothing is fetched or rasterized. */
-    async check(html) {
-      return (await prepare(html)).diagnostics
-    },
-
-    /**
-     * Renders a card. Never throws on a card's styles or images: those come back as diagnostics, and the card renders
-     * without them. `strict` (dev, `weft build`) throws on any error-severity diagnostic instead.
-     */
-    async render(html, { width = SIZE.width, height = SIZE.height, format = 'png', quality, strict = false } = {}) {
-      const { node, css, diagnostics, imageNodes } = await prepare(html)
-      const { images, failed } = await loadImages(imageNodes.map(n => n.src), { cache, ...imageOptions })
-      for (const f of failed) {
-        diagnostics.push({ code: 'H008', severity: 'warning', message: `Card image ${f.src} didn't load (${f.reason}); the card renders without it.` })
-        for (const n of imageNodes) if (n.src === f.src) Object.assign(n, { type: 'container', src: undefined, style: { width: n.width && `${n.width}px`, height: n.height && `${n.height}px`, ...n.style } })
-      }
-      if (strict && diagnostics.some(d => d.severity === 'error')) {
-        throw Object.assign(new Error(diagnostics.filter(d => d.severity === 'error').map(d => `${d.code} ${d.message} (${d.element})`).join('\n')), { diagnostics })
-      }
-      const options = { width, height, images, css: [PREFLIGHT, ...css] }
-      const body = format === 'svg'
-        ? await renderer.renderSvg(node, options)
-        : new Uint8Array(await renderer.render(node, { ...options, format, ...(quality != null && { quality }) }))
-      return { body, type: TYPES[format], diagnostics }
-    },
-  }
+  return prepare
 }
 
 /**
@@ -124,7 +190,10 @@ export async function createCardRenderer({ backend, fonts = [], images: imageOpt
  */
 export function cardResponse({ body, type }, { dev = false } = {}) {
   return new Response(body, {
-    headers: { 'content-type': type, 'cache-control': dev ? 'no-store' : 'public, max-age=31536000, immutable' },
+    headers: {
+      'content-type': type,
+      'cache-control': dev ? 'no-store' : 'public, max-age=31536000, immutable',
+    },
   })
 }
 
@@ -133,14 +202,21 @@ export function cardResponse({ body, type }, { dev = false } = {}) {
  * browser shows what the renderer draws.
  */
 export function previewHtml(html, { fonts = [], width = SIZE.width, height = SIZE.height } = {}) {
-  const faces = fonts.map(f => `@font-face{font-family:"${f.name}";font-weight:${f.weight ?? 400};font-style:${f.style ?? 'normal'};src:url(data:font/${fontMime(f.data)};base64,${base64(f.data)})}`).join('')
+  const faces = fonts
+    .map(
+      (f) =>
+        `@font-face{font-family:"${f.name}";font-weight:${f.weight ?? 400};font-style:${f.style ?? 'normal'};src:url(data:font/${fontMime(f.data)};base64,${base64(f.data)})}`,
+    )
+    .join('')
   return `<!doctype html><meta charset="utf-8"><style>${faces}${PREFLIGHT}html,body{margin:0}#card{width:${width}px;height:${height}px;overflow:hidden;display:flex}</style><div id="card">${stripComments(html)}</div>`
 }
 
-const fontMime = d => ({ wOFF: 'woff', wOF2: 'woff2', OTTO: 'otf' })[String.fromCharCode(...d.subarray(0, 4))] ?? 'ttf'
+const fontMime = (d) =>
+  ({ wOFF: 'woff', wOF2: 'woff2', OTTO: 'otf' })[String.fromCharCode(...d.subarray(0, 4))] ?? 'ttf'
 
 function base64(bytes) {
   let s = ''
-  for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode(...bytes.subarray(i, i + 0x8000))
+  for (let i = 0; i < bytes.length; i += 0x8000)
+    s += String.fromCharCode(...bytes.subarray(i, i + 0x8000))
   return btoa(s)
 }

package/src/og/native.mjs

@@ -1,9 +1,10 @@
 // `@takumi-rs/core`: Node, Bun and Deno servers, `weft build`, Vercel and Netlify Node functions. A file of its own so
-// an edge bundle (`@takumi-rs/wasm`, spikes/og/card/wasm.mjs) never pulls in the native addon. Both builds draw byte-identical cards (§9.4).
+// an edge bundle (`@takumi-rs/wasm`, archive/evals-2026-11:spikes/og/card/wasm.mjs) never pulls in the native addon. Both builds draw byte-identical cards (§9.4).
 export async function native() {
   // Takumi's addon in the same process as a later Rolldown pass kills a Windows `weft build` (0xC0000005) before the
   // server is written. WEFT_START_DIR means a build, and the cards come out the same.
-  if (globalThis.process?.platform === 'win32' && globalThis.process.env.WEFT_START_DIR) return wasmBackend(globalThis.process.env.WEFT_START_DIR)
+  if (globalThis.process?.platform === 'win32' && globalThis.process.env.WEFT_START_DIR)
+    return wasmBackend(globalThis.process.env.WEFT_START_DIR)
   const { Renderer } = await import('@takumi-rs/core').catch(linked)
   return { name: 'native', Renderer }
 }
@@ -21,9 +22,15 @@ async function linked(error) {
 
 /** The wasm renderer, found from `start` (the @weft-js/start directory) because a prerender runs from a bundle. */
 export async function wasmBackend(start) {
-  const [{ createRequire }, { readFile }, { dirname, join }, { pathToFileURL }] = await Promise.all(['node:module', 'node:fs/promises', 'node:path', 'node:url'].map(m => import(/* @vite-ignore */ m)))
+  const [{ createRequire }, { readFile }, { dirname, join }, { pathToFileURL }] = await Promise.all(
+    ['node:module', 'node:fs/promises', 'node:path', 'node:url'].map(
+      (m) => import(/* @vite-ignore */ m),
+    ),
+  )
   const root = dirname(dirname(createRequire(`${start}/package.json`).resolve('@takumi-rs/wasm')))
-  const { default: init, Renderer } = await import(/* @vite-ignore */ pathToFileURL(join(root, 'dist/export.mjs')).href)
+  const { default: init, Renderer } = await import(
+    /* @vite-ignore */ pathToFileURL(join(root, 'dist/export.mjs')).href
+  )
   await init({ module_or_path: await readFile(join(root, 'pkg/takumi_wasm_bg.wasm')) })
   return { name: 'wasm', Renderer }
 }

package/src/range.mjs

@@ -1,6 +1,6 @@
 // Byte ranges for built video and audio. Nitro's static handler has none and runs before any middleware, and Safari
 // won't play a video without them, so this Nitro plugin answers ranged requests for those files in front of the app.
-export default nitro => {
+export default (nitro) => {
   const app = nitro.fetch
   nitro.fetch = async (request, ...rest) => {
     const range = /^bytes=(\d+)-(\d*)$/.exec(request.headers.get('range') ?? '')
@@ -13,7 +13,19 @@ export default nitro => {
     const bytes = Buffer.from(await readAsset(id))
     const start = Number(range[1])
     const end = Math.min(range[2] ? Number(range[2]) : Infinity, bytes.length - 1)
-    if (start > end) return new Response(null, { status: 416, headers: { 'content-range': `bytes */${bytes.length}` } })
-    return new Response(bytes.subarray(start, end + 1), { status: 206, headers: { 'content-type': asset.type, 'accept-ranges': 'bytes', 'content-range': `bytes ${start}-${end}/${bytes.length}`, 'cache-control': 'public, max-age=31536000, immutable' } })
+    if (start > end)
+      return new Response(null, {
+        status: 416,
+        headers: { 'content-range': `bytes */${bytes.length}` },
+      })
+    return new Response(bytes.subarray(start, end + 1), {
+      status: 206,
+      headers: {
+        'content-type': asset.type,
+        'accept-ranges': 'bytes',
+        'content-range': `bytes ${start}-${end}/${bytes.length}`,
+        'cache-control': 'public, max-age=31536000, immutable',
+      },
+    })
   }
 }

package/src/router.ts

@@ -5,9 +5,10 @@
 // renders its new route, and everything inside it goes. One state per request on the server (passed down as a
 // prop), one per tab on the client.
 
-import { state, untrack, type State,type SsrData } from '@weft-js/core'
+import { state, untrack, type State, type SsrData } from '@weft-js/core'
 import type { Merged } from '@weft-js/core/ssr'
 import type { Wire } from './data'
+import type { PreparedRouteShape } from './run/shape-preparation'
 
 /**
  * One level as the server sends it: `d` lists the data's deferred fields (promises on the server, research 25 §4),
@@ -31,12 +32,33 @@ export interface Level {
   data: State<unknown>
   /** A static level's HTML: empty for the page's own; undefined for a level with client code. */
   html: State<string | undefined>
+  /** A temporary incoming shape for this outlet, while its route is pending. */
+  shape: State<PreparedRouteShape[] | undefined>
   x?: string | undefined
 }
 
 /** A route, layout or island: its props are its own, so nothing here can call one without a cast. */
 export type Component = (props: never) => unknown
 
+/** Sizes are emitted, uncompressed bytes in Vite's recorded static closure. */
+export interface RouteAssetCosts {
+  build: string
+  scope: 'vite-static-closure'
+  levels: { id: string; bytes: number | null }[]
+  routeBytes: number | null
+  eagerBytes: number | null
+  combinedBytes: number | null
+}
+
+export interface AssetReceipt {
+  build: string | null
+  version: 1
+  scope: 'vite-static-closure'
+  files: Record<string, { bytes: number | null; kind: string }>
+  routes: Record<string, { files: string[]; bytes: number | null } | null>
+  eager: { files: string[]; bytes: number | null } | null
+}
+
 export interface RouteState {
   levels: Level[]
   /** The current path (pathname + search). */
@@ -44,6 +66,10 @@ export interface RouteState {
   status: State<number>
   /** Loaded route components by id. */
   comps: Record<string, Component>
+  /** Cost of the current match, when the client and receipt are from the same build. */
+  assetBytes?: RouteAssetCosts | null
+  /** Prepare a route's provided shape CSS until the caller releases it. */
+  prepareShape?: (id: string) => PreparedRouteShape | null
   /** Client: shows a static level's HTML, with the next level inside it. */
   mount?: (html: string, depth: number, next: () => unknown) => unknown
   /** Around a level's component, at the same point on both sides: the server's markers, the client's key scope. */
@@ -64,19 +90,24 @@ export interface RoutePayload {
   i?: string[]
   /** A navigation's page data, for those islands. */
   b?: SsrData | null
+  /** Emitted asset cost for these levels, when a matching build receipt exists. */
+  a?: RouteAssetCosts
 }
 
 /** The route state of the render in progress: a server pass sets it as it starts (passes are synchronous). */
 export const active: { route?: RouteState } = {}
 
-export function createRouteState(payload: RoutePayload, comps: Record<string, Component>): RouteState {
+export function createRouteState(
+  payload: RoutePayload,
+  comps: Record<string, Component>,
+): RouteState {
   const r: RouteState = { levels: [], path: state(payload.p), status: state(payload.s), comps }
   payload.m.forEach((m, d) => {
     const lv = level(r, d)
     lv.id.value = m.id
     lv.params.value = m.params
     lv.data.value = m.data
-    lv.html.value = m.s ? m.h ?? '' : undefined
+    lv.html.value = m.s ? (m.h ?? '') : undefined
     lv.x = m.x
   })
   return r
@@ -84,7 +115,13 @@ export function createRouteState(payload: RoutePayload, comps: Record<string, Co
 
 /** Level `d`, made on first use (an empty level renders nothing). */
 export function level(r: RouteState, d: number): Level {
-  return (r.levels[d] ??= { id: state<string | undefined>(undefined), params: state({}), data: state<unknown>(undefined), html: state<string | undefined>(undefined) })
+  return (r.levels[d] ??= {
+    id: state<string | undefined>(undefined),
+    params: state({}),
+    data: state<unknown>(undefined),
+    html: state<string | undefined>(undefined),
+    shape: state<PreparedRouteShape[] | undefined>(undefined),
+  })
 }
 
 const same = (a: unknown, b: unknown) => a === b || JSON.stringify(a) === JSON.stringify(b)
@@ -125,10 +162,17 @@ export function applyMatches(r: RouteState, matches: Match[], path: string, stat
  */
 export const client: {
   route?: RouteState
-  navigate?: (href: string, options?: NavigateOptions & { replace?: boolean | undefined }) => Promise<void>
-  seed?: (list: Wire[]) => void
+  navigate?: (
+    href: string,
+    options?: NavigateOptions & { replace?: boolean | undefined },
+  ) => Promise<void>
+  /** `since`: what `now` said when the navigation left, so entries a write has passed don't land. */
+  seed?: (list: Wire[], since?: number) => void
   seeds?: Wire[] | undefined
+  now?: () => number
   invalidated?: (tags: string[]) => void
+  /** Clear navigation state before a session-changing reload. */
+  sessionChanged?: () => void
   /** Dev: server code changed, so whatever a query read may have too. */
   refreshed?: () => void
 } = {}
@@ -141,6 +185,12 @@ export interface NavigateOptions {
   scroll?: false
 }
 
+/** This tab's line to the app's other tabs: a list of tags a write invalidated, or `0` when the session changed. */
+export const peers =
+  typeof document !== 'undefined' && typeof BroadcastChannel !== 'undefined'
+    ? new BroadcastChannel('weft:tags')
+    : undefined
+
 /** Go to `href` without a page load (a full load before `start()` ran, or for another origin). */
 export function navigate(href: string, options?: NavigateOptions): Promise<void> {
   if (client.navigate) return client.navigate(href, options)

package/src/routes.mjs

@@ -17,7 +17,7 @@ import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
 
 const EXT = /\.(tsx|jsx|ts|js)$/
-const posix = p => p.split('\\').join('/')
+const posix = (p) => p.split('\\').join('/')
 
 /**
  * @typedef {{ id: string, file: string, layouts: string[], path: string, pattern: string, params: string[], splat?: string, rank: number[], card?: string, kind: 'page' | '404' | 'error' }} RouteEntry
@@ -31,25 +31,31 @@ export function scanRoutes(root, dir = join(root, 'src', 'routes')) {
   const out = { root, dir: posix(relative(root, dir)), routes: [], layouts: [], problems: [] }
   if (!existsSync(dir)) return out
   const files = []
-  const walk = d => {
+  const walk = (d) => {
     for (const name of readdirSync(d).sort()) {
       const abs = join(d, name)
       if (statSync(abs).isDirectory()) {
         if (!name.startsWith('_') && !name.startsWith('.')) walk(abs)
-      } else if (EXT.test(name) && !/\.(test|spec)\.|\.d\.ts$/.test(name)) files.push(posix(relative(dir, abs)))
+      } else if (EXT.test(name) && !/\.(test|spec)\.|\.d\.ts$/.test(name))
+        files.push(posix(relative(dir, abs)))
     }
   }
   walk(dir)
 
-  const rel = f => posix(relative(root, join(dir, f)))
+  const rel = (f) => posix(relative(root, join(dir, f)))
   const layoutFile = new Map() // route dir ('' = root) → its _layout file
   for (const f of files) {
     const m = /^(?:(.*)\/)?_layout\.[jt]sx?$/.exec(f)
     if (m) layoutFile.set(m[1] ?? '', f)
   }
-  const layoutOf = new Map([...layoutFile.keys()].map(d => [d, `layout:${d}`]))
+  const layoutOf = new Map([...layoutFile.keys()].map((d) => [d, `layout:${d}`]))
   for (const [d, f] of [...layoutFile].sort((a, b) => a[0].length - b[0].length)) {
-    out.layouts.push({ id: layoutOf.get(d), file: rel(f), dir: d, parent: chain(d, layoutOf).at(-2) })
+    out.layouts.push({
+      id: layoutOf.get(d),
+      file: rel(f),
+      dir: d,
+      parent: chain(d, layoutOf).at(-2),
+    })
   }
 
   const cards = new Map()
@@ -60,17 +66,41 @@ export function scanRoutes(root, dir = join(root, 'src', 'routes')) {
     else cards.set(m[1], rel(f))
   }
 
+  appendRoutes(files, out, rel, layoutOf, cards)
+  out.routes.sort((a, b) => cmpRank(a.rank, b.rank) || a.id.localeCompare(b.id))
+  for (const [b, file] of cards)
+    if (!out.routes.some((r) => r.card === file))
+      out.problems.push({ file, message: `no route \`${b}\` for this card` })
+  return out
+}
+
+function appendRoutes(files, out, rel, layoutOf, cards) {
   for (const f of files) {
     const base = f.replace(EXT, '')
     const name = base.split('/').pop()
     if (base.endsWith('.og') || name === '_layout' || name === '_default') continue
     const d = base.includes('/') ? base.slice(0, base.lastIndexOf('/')) : ''
     if (name === '404' || name === '_error') {
-      if (d) { out.problems.push({ file: rel(f), message: `\`${name}\` is only read at the routes root for now; this one is ignored` }); continue }
-      out.routes.push({ id: name === '404' ? '404' : 'error', file: rel(f), layouts: chain('', layoutOf), path: '', pattern: '', params: [], rank: [], kind: name === '404' ? '404' : 'error' })
+      if (d) {
+        out.problems.push({
+          file: rel(f),
+          message: `\`${name}\` is only read at the routes root for now; this one is ignored`,
+        })
+        continue
+      }
+      out.routes.push({
+        id: name === '404' ? '404' : 'error',
+        file: rel(f),
+        layouts: chain('', layoutOf),
+        path: '',
+        pattern: '',
+        params: [],
+        rank: [],
+        kind: name === '404' ? '404' : 'error',
+      })
       continue
     }
-    if (name.startsWith('_') || d.split('/').some(s => s.startsWith('_'))) continue
+    if (name.startsWith('_') || d.split('/').some((s) => s.startsWith('_'))) continue
     const segs = base === 'index' ? [] : base.split('/')
     if (segs.at(-1) === 'index') segs.pop()
     const params = []
@@ -86,19 +116,32 @@ export function scanRoutes(root, dir = join(root, 'src', 'routes')) {
       } else if (/[[\]]/.test(s)) bad = true
       else parts.push(s)
     }
-    if (bad) { out.problems.push({ file: rel(f), message: 'a segment mixes text and a `[param]`; use a whole segment `[name]`' }); continue }
-    if (splat && parts.at(-1) !== '$') { out.problems.push({ file: rel(f), message: '`[...rest]` must be the last segment' }); continue }
+    if (bad) {
+      out.problems.push({
+        file: rel(f),
+        message: 'a segment mixes text and a `[param]`; use a whole segment `[name]`',
+      })
+      continue
+    }
+    if (splat && parts.at(-1) !== '$') {
+      out.problems.push({ file: rel(f), message: '`[...rest]` must be the last segment' })
+      continue
+    }
     const pattern = '/' + parts.join('/')
     out.routes.push({
-      id: pattern, file: rel(f), layouts: chain(d, layoutOf), path: '/' + segs.join('/'), pattern, params, splat,
+      id: pattern,
+      file: rel(f),
+      layouts: chain(d, layoutOf),
+      path: '/' + segs.join('/'),
+      pattern,
+      params,
+      splat,
       // Static segments outrank params, params outrank a splat (router-core's order; the client table uses it).
-      rank: parts.map(p => (p === '$' ? 0 : p.startsWith('$') ? 1 : 2)),
-      card: cards.get(base), kind: 'page',
+      rank: parts.map((p) => (p === '$' ? 0 : p.startsWith('$') ? 1 : 2)),
+      card: cards.get(base),
+      kind: 'page',
     })
   }
-  out.routes.sort((a, b) => cmpRank(a.rank, b.rank) || a.id.localeCompare(b.id))
-  for (const [b, file] of cards) if (!out.routes.some(r => r.card === file)) out.problems.push({ file, message: `no route \`${b}\` for this card` })
-  return out
 }
 
 /** Layout ids from the root down to `d`. */
@@ -114,8 +157,10 @@ function chain(d, layoutOf) {
 
 function cmpRank(a, b) {
   for (let i = 0; i < Math.max(a.length, b.length); i++) {
-    if (a[i] === undefined) return 1 // shorter after: `/users/new` is tried before `/users/$id/edit`… only on ties
-    if (b[i] === undefined) return -1
+    // Shorter after: `/users/new` is tried before `/users/$id/edit`… only on ties. But a splat also matches nothing, so
+    // the route it would extend comes first: `/docs` before `/docs/$`, or the splat takes `/docs` itself.
+    if (a[i] === undefined) return b[i] === 0 && b.length === i + 1 ? -1 : 1
+    if (b[i] === undefined) return a[i] === 0 && a.length === i + 1 ? 1 : -1
     if (a[i] !== b[i]) return b[i] - a[i]
   }
   return 0
@@ -131,12 +176,18 @@ export function fillPath(pattern, params) {
 
 /** A route's file path as authors write it in types: `src/routes/users/[id].tsx` → `/users/[id]`, `index.tsx` → `/`. */
 export function filePath(manifest, route) {
-  return '/' + route.file.slice(manifest.dir.length + 1).replace(EXT, '').replace(/(^|\/)index$/, '')
+  return (
+    '/' +
+    route.file
+      .slice(manifest.dir.length + 1)
+      .replace(EXT, '')
+      .replace(/(^|\/)index$/, '')
+  )
 }
 
 /** `.weft/routes.d.ts`: every route path, so `RouteProps<…, '/users/[id]'>` and `Meta<…, path>` only take real ones. */
 export function routeTypes(manifest) {
-  const pages = manifest.routes.filter(r => r.kind === 'page')
-  const lines = pages.map(r => `    '${filePath(manifest, r)}': true`)
+  const pages = manifest.routes.filter((r) => r.kind === 'page')
+  const lines = pages.map((r) => `    '${filePath(manifest, r)}': true`)
   return `// Generated by weft from ${manifest.dir}. Do not edit.\nimport '@weft-js/start'\ndeclare module '@weft-js/start' {\n  interface RouteFiles {\n${lines.join('\n')}\n  }\n}\n`
 }

package/src/run/admission.ts

@@ -0,0 +1,80 @@
+import type { ClientRoutes } from '../run'
+import { guess, ours } from './helpers'
+
+/** Admit a link only after the app's own event handlers have run. */
+export function admitLink(event: Event, routes: ClientRoutes) {
+  if (event.defaultPrevented) return
+  if (
+    event instanceof MouseEvent &&
+    (event.metaKey ||
+      event.ctrlKey ||
+      event.shiftKey ||
+      event.altKey ||
+      ((event.type === 'pointerdown' || event.type === 'click') && event.button !== 0))
+  )
+    return
+  if (event.type === 'pointerdown' && 'isPrimary' in event && !event.isPrimary) return
+  const path = event.composedPath()
+  const anchor = path.find((item) => item instanceof HTMLAnchorElement)
+  if (
+    !anchor ||
+    path.some(
+      (item) =>
+        item instanceof Element &&
+        item.matches('[data-navigation="off"], [contenteditable]:not([contenteditable="false"])'),
+    )
+  )
+    return
+  try {
+    const url = ours(anchor)
+    if (!url || !['http:', 'https:'].includes(url.protocol)) return
+    if (!guess(routes, url.pathname).length) return
+    return { anchor, url, noop: url.href === location.href }
+  } catch {
+    return undefined
+  }
+}
+
+/** Pointer admission and its click fallback; the returned disposer removes only these listeners. */
+export function routeClicks(
+  doc: Document,
+  routes: ClientRoutes,
+  go: (href: string) => void | Promise<void>,
+) {
+  let accepted: { id: number; anchor: HTMLAnchorElement } | undefined
+  const down = (event: PointerEvent) => {
+    accepted = undefined
+    const target = admitLink(event, routes)
+    if (!target) return
+    accepted = { id: event.pointerId, anchor: target.anchor }
+    if (!target.noop) void Promise.resolve(go(target.url.href)).catch(() => {})
+  }
+  const cancel = (event: PointerEvent) => {
+    if (accepted?.id === event.pointerId) accepted = undefined
+  }
+  const click = (event: MouseEvent) => {
+    const record = accepted
+    accepted = undefined
+    const pointer = event as PointerEvent
+    if (
+      record &&
+      event.detail > 0 &&
+      (pointer.pointerId === record.id || event.composedPath().includes(record.anchor))
+    ) {
+      event.preventDefault()
+      return
+    }
+    const target = admitLink(event, routes)
+    if (!target) return
+    event.preventDefault()
+    if (!target.noop) void go(target.url.href)
+  }
+  doc.addEventListener('pointerdown', down)
+  doc.addEventListener('pointercancel', cancel)
+  doc.addEventListener('click', click)
+  return () => {
+    doc.removeEventListener('pointerdown', down)
+    doc.removeEventListener('pointercancel', cancel)
+    doc.removeEventListener('click', click)
+  }
+}