@wular/pnext 0.1.3 → 0.1.5

package/config/ts/react.json

@@ -4,6 +4,7 @@
   "extends": "./base.json",
   "compilerOptions": {
     "lib": ["DOM", "DOM.Iterable", "ESNext"],
-    "jsx": "react-jsx"
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/pnext",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A fast little framework for server-first React apps, fully compatible with Next.js",
   "type": "module",
   "bin": {

package/reference/navigation.md

@@ -92,7 +92,9 @@ Exported from `@wular/pnext/navigation/client`, for use in components marked `"u
 | `useSearchParams()`  | Read-only URL search params.                                  |
 | `useParams<Route>()` | Current route params from the initial route state.            |
 | `useRoute<Route>()`  | Pathname, route template, params, and search params together. |
-| `useLinkStatus()`    | Currently always `{ pending: false }`.                        |
+| `useLinkStatus()`    | `{ pending }` for the enclosing `<Link>`.                     |
+
+`useLinkStatus()` tracks the pending state of a `<Link>`, so call it in a component rendered inside one. `pending` turns true when the link is clicked and false once its navigation paints a loading state or the page, fails, or another navigation replaces it.
 
 Router pushes and replaces are typed like links. They soft-navigate when the path or query changes, and fall back to the History API for same-URL hash updates. Cross-origin targets become a full page load. Refreshing re-fetches the current route in place.
 

package/src/api/client-navigation.ts

@@ -1,6 +1,8 @@
+import { options } from 'preact'
 import { useEffect, useState } from 'preact/hooks'
 import { ReadonlyURLSearchParams, type HrefOptions } from './navigation'
 import { blockJavascriptUrl, prefetchRoute, softNavigate } from '../client/router'
+import { routerState } from '../client/router/hub'
 import { seedHistoryEntry } from '../client/router/history'
 import {
   emitLocationChange,
@@ -158,8 +160,31 @@ export function useRoute<Route extends RoutePath = RoutePath>(): CurrentRoute<Ro
   }
 }
 
+interface HookOptions {
+  __h?: (component: { __P?: Element }, ...rest: unknown[]) => void
+}
+
 export function useLinkStatus() {
-  return { pending: false }
+  // The router marks a link pending through its anchor, so find the Link this component renders in.
+  const hookOptions = options as HookOptions
+  const hook = hookOptions.__h
+  let parent: Element | undefined
+  hookOptions.__h = (component, ...rest) => {
+    parent = component.__P
+    hook?.(component, ...rest)
+  }
+  const [pending, setPending] = useState(false)
+  hookOptions.__h = hook
+  useEffect(() => {
+    const link = parent?.closest<HTMLAnchorElement & { __pnextHints?: Set<typeof setPending> }>(
+      'a[data-pnext-link]',
+    )
+    if (!link) return
+    const hints = (link.__pnextHints ??= new Set())
+    hints.add(setPending)
+    return () => hints.delete(setPending)
+  }, [])
+  return { pending }
 }
 
 function useLocation() {
@@ -196,11 +221,33 @@ function locationSignature(location: { pathname: string; search: string; hash: s
   return `${location.pathname}${location.search}${location.hash}`
 }
 
+// Server only: a request/context store, anchored on globalThis.
+interface ServerStore {
+  request?: { url: string }
+  params?: Record<string, RouteParamValue>
+  routeMode?: string
+}
+
+function serverStore(key: string) {
+  const storage = (globalThis as Record<symbol, { getStore(): ServerStore | undefined }>)[
+    Symbol.for(key)
+  ]
+  return storage?.getStore()
+}
+
 function currentLocation() {
   if (!process.browser && typeof window === 'undefined') {
+    const href = serverStore('pnext.requestStorage')?.request?.url
+    const url = href ? new URL(href) : undefined
     return {
-      pathname: '/',
-      search: '',
+      pathname: url?.pathname ?? '/',
+      // Like Next: dev and dynamic renders see the query; static and cached HTML must not bake it in.
+      search:
+        // eslint-disable-next-line turbo/no-undeclared-env-vars
+        process.env.NODE_ENV === 'development' ||
+        serverStore('pnext.workUnitStorage')?.routeMode === 'dynamic'
+          ? (url?.search ?? '')
+          : '',
       hash: '',
     }
   }
@@ -212,7 +259,8 @@ function currentLocation() {
 }
 
 function routeState() {
-  if (!process.browser && typeof window === 'undefined') return {}
+  if (!process.browser && typeof window === 'undefined')
+    return { params: serverStore('pnext.requestStorage')?.params } as RouteState
   const state = (history.state as Record<string, unknown> | null) ?? {}
   const routeState = window.__PNEXT_ROUTE__ ?? {}
   const bfcacheId = typeof state.__pnextBfcacheId === 'string' ? state.__pnextBfcacheId : undefined
@@ -242,6 +290,7 @@ function navigate(url: string, mode: 'push' | 'replace', scroll = true) {
   if (mode === 'replace') window.history.replaceState(history.state, '', next)
   else window.history.pushState(history.state, '', next)
   scheduleNavigationScroll(next, { scroll })
+  routerState.settleLink?.()
 }
 
 // Exported so compat's link-status can guarantee raw history.pushState /

package/src/api/link.tsx

@@ -1,7 +1,6 @@
 /** @jsxImportSource preact */
 import { h, type ComponentChildren, type JSX } from 'preact'
 import { useEffect, useRef } from 'preact/hooks'
-import type { AnchorHTMLAttributes, MouseEvent, ReactNode } from 'react'
 import { getDefaultPrefetchMode, routeHref, type SearchInput } from '../routing/href'
 import type { PrefetchMode, RouteParams, RoutePath } from '../types'
 
@@ -9,9 +8,9 @@ export interface NavigateEvent {
   preventDefault(): void
 }
 
-type LinkMouseEvent = MouseEvent<HTMLAnchorElement>
+type LinkMouseEvent = JSX.TargetedMouseEvent<HTMLAnchorElement>
 
-type BaseLinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'onClick'> & {
+type BaseLinkProps = Omit<JSX.IntrinsicElements['a'], 'href' | 'onClick' | 'ref'> & {
   prefetch?: PrefetchMode
   replace?: boolean
   scroll?: boolean
@@ -21,7 +20,7 @@ type BaseLinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'onC
   onNavigate?: (event: NavigateEvent) => void
   onPrefetchStart?: () => void
   onPrefetchFinish?: () => void
-  children?: ReactNode
+  children?: ComponentChildren
 }
 
 type ParamsProp<Route extends RoutePath> =
@@ -48,7 +47,7 @@ export function Link<Route extends RoutePath>({
   onPrefetchFinish,
   children,
   ...anchorProps
-}: LinkProps<Route>): ReactNode {
+}: LinkProps<Route>): ComponentChildren {
   const resolvedHref = routeHref(href, { params: params ?? {}, search, hash })
   // A link's own prefetch prop wins; otherwise the app-wide config default.
   const prefetchMode = prefetch ?? getDefaultPrefetchMode()
@@ -72,8 +71,8 @@ export function Link<Route extends RoutePath>({
         if (navEvent.defaultPrevented) clickEvent.preventDefault()
       },
     } as JSX.HTMLAttributes<HTMLAnchorElement>,
-    children as ComponentChildren,
-  ) as unknown as ReactNode
+    children,
+  )
 }
 
 // The prefetch runtime dispatches lifecycle events on the anchor that

package/src/cli/adapters/vercel-warm.ts

@@ -1,3 +1,4 @@
+import { resolveManifest } from '../../utils/fs'
 /**
  * Module warm-up for a production build - run in its own process.
  *
@@ -549,7 +550,11 @@ if (import.meta.main) {
   // only thing on stderr.
   const manifestFile = path.join(config.outPath, 'manifest.json')
   if (!request.skip || !existsSync(manifestFile)) process.exit(0)
-  const manifest = JSON.parse(await readFile(manifestFile, 'utf8')) as BuildManifest
+  const manifest = resolveManifest(
+    JSON.parse(await readFile(manifestFile, 'utf8')) as BuildManifest,
+    config.outPath,
+    config.root,
+  )
   await warmRouteModules(config, manifest, new Set(request.skip ?? []), mode)
   // App code reached through a route handler can leave the loop alive (a db
   // pool, a stray interval); the warm pass is done either way.

package/src/cli/adapters/vercel.ts

@@ -1012,7 +1012,7 @@ async function traceNodeModulesClosure(
         // packages - workspace source gets traced further. Bare package specifiers are also recorded
         // so the closure ships (or workspace-links) their node_modules entries; workspace packages
         // need the link even when their source is traced.
-        const resolved = resolveImport(config.root, file, specifier)
+        const resolved = resolveImport(config.root, file, specifier, config.workspaceRoot)
         if (
           resolved &&
           isInsideDir(workspaceRoot, resolved) &&

package/src/cli/build/cache.ts

@@ -1,3 +1,4 @@
+import { resolveManifest } from '../../utils/fs'
 import { createHash } from 'node:crypto'
 import { existsSync } from 'node:fs'
 import { lstat, mkdir, readFile, readdir, readlink } from 'node:fs/promises'
@@ -73,9 +74,13 @@ export async function lookupBuildCache(
     return { enabled: true, context, inputs, reason: `output (${changed || 'unknown'})` }
   }
   try {
-    const manifest = JSON.parse(
-      await readFile(path.join(config.outPath, 'manifest.json'), 'utf8'),
-    ) as BuildManifest
+    const manifest = resolveManifest(
+      JSON.parse(
+        await readFile(path.join(config.outPath, 'manifest.json'), 'utf8'),
+      ) as BuildManifest,
+      config.outPath,
+      config.root,
+    )
     return { enabled: true, context, inputs, manifest, reason: 'hit' }
   } catch {
     return { enabled: true, context, inputs, reason: 'manifest' }

package/src/cli/build.ts

@@ -1,3 +1,4 @@
+import { serializeBuildManifest } from '../utils/fs'
 import { copyFile, mkdir, rename, writeFile } from 'node:fs/promises'
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs'
 import { createRequire } from 'node:module'
@@ -257,7 +258,7 @@ async function runBuild(
   const partytownLib = log.step('partytown lib', () => copyPartytownLib(config))
   partytownLib.catch(() => undefined)
 
-  let routes = await log.step('scan routes', () => scanRoutes(config.appPath))
+  let routes = await log.step('scan routes', () => scanRoutes(config.appPath, config.workspaceRoot))
   log.log(`found ${routes.length} route${routes.length === 1 ? '' : 's'}`)
   if (options.debugBuildPaths) {
     routes = filterDebugBuildRoutes(config.root, routes, options.debugBuildPaths)
@@ -1055,7 +1056,7 @@ async function writeBuildManifest(outPath: string, manifest: BuildManifest) {
   assertManifestServerArtifacts(outPath, manifest)
   const file = path.join(outPath, 'manifest.json')
   const temporary = path.join(outPath, `.manifest-${process.pid}.tmp`)
-  await writeFile(temporary, `${JSON.stringify(manifest, null, 2)}\n`)
+  await writeFile(temporary, serializeBuildManifest(manifest))
   await rename(temporary, file)
 }
 

package/src/cli/serve/pipeline.ts

@@ -1,3 +1,4 @@
+import { resolveManifest } from '../../utils/fs'
 /**
  * The production request pipeline. Split out of `start.ts` so the prebundled
  * server entry parses only what listening needs: this module (renderer,
@@ -99,9 +100,16 @@ export async function createRequestHandler(
   const manifestPath = path.join(config.outPath, 'manifest.json')
   // `start` reads the manifest before binding the port (a missing build must
   // still fail there, not on the first request) and hands it over.
-  const manifest =
-    options.manifest ?? (JSON.parse(await readFile(manifestPath, 'utf8')) as BuildManifest)
-  const persistManifest = () => writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  const manifest = resolveManifest(
+    options.manifest ?? (JSON.parse(await readFile(manifestPath, 'utf8')) as BuildManifest),
+    config.outPath,
+    config.root,
+  )
+  const persistManifest = async () => {
+    const stored = JSON.parse(await readFile(manifestPath, 'utf8')) as BuildManifest
+    stored.staticFiles = manifest.staticFiles
+    await writeFile(manifestPath, `${JSON.stringify(stored, null, 2)}\n`)
+  }
   // Compat action-registry arming + serverActions.bodySizeLimit resolution +
   // fetch-cache install now run through the extension registry: the action
   // dispatch interceptor rebuilds the registry from manifest.actions on the

package/src/cli/typegen.ts

@@ -3,7 +3,8 @@ import { readFile, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import type { ResolvedConfig } from '../config'
 import { loadConfig } from '../config'
-import { ensureDir, toPosixPath } from '../utils/fs'
+import { bootstrapCompatBoot, generateCompatRouteTypes } from '../compat-bootstrap'
+import { ensureDir, includeTypes, toPosixPath, writeFileAtomic } from '../utils/fs'
 import { scanRoutes } from '../routing/routes'
 import type { RouteManifestEntry } from '../types'
 
@@ -16,8 +17,11 @@ export interface TypegenResult {
 
 export async function typegenProject(root?: string): Promise<TypegenResult> {
   const config = await loadConfig(root)
-  const routes = await scanRoutes(config.appPath)
-  return writeTypegen(config, routes)
+  await bootstrapCompatBoot(config)
+  const routes = await scanRoutes(config.appPath, config.workspaceRoot)
+  const result = await writeTypegen(config, routes)
+  await generateCompatRouteTypes(config, routes)
+  return result
 }
 
 export async function writeTypegen(
@@ -28,6 +32,7 @@ export async function writeTypegen(
   const file = path.join(config.typesPath, 'pnext.gen.d.ts')
   const source = typegenSource(routes)
   await writeIfChanged(file, source)
+  await writeCoreEnv(config, file, allRoutes)
   const aliases = await writeRouteAliases(config, routes)
   const checks = await writeChecks(config, routes)
   return { file, routes: routes.length, checks, aliases }
@@ -162,3 +167,60 @@ async function writeIfChanged(file: string, source: string) {
   await ensureDir(path.dirname(file))
   await writeFile(file, source)
 }
+
+async function writeCoreEnv(
+  config: ResolvedConfig,
+  typesFile: string,
+  routes: RouteManifestEntry[],
+) {
+  if (config.compat?.next) return
+  const file = path.join(config.root, 'tsconfig.json')
+  const exists = existsSync(file)
+  if (!exists && !routes.some(route => route.sourceFiles.some(file => /\.[cm]?tsx?$/.test(file))))
+    return
+  const reference = toPosixPath(path.relative(config.root, typesFile))
+  await writeIfChanged(
+    path.join(config.root, 'pnext-env.d.ts'),
+    `/// <reference types="@wular/pnext" />\n/// <reference path="${reference}" />\n\n// This file is generated by PNext. Do not edit.\n`,
+  )
+  if (!exists) return
+  let source: string
+  let tsconfig: { include?: unknown }
+  try {
+    source = await readFile(file, 'utf8')
+    tsconfig = Bun.JSONC.parse(source) as typeof tsconfig
+  } catch {
+    return
+  }
+  if (!tsconfig || !Array.isArray(tsconfig.include)) return
+  const typesGlob = `${toPosixPath(path.relative(config.root, config.typesPath))}/**/*.ts`
+  const added = includeTypes(tsconfig, ['pnext-env.d.ts', typesGlob], [])
+  if (added.length) await writeFileAtomic(file, updateTypeSelection(source, added))
+}
+
+function updateTypeSelection(source: string, added: string[]) {
+  // Token offsets preserve comments, whitespace and escaped strings outside the edited selection.
+  const tokens = [
+    ...source.matchAll(/"(?:\\[\s\S]|[^"\\])*"|\/\/[^\r\n]*|\/\*[\s\S]*?\*\/|[^\s]/g),
+  ].filter(token => !token[0].startsWith('//') && !token[0].startsWith('/*'))
+  let depth = 0
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index]!
+    if (
+      depth === 1 &&
+      token[0].startsWith('"') &&
+      JSON.parse(token[0]) === 'include' &&
+      tokens[index + 1]?.[0] === ':'
+    ) {
+      let end = index + 3
+      while (tokens[end]?.[0] !== ']') end++
+      const close = tokens[end]!
+      const previous = tokens[end - 1]![0]
+      const insertion = `${previous === '[' || previous === ',' ? '' : ','} ${added.map(value => JSON.stringify(value)).join(', ')}`
+      return source.slice(0, close.index) + insertion + source.slice(close.index)
+    }
+    if (token[0] === '[' || token[0] === '{') depth++
+    if (token[0] === ']' || token[0] === '}') depth--
+  }
+  return source
+}

package/src/client/build.ts

@@ -1532,7 +1532,8 @@ function createClientSourcePipeline(config: ResolvedConfig, dev = false, routeId
       contents = rewriteDeferredDynamicImports(
         contents,
         resolved,
-        specifier => resolveImport(rootFromFile(resolved), resolved, specifier),
+        specifier =>
+          resolveImport(rootFromFile(resolved), resolved, specifier, config.workspaceRoot),
         target => {
           const id = clientReferenceId(target.file, target.exportName)
           const ref = { ...target, routeId }
@@ -2089,7 +2090,9 @@ export async function clientCacheKeyParts(
 ): Promise<ClientCacheKeyParts> {
   const staticDigest = staticHash ?? clientCacheStaticHash(route, nextCompat, config)
   const sources = await Promise.all(
-    (await clientSourceFiles(route)).map(file => readClientCacheSource(file)),
+    (await clientSourceFiles(route, config?.workspaceRoot)).map(file =>
+      readClientCacheSource(file),
+    ),
   )
   return { key: clientCacheKeyFrom(staticDigest, sources), staticHash: staticDigest, sources }
 }
@@ -2102,14 +2105,14 @@ export async function clientCacheKey(
   return (await clientCacheKeyParts(route, nextCompat, config)).key
 }
 
-async function clientSourceFiles(route: RouteManifestEntry) {
+async function clientSourceFiles(route: RouteManifestEntry, workspaceRoot?: string) {
   const entryFiles = [
     ...(route.client ? [route.file] : []),
     ...route.clientReferences.map(reference => reference.file),
   ]
   const files = new Set<string>()
 
-  await Promise.all(entryFiles.map(file => collectClientSourceFile(file, files)))
+  await Promise.all(entryFiles.map(file => collectClientSourceFile(file, files, workspaceRoot)))
 
   return [...files].sort()
 }
@@ -2117,7 +2120,7 @@ async function clientSourceFiles(route: RouteManifestEntry) {
 // The walk fans out: every file joins `files` before its own read starts, so
 // concurrent branches still visit each file once. Serially this was the whole
 // cost of a route's client cache key (~1.8 s on a 300-module route).
-async function collectClientSourceFile(file: string, files: Set<string>) {
+async function collectClientSourceFile(file: string, files: Set<string>, workspaceRoot?: string) {
   if (files.has(file) || !existsSync(file)) return
   files.add(file)
   if (isAssetLike(file)) return
@@ -2125,8 +2128,8 @@ async function collectClientSourceFile(file: string, files: Set<string>) {
   const source = rewriteLiteralDynamicCalls(await readText(file), file)
   await Promise.all(
     [...localImports(file, source)].map(specifier => {
-      const resolved = resolveImport(rootFromFile(file), file, specifier)
-      return resolved ? collectClientSourceFile(resolved, files) : Promise.resolve()
+      const resolved = resolveImport(rootFromFile(file), file, specifier, workspaceRoot)
+      return resolved ? collectClientSourceFile(resolved, files, workspaceRoot) : Promise.resolve()
     }),
   )
 }

package/src/client/entry.ts

@@ -104,10 +104,23 @@ function serializeModulePath() {
 // Re-provide the per-island layout-segment snapshot (stamped by the renderer as
 // `data-pnext-layout-segments`) around a hydrated island so compat's
 // useSelectedLayoutSegment(s) recomputes live from the layout depth. Emitted
-// only under next compat (the hooks are compat-only); a no-op wrapper otherwise.
+// only under next compat (the hooks are compat-only); core keeps the children guard.
 function layoutSegmentHelperSource(nextCompat?: boolean) {
-  if (!nextCompat) return ''
-  return `
+  // useId's mask (preact's _mask), seeded by data-pnext-id and kept on the instance (__c) across re-adoption.
+  const seed = `
+function pnextIslandMask(vnode, root) {
+  const mask = root.__pnextMask ??= [root.getAttribute('data-pnext-id'), 0];
+  Object.defineProperty(vnode, '__m', { enumerable: true, get() { return (this.__c || this).__pnextMask ??= mask; } });
+}`
+  if (!nextCompat)
+    return `${seed}
+function pnextIslandVNode(h, Component, props, children, root) {
+  const vnode = children !== undefined ? h(Component, props, children) : h(Component, props);
+  pnextIslandMask(vnode, root);
+  return vnode;
+}
+`
+  return `${seed}
 import { LayoutSegmentContext as __PNextLayoutSegmentContext, RouteParamsContext as __PNextRouteParamsContext } from ${JSON.stringify(islandContextModulePath())};
 function pnextIslandReadJson(root, attr) {
   const raw = root && root.getAttribute ? root.getAttribute(attr) : null;
@@ -118,6 +131,7 @@ function pnextIslandVNode(h, Component, props, children, root) {
   // An explicit undefined children argument clobbers props.children in
   // preact's createElement; plain children travel inside the parsed props.
   let vnode = children !== undefined ? h(Component, props, children) : h(Component, props);
+  pnextIslandMask(vnode, root);
   const segments = pnextIslandReadJson(root, 'data-pnext-layout-segments');
   if (segments) vnode = h(__PNextLayoutSegmentContext.Provider, { value: segments }, vnode);
   const params = pnextIslandReadJson(root, 'data-pnext-params');
@@ -132,11 +146,8 @@ function islandVNodeExpr(
   propsExpr: string,
   childrenExpr: string,
   rootExpr: string,
-  nextCompat?: boolean,
 ) {
-  return nextCompat
-    ? `pnextIslandVNode(h, ${componentExpr}, ${propsExpr}, ${childrenExpr}, ${rootExpr})`
-    : `h(${componentExpr}, ${propsExpr}, ${childrenExpr})`
+  return `pnextIslandVNode(h, ${componentExpr}, ${propsExpr}, ${childrenExpr}, ${rootExpr})`
 }
 
 /**
@@ -1136,11 +1147,10 @@ function observeVisibleIsland(root, island) {
 }
 
 function visibleTarget(root) {
-  // The host's OWN box: hostMeasureSource delegates the patched one to the
-  // parent, and IntersectionObserver never fires for a display:contents target.
-  const rect = Element.prototype.getBoundingClientRect.call(root);
-  if (rect.width || rect.height) return root;
-  return root.parentElement ?? root;
+  // IntersectionObserver never fires for a display:contents target: observe the nearest box.
+  let target = root;
+  while (target.parentElement && getComputedStyle(target).display === 'contents') target = target.parentElement;
+  return target;
 }
 
 ${mountOnceSource()}
@@ -1159,7 +1169,8 @@ async function mountIslandTree(root, island) {
   ]);
 ${facts.suspense !== false ? '  islandBoundary = Suspense;\n' : ''}  const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
   const source = preservedSource(root, render);
-  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node), h), await staticChildren(h, source, island.id));
+  if (!source) return adoptPreserved(render, root);
+  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node), h), await staticChildren(h, source, island.id), root);
   const wrapped = ${facts.suspense !== false ? 'h(Suspense, { fallback: null }, pnextClientBoundary(h, vnode))' : 'pnextClientBoundary(h, vnode)'};
   if (source !== root) adoptPreserved(render, root, wrapped);
   else mount(hydrate, render, root, wrapped);
@@ -1172,7 +1183,8 @@ async function mountIslandTree(root, island) {
   const [{ h, hydrate, render }, Component] = await Promise.all([import('preact'), islandComponent(island)]);
   const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
   const source = preservedSource(root, render);
-  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node), h), await staticChildren(h, source, island.id));
+  if (!source) return adoptPreserved(render, root);
+  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node), h), await staticChildren(h, source, island.id), root);
   if (source !== root) adoptPreserved(render, root, vnode);
   else mount(hydrate, render, root, vnode);
 }`
@@ -1200,16 +1212,18 @@ function preservedSource(root, render) {
   const incoming = root.__pnextIncoming;
   root.__pnextIncoming = undefined;
   if (!incoming) return root;
-  if (root.__pnextLive === render) return incoming;
+  // A kept layout's island stashed as its own incoming has no new render: keep its tree.
+  if (root.__pnextLive === render) return incoming === root ? null : incoming;
   root.replaceChildren(...incoming.childNodes);
   root.__pnextLive = undefined;
+  root.__pnextMask = [incoming.getAttribute('data-pnext-id'), 0];
   return root;
 }
 
 // Re-render the preserved root in place so component state survives while the
 // routed content under the island updates.
 function adoptPreserved(render, root, vnode) {
-  render(vnode, root);
+  if (vnode) render(vnode, root);
   pnextRender = render;
   pnextMountedRoots.add(root);
 }
@@ -1230,8 +1244,10 @@ function mount(hydrate, render, root, vnode) {
 // Adopted DOM children win (element children); plain children travel inside
 // the serialized props instead, and an explicit undefined third argument would
 // clobber props.children in preact's createElement — so only pass it when set.
-function islandVNode(h, Component, props, adopted) {
-  return adopted !== undefined ? h(Component, props, adopted) : h(Component, props);
+function islandVNode(h, Component, props, adopted, root) {
+  const vnode = adopted !== undefined ? h(Component, props, adopted) : h(Component, props);
+  pnextIslandMask(vnode, root);
+  return vnode;
 }
 
 async function staticChildren(h, root, id) {
@@ -1278,7 +1294,7 @@ async function domNode(h, node) {
     // A nested island must match its previous incarnation by IDENTITY, or the shift remounts
     // it and resets its state - Next never remounts layout components on navigation.
     if (props.key === undefined) props.key = 'pnext-island:' + id;
-    const vnode = islandVNode(h, Component, props, await staticChildren(h, element, island.id));
+    const vnode = islandVNode(h, Component, props, await staticChildren(h, element, island.id), element);
     return ${nextCompat ? 'islandBoundary ? h(islandBoundary, { fallback: null }, pnextClientBoundary(h, vnode)) : pnextClientBoundary(h, vnode)' : 'vnode'};
   }
 
@@ -1531,7 +1547,7 @@ function diagnoseSkippedIslands() {
     // claim pass adopted is no longer in the document. Everything else is a host
     // this route can never hydrate.
     if (island?.options?.load === 'visible') continue;
-    if (root.closest('pnext-hole-capture')) continue;
+    if (root.closest('pnext-hole-capture, [data-pnext-stream]')) continue;
     if (parent && !parent.__pnextLive) continue;
     const reason = island
       ? 'was materialized after its parent island mounted, outside any streamed hole this route can re-adopt'
@@ -1562,6 +1578,8 @@ for (const island of islands) {
   }
 for (const island of islands) {
   for (const root of document.querySelectorAll(\`[data-pnext-client="\${island.id}"]\`)) {
+    // React hydrates a streamed boundary only once revealed; its promotion re-runs this scan.
+    if (root.closest('[data-pnext-stream]')) continue;
     const parent = nestedIslandParent(root);
     if (parent) {
       pending.push(claimNestedIslandRoot(root, parent));
@@ -1625,8 +1643,11 @@ async function mountIslandTree(root, island) {
     // Preserved across a soft navigation: re-render in place with the incoming
     // document's props/children so component state survives while the routed
     // content under the island updates.
-    const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, incoming, domChildren, h)', 'await staticChildren(incoming, island.id)', 'root', nextCompat)};
-    render(${wrapInBoundary('vnode', nextCompat)}, root);
+    // A kept layout's island (its own incoming) keeps its tree.
+    if (incoming !== root) {
+      const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, incoming, domChildren, h)', 'await staticChildren(incoming, island.id)', 'root')};
+      render(${wrapInBoundary('vnode', nextCompat)}, root);
+    }
     pnextMountedRoots.add(root);
     return;
   }
@@ -1635,8 +1656,9 @@ async function mountIslandTree(root, island) {
     // instance can't diff its tree — restore the SSR children and mount fresh.
     root.replaceChildren(...incoming.childNodes);
     root.__pnextLive = undefined;
+    root.__pnextMask = [incoming.getAttribute('data-pnext-id'), 0];
   }
-  const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, root, domChildren, h)', 'await staticChildren(root, island.id)', 'root', nextCompat)};
+  const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, root, domChildren, h)', 'await staticChildren(root, island.id)', 'root')};
   mount(root, ${wrapInBoundary('vnode', nextCompat)});
 }
 
@@ -1713,7 +1735,7 @@ async function domNode(node) {
         : ''
     }
     const Component = await islandComponent(island);
-    return ${wrapInBoundary(islandVNodeExpr('Component', 'await islandProps(rawProps, element, domChildren, h)', 'children', 'element', nextCompat), nextCompat)};
+    return ${wrapInBoundary(islandVNodeExpr('Component', 'await islandProps(rawProps, element, domChildren, h)', 'children', 'element'), nextCompat)};
   }
 
   if (Page && element.id === 'pnext-page') {
@@ -1755,11 +1777,10 @@ ${holeSeamSource()}${
     visibleIslands
       ? `
 function visibleTarget(root) {
-  // The host's OWN box: hostMeasureSource delegates the patched one to the
-  // parent, and IntersectionObserver never fires for a display:contents target.
-  const rect = Element.prototype.getBoundingClientRect.call(root);
-  if (rect.width || rect.height) return root;
-  return root.parentElement ?? root;
+  // IntersectionObserver never fires for a display:contents target: observe the nearest box.
+  let target = root;
+  while (target.parentElement && getComputedStyle(target).display === 'contents') target = target.parentElement;
+  return target;
 }
 `
       : ''

package/src/client/reference-stub.ts

@@ -86,7 +86,7 @@ export async function clientReferenceExportNames(
   // excluded, per ES module star semantics). `export * as ns from` exports
   // only `ns`, which the own-module scan already lists.
   for (const specifier of moduleExportStars(text, file)) {
-    const resolved = resolveImport(config.root, file, specifier)
+    const resolved = resolveImport(config.root, file, specifier, config.workspaceRoot)
     if (!resolved || !isInside(config.workspaceRoot, resolved)) continue
     for (const name of await clientReferenceExportNames(config, resolved, undefined, visited)) {
       if (name !== 'default') names.add(name)