@remix-run/ui 0.5.0 → 0.7.0

package/src/runtime/frame.ts

@@ -10,6 +10,7 @@ import { createRangeRoot, createRoot } from './vdom.ts'
 import { diffNodes } from './diff-dom.ts'
 import { createStyleManager, type StyleManager } from '../style/index.ts'
 import { findFlushMarker, type FlushKind } from './stream-protocol.ts'
+import { getDocumentModulePreloader } from './module-preloader.ts'
 import { unwrapFrameResolution } from './frame-resolution.ts'
 import {
   disposeClientEntryBoundary,
@@ -213,6 +214,7 @@ export type FrameContext = {
   regionTailRef?: ChildNode | null
   regionParent?: ParentNode | null
   signal?: AbortSignal
+  isActiveModulePreload?: (node: Node) => boolean
 }
 
 type FrameInit = {
@@ -278,6 +280,7 @@ export function createFrame(root: FrameRoot, init: FrameInit): Frame {
   let reloadAbortUnsubscribe: (() => void) | undefined
   let reloadKind: 'direct' | 'ancestor' | undefined
   let styleManager = init.styleManager ?? createStyleManager()
+  let modulePreloader = getDocumentModulePreloader(container.doc)
   let currentMarker = init.marker
   let displayedContentStatus: 'pending' | 'resolved' = init.marker?.status ?? 'resolved'
   let pendingTemplateMarkerId: string | undefined
@@ -288,6 +291,12 @@ export function createFrame(root: FrameRoot, init: FrameInit): Frame {
   let disposed = false
   let lifecycleController = new AbortController()
 
+  if (isDocumentNode(container.root)) {
+    modulePreloader.adoptInitialPreloadLinks(container.root)
+  } else {
+    modulePreloader.consumePreloadLinks(container.root)
+  }
+
   // Merge any rmx-data found in the current document once at startup.
   mergeRmxDataFromDocument(init.data, container.doc)
 
@@ -407,6 +416,7 @@ export function createFrame(root: FrameRoot, init: FrameInit): Frame {
 
     if (isFullDocumentReload && htmlContent !== undefined) {
       let parsed = new DOMParser().parseFromString(htmlContent, 'text/html')
+      modulePreloader.consumePreloadLinks(parsed)
       let responseData = options.data
       mergeRmxDataFromDocument(responseData, parsed)
       let responseContext = { ...context, data: responseData }
@@ -421,6 +431,9 @@ export function createFrame(root: FrameRoot, init: FrameInit): Frame {
         regionParent: container.doc.documentElement,
         regionTailRef: null,
         signal: options.signal,
+        isActiveModulePreload: modulePreloader.hasActivePreloads()
+          ? modulePreloader.isActivePreload
+          : undefined,
       })
       diffNodes([container.doc.body], [parsed.body], {
         ...responseContext,
@@ -445,6 +458,7 @@ export function createFrame(root: FrameRoot, init: FrameInit): Frame {
 
     let fragment =
       htmlContent !== undefined ? createFragmentFromString(container.doc, htmlContent) : content
+    modulePreloader.consumePreloadLinks(fragment)
     context.styleManager.adoptServerStyles(
       collectFrameServerStyleTags(createElementContainer(fragment)),
     )
@@ -1760,6 +1774,10 @@ function isCommentNode(node: Node | null | undefined): node is Comment {
   return node?.nodeType === Node.COMMENT_NODE
 }
 
+function isDocumentNode(node: Node): node is Document {
+  return node.nodeType === Node.DOCUMENT_NODE
+}
+
 function isDocumentFragmentNode(value: unknown): value is DocumentFragment {
   return (
     typeof value === 'object' &&

package/src/runtime/module-preloader.ts

@@ -0,0 +1,115 @@
+const SERVER_MODULE_PRELOAD_SELECTOR = 'link[data-rmx][rel~="modulepreload" i][href]'
+
+interface ModulePreloader {
+  adoptInitialPreloadLinks(source: ParentNode): void
+  consumePreloadLinks(source: ParentNode): void
+  hasActivePreloads(): boolean
+  isActivePreload(node: Node): boolean
+}
+
+const modulePreloaders = new WeakMap<Document, ModulePreloader>()
+
+export function getDocumentModulePreloader(doc: Document): ModulePreloader {
+  let preloader = modulePreloaders.get(doc)
+  if (!preloader) {
+    preloader = createModulePreloader(doc)
+    modulePreloaders.set(doc, preloader)
+  }
+  return preloader
+}
+
+function createModulePreloader(doc: Document): ModulePreloader {
+  let requestedUrls = new Set<string>()
+  let activeLinks = new WeakSet<HTMLLinkElement>()
+  let activeLinkCount = 0
+
+  function activateLink(link: HTMLLinkElement): void {
+    activeLinks.add(link)
+    activeLinkCount++
+  }
+
+  function deactivateLink(link: HTMLLinkElement): void {
+    if (activeLinks.delete(link)) activeLinkCount--
+  }
+
+  function preload(href: string): void {
+    let link = doc.createElement('link')
+    link.rel = 'modulepreload'
+    link.href = href
+    link.setAttribute('data-rmx', '')
+    let url = link.href
+    if (requestedUrls.has(url)) return
+    requestedUrls.add(url)
+
+    activateLink(link)
+    link.addEventListener(
+      'load',
+      () => {
+        deactivateLink(link)
+        link.remove()
+      },
+      { once: true },
+    )
+    link.addEventListener(
+      'error',
+      () => {
+        deactivateLink(link)
+        link.remove()
+        requestedUrls.delete(url)
+      },
+      { once: true },
+    )
+    doc.head.append(link)
+  }
+
+  return {
+    adoptInitialPreloadLinks(source) {
+      for (let initialLink of source.querySelectorAll<HTMLLinkElement>(
+        SERVER_MODULE_PRELOAD_SELECTOR,
+      )) {
+        if (activeLinks.has(initialLink)) continue
+
+        // An identical link joins the document's existing module-map request and receives its own
+        // terminal event, even when the parser-created link settled before runtime startup.
+        let observerLink = doc.createElement('link')
+        observerLink.rel = 'modulepreload'
+        observerLink.href = initialLink.href
+        observerLink.setAttribute('data-rmx', '')
+        let url = initialLink.href
+        requestedUrls.add(url)
+        activateLink(initialLink)
+        activateLink(observerLink)
+
+        let settled = false
+        function settle(succeeded: boolean): void {
+          if (settled) return
+          settled = true
+          deactivateLink(initialLink)
+          deactivateLink(observerLink)
+          initialLink.remove()
+          observerLink.remove()
+          if (!succeeded) requestedUrls.delete(url)
+        }
+
+        observerLink.addEventListener('load', () => settle(true), { once: true })
+        observerLink.addEventListener('error', () => settle(false), { once: true })
+        doc.head.append(observerLink)
+      }
+    },
+    consumePreloadLinks(source) {
+      let hrefs: string[] = []
+      for (let link of source.querySelectorAll<HTMLLinkElement>(SERVER_MODULE_PRELOAD_SELECTOR)) {
+        let href = link.getAttribute('href')
+        link.remove()
+        if (href) hrefs.push(href)
+      }
+      for (let href of hrefs) preload(href)
+    },
+    hasActivePreloads() {
+      return activeLinkCount > 0
+    },
+    isActivePreload(node) {
+      return node instanceof HTMLLinkElement && activeLinks.has(node)
+    },
+  }
+}

package/src/runtime/navigation.ts

@@ -72,11 +72,9 @@ export async function navigate(href: string, options?: NavigationOptions) {
  * Starts listening for Navigation API transitions and routes them through frame reloads.
  *
  * @param signal Abort signal used to remove the listener.
- * @param canResolveFrames Whether the runtime has a resolver that can handle intercepted navigations.
  * @returns void
  */
-export function startNavigationListener(signal: AbortSignal, canResolveFrames = true) {
-  if (!canResolveFrames) return
+export function startNavigationListener(signal: AbortSignal) {
   return startNavigationListenerImpl(signal, {
     getTopFrame,
     getNamedFrame,

package/src/runtime/run.ts

@@ -4,7 +4,7 @@ import { createStyleManager } from '../style/index.ts'
 import type { FrameHandle, Handle } from './component.ts'
 import { createComponentErrorEvent } from './error-event.ts'
 import type { ComponentErrorEvent } from './error-event.ts'
-import type { LoadModule, ResolveFrame } from './frame.ts'
+import type { LoadModule, ResolveFrame, ResolveFrameOptions } from './frame.ts'
 import { startNavigationListener } from './navigation.ts'
 import { TypedEventTarget } from './typed-event-target.ts'
 
@@ -23,8 +23,8 @@ export interface RunInit {
   /**
    * Resolves browser-loaded `<Frame>` content.
    *
-   * Omit this only when the runtime never needs to load or reload frames in the
-   * browser.
+   * Defaults to fetching the frame source as HTML with the submitted form data,
+   * method, encoding, and abort signal.
    */
   resolveFrame?: ResolveFrame
 }
@@ -72,10 +72,54 @@ export function getNamedFrame(name: string): FrameHandle {
   return namedFrames.get(name) ?? getTopFrame()
 }
 
+// Frame reloads can receive raw FormData without going through form navigation. Encode it here so
+// manual reloads use the requested form encoding instead of always sending multipart bodies.
+function getRequestBody(options?: ResolveFrameOptions): BodyInit | undefined {
+  let formData = options?.formData
+  if (!formData || options?.method?.toLowerCase() === 'get') return
+
+  if (options?.encType === 'text/plain') {
+    let body = ''
+    for (let [name, value] of formData) {
+      name = normalizeLineBreaks(name)
+      value = normalizeLineBreaks(typeof value === 'string' ? value : value.name)
+      body += `${name}=${value}\r\n`
+    }
+    return new Blob([body], { type: 'text/plain' })
+  }
+
+  if (options?.encType !== 'application/x-www-form-urlencoded') return formData
+
+  let body = new URLSearchParams()
+  for (let [name, value] of formData) {
+    body.append(name, typeof value === 'string' ? value : value.name)
+  }
+  return body
+}
+
+function normalizeLineBreaks(value: string): string {
+  return value.replace(/\r\n|\r|\n/g, '\r\n')
+}
+
+async function defaultResolveFrame(src: string, options?: ResolveFrameOptions): Promise<Response> {
+  let response = await fetch(src, {
+    body: getRequestBody(options),
+    headers: { Accept: 'text/html' },
+    method: options?.method,
+    signal: options?.signal,
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to resolve frame: ${response.status} ${response.statusText}`.trimEnd())
+  }
+
+  return response
+}
+
 /**
  * Starts the client-side Remix component runtime for the current document.
  *
- * @param init Runtime hooks for loading modules and resolving frames.
+ * @param init Runtime options for loading modules and customizing frame resolution.
  * @returns The running application runtime.
  */
 export function run(init: RunInit): AppRuntime {
@@ -83,7 +127,7 @@ export function run(init: RunInit): AppRuntime {
   let errorTarget = new TypedEventTarget<AppRuntimeEventMap>()
   let scheduler = createScheduler(document, errorTarget, styleManager)
 
-  let resolveFrame: ResolveFrame = init.resolveFrame ?? (() => '<p>resolve frame unimplemented</p>')
+  let resolveFrame = init.resolveFrame ?? defaultResolveFrame
 
   topFrame = createFrame(document, {
     src: document.location.href,
@@ -107,7 +151,7 @@ export function run(init: RunInit): AppRuntime {
       return namedFrames.get(name)
     },
   }
-  startNavigationListener(appController.signal, init.resolveFrame !== undefined)
+  startNavigationListener(appController.signal)
   let readyPromise = topFrame.ready().catch((error) => {
     errorTarget.dispatchEvent(createComponentErrorEvent(error))
     throw error

package/src/server/README.md

@@ -23,6 +23,7 @@ Renders a component tree to a streaming response. The initial HTML is sent immed
 
 ```tsx
 import { renderToStream } from 'remix/ui/server'
+import { assetServer } from './assets.ts'
 
 let stream = renderToStream(<App />, {
   frameSrc: request.url,
@@ -31,6 +32,17 @@ let stream = renderToStream(<App />, {
     let frameUrl = new URL(src, context?.currentFrameSrc ?? request.url)
     return fetchHtml(frameUrl)
   },
+  async resolveClientEntry(entryId, component) {
+    let [href, preloads] = await Promise.all([
+      assetServer.getHref(entryId),
+      assetServer.getPreloads(entryId),
+    ])
+    return {
+      href,
+      exportName: entryId.split('#')[1] || component.name,
+      preloads,
+    }
+  },
   onError(error) {
     console.error(error)
   },
@@ -47,6 +59,7 @@ return new Response(stream, {
 - **`topFrameSrc`** - Overrides the root frame URL used for `handle.frames.top.src`. This is mainly useful when calling `renderToStream()` from inside `resolveFrame()` for a nested frame render.
 - **`signal`** - Cancels pending server rendering work. Pass `request.signal` so client disconnects can stop unresolved frame work without invoking `onError` for the disconnect itself.
 - **`resolveFrame(src, target, context)`** - Called when a `<Frame>` needs its content. Return a string of HTML, a `ReadableStream<Uint8Array>`, or a promise of either. `context.currentFrameSrc` is the URL for the frame that contains the `<Frame>`, and `context.topFrameSrc` is the outer document URL. Required if your component tree contains `<Frame>` elements.
+- **`resolveClientEntry(entryId, component)`** - Resolves the public module URL, export name, and optional module preload hrefs for a hydrated client entry.
 - **`onError(error)`** - Called when a rendering error occurs. If not provided, the stream rejects with the error.
 
 When you render nested frame responses with `renderToStream()` inside `resolveFrame()`, pass `frameSrc` for the frame being rendered and carry `topFrameSrc` forward from the parent context. That preserves `handle.frames.top.src` across the whole SSR frame tree.

package/src/server/stream.ts

@@ -77,6 +77,8 @@ interface UnresolvedHydrationData {
 interface ResolvedClientEntry {
   href: string
   exportName: string
+  /** Browser module hrefs to begin preloading before hydrating this entry. */
+  preloads?: readonly string[]
 }
 
 interface FrameData {
@@ -99,6 +101,7 @@ interface RenderContext {
   hydrationData: Map<string, HydrationData>
   unresolvedHydrationData: Map<string, UnresolvedHydrationData>
   frameData: Map<string, FrameData>
+  modulePreloadTags: Set<string>
   blockingFrameTails: ReadableStream<Uint8Array>[]
   signal: AbortSignal
   flushKind: FlushKind
@@ -207,6 +210,7 @@ export function renderToStream(
     hydrationData: new Map(),
     unresolvedHydrationData: new Map(),
     frameData: new Map(),
+    modulePreloadTags: new Set(),
     blockingFrameTails: [],
     signal: renderAbortController.signal,
     flushKind: 'fragment',
@@ -492,6 +496,7 @@ function buildFrameSegment(
       context.resolveFrame(props.src, props.name, resolveFrameContext),
     ).then(async (resolved) => {
       let { html, tail } = await resolveFrameHtml(resolved)
+      html = hoistModulePreloadsFromFrameHead(html, context)
       seg.content = staticSeg(html)
       if (tail) {
         context.blockingFrameTails.push(tail)
@@ -1073,6 +1078,10 @@ async function resolveClientEntries(
       moduleUrl: resolvedEntry.href,
       props,
     })
+
+    for (let preload of resolvedEntry.preloads ?? []) {
+      context.modulePreloadTags.add(createModulePreloadTag(preload))
+    }
   }
 
   context.unresolvedHydrationData.clear()
@@ -1095,6 +1104,19 @@ function validateResolvedClientEntry(
   if (!resolvedEntry.exportName) {
     throw new Error(`resolveClientEntry must return a non-empty exportName. Received "${entryId}".`)
   }
+
+  if (resolvedEntry.preloads !== undefined) {
+    if (!Array.isArray(resolvedEntry.preloads)) {
+      throw new Error(`resolveClientEntry preloads must be an array. Received "${entryId}".`)
+    }
+    for (let preload of resolvedEntry.preloads) {
+      if (typeof preload !== 'string' || preload.length === 0) {
+        throw new Error(
+          `resolveClientEntry preloads must contain non-empty strings. Received "${entryId}".`,
+        )
+      }
+    }
+  }
 }
 
 function validateClientEntriesForHydration(context: RenderContext): void {
@@ -1159,9 +1181,10 @@ function transformAttributeName(name: string, isSvg: boolean): string {
 function finalizeHtml(html: string, context: RenderContext): string {
   let hasHtmlRoot = context.flushKind === 'document'
 
+  let preloads = collectModulePreloadTags(context)
   let styles = collectStyleTags(context)
-  if (styles) {
-    let headContent = styles
+  if (preloads || styles) {
+    let headContent = preloads + styles
     if (hasHtmlRoot) {
       // For HTML root, inject into existing head or create one
       let headCloseIndex = html.indexOf('</head>')
@@ -1207,6 +1230,52 @@ function finalizeHtml(html: string, context: RenderContext): string {
   return html
 }
 
+const FRAME_HEAD_OPEN_TAG = '<head>'
+const FRAME_HEAD_CLOSE_TAG = '</head>'
+const MARKED_MODULE_PRELOAD_START = '<link data-rmx rel="modulepreload" href="'
+const MODULE_PRELOAD_END = '" />'
+
+function createModulePreloadTag(href: string): string {
+  return `${MARKED_MODULE_PRELOAD_START}${escapeHtml(href)}${MODULE_PRELOAD_END}`
+}
+
+function collectModulePreloadTags(context: RenderContext): string {
+  return Array.from(context.modulePreloadTags).join('')
+}
+
+function hoistModulePreloadsFromFrameHead(html: string, context: RenderContext): string {
+  if (!html.startsWith(FRAME_HEAD_OPEN_TAG)) return html
+
+  let tags: string[] = []
+  let remainingHeadStart = FRAME_HEAD_OPEN_TAG.length
+  while (html.startsWith(MARKED_MODULE_PRELOAD_START, remainingHeadStart)) {
+    let tagEnd = html.indexOf(
+      MODULE_PRELOAD_END,
+      remainingHeadStart + MARKED_MODULE_PRELOAD_START.length,
+    )
+    if (tagEnd === -1) return html
+
+    tagEnd += MODULE_PRELOAD_END.length
+    tags.push(html.slice(remainingHeadStart, tagEnd))
+    remainingHeadStart = tagEnd
+  }
+
+  if (tags.length === 0) return html
+
+  let headClose = html.indexOf(FRAME_HEAD_CLOSE_TAG, remainingHeadStart)
+  if (headClose === -1) return html
+
+  for (let tag of tags) {
+    context.modulePreloadTags.add(tag)
+  }
+
+  if (remainingHeadStart === headClose) {
+    return html.slice(headClose + FRAME_HEAD_CLOSE_TAG.length)
+  }
+
+  return FRAME_HEAD_OPEN_TAG + html.slice(remainingHeadStart)
+}
+
 function processStyleProps(props: any): any {
   let processedProps = { ...props }
   let classAttr = typeof props.class === 'string' ? props.class : ''