flamefront 0.1.0-alpha.0 → 0.1.0

package/src/{octane.ts → octane.tsx}

@@ -2,6 +2,7 @@ import type {
   AppDefinition,
   GeneratedRouteMetadata,
   RouteDefinition,
+  RouteParams,
 } from "./index.ts"
 import type {
   DocumentMode,
@@ -15,16 +16,22 @@ import type {
 } from "./remix-router-core.ts"
 import { stripFlamefrontProtocolRequest } from "./fragment-protocol.ts"
 import {
-  staticFragmentProtocol,
-  type StaticFragmentArtifact,
-  type StaticFragmentBoundary,
+  routeFragmentProtocol,
+  type RouteFragmentArtifact,
+  type RouteFragmentBoundary,
 } from "./fragment-client.ts"
+import {
+  outletIdentifierPrefix,
+  shellIdentifierPrefix,
+} from "./identifier-prefix.ts"
 
 export type { DocumentMode, RenderedDocument } from "./server.ts"
 
 export interface RouterDocumentProps {
   readonly router: unknown
   readonly context: unknown
+  /** Server-only markup for the independently-owned routed outlet. */
+  readonly outletHtml?: string | null
 }
 
 export type RouterDocument = (props: RouterDocumentProps) => unknown
@@ -43,7 +50,7 @@ export interface DocumentCompositionContext<
   readonly request: Request
   readonly mode: DocumentMode
   readonly route: Route | null
-  readonly params: Readonly<Record<string, string | undefined>>
+  readonly params: Readonly<RouteParams<Route["path"]>>
   readonly status: number
 }
 
@@ -71,14 +78,19 @@ export interface OctaneRenderer {
     context: unknown,
   ) => unknown
   readonly renderToString: (
-    component: unknown,
+    component: RouterDocument,
     props: RouterDocumentProps,
+    options?: { readonly identifierPrefix?: string },
   ) => OctaneRenderResult
   /** Render one generated route boundary directly from the static router tree. */
   readonly renderRouteFragment?: (
     router: unknown,
     context: unknown,
     boundary: string,
+    options?: {
+      readonly identifierPrefix?: string
+      readonly includeBoundary?: boolean
+    },
   ) => OctaneRenderResult
   readonly defaultRouterDocument: RouterDocument
 }
@@ -113,7 +125,7 @@ export interface OctaneDocuments {
     options?: RenderDocumentOptions,
   ) => Promise<RenderedDocument>
   readonly loadRouteData: (request: Request) => Promise<Response>
-  readonly renderFragment: (request: Request) => Promise<StaticFragmentArtifact>
+  readonly renderFragment: (request: Request) => Promise<RouteFragmentArtifact>
 }
 
 interface StaticDocumentContext {
@@ -228,132 +240,12 @@ async function loadDefaultRouter(): Promise<DocumentRouter> {
 }
 
 async function loadDefaultRenderer(): Promise<OctaneRenderer> {
-  const [remix, routerDocument, octane, fragment] = await Promise.all([
-    import("@octanejs/remix-router"),
-    import("./octane-router-document.ts"),
-    import("octane/server"),
-    import("./fragment.ts"),
-  ])
-
-  const createStaticNavigator = (router: {
-    readonly createHref: (to: unknown) => string
-    readonly encodeLocation: (to: unknown) => unknown
-  }) => ({
-    createHref: router.createHref,
-    encodeLocation: router.encodeLocation,
-    push() {
-      throw new Error(
-        "Static fragment rendering cannot navigate on the server.",
-      )
-    },
-    replace() {
-      throw new Error(
-        "Static fragment rendering cannot navigate on the server.",
-      )
-    },
-    go() {
-      throw new Error(
-        "Static fragment rendering cannot navigate on the server.",
-      )
-    },
-    back() {
-      throw new Error(
-        "Static fragment rendering cannot navigate on the server.",
-      )
-    },
-    forward() {
-      throw new Error(
-        "Static fragment rendering cannot navigate on the server.",
-      )
-    },
-  })
-
-  return {
-    createStaticRouter: (routes, context) =>
-      remix.createStaticRouter(routes as any[], context as any),
-    renderToString: (component, props) =>
-      octane.renderToString(component as never, props as never),
-    renderRouteFragment: (router, context, boundary) => {
-      const dataRouter = router as {
-        readonly state: {
-          readonly location: unknown
-          readonly matches: readonly {
-            readonly route?: { readonly id?: string }
-          }[]
-        }
-        readonly createHref: (to: unknown) => string
-        readonly encodeLocation: (to: unknown) => unknown
-      }
-      const staticContext = context as { readonly basename?: string }
-      const state = dataRouter.state
-      const matchIndex = state.matches.findIndex(
-        (match) => match.route?.id === boundary,
-      )
-
-      if (matchIndex < 0) {
-        throw new Error(
-          `No static router match exists for fragment boundary ${JSON.stringify(boundary)}.`,
-        )
-      }
-
-      const navigator = createStaticNavigator(dataRouter)
-      const dataRouterContext = {
-        router: dataRouter,
-        navigator,
-        static: true,
-        staticContext: context,
-        basename: staticContext.basename ?? "/",
-      }
-      const fragmentTree = remix.renderMatches(
-        state.matches.slice(matchIndex) as never,
-      )
-      const fragmentRoot = octane.createElement(
-        remix.UNSAFE_DataRouterContext.Provider as never,
-        {
-          value: dataRouterContext,
-          children: octane.createElement(
-            remix.UNSAFE_DataRouterStateContext.Provider as never,
-            {
-              value: state,
-              children: octane.createElement(
-                remix.UNSAFE_FetchersContext.Provider as never,
-                {
-                  value: new Map(),
-                  children: octane.createElement(
-                    remix.UNSAFE_ViewTransitionContext.Provider as never,
-                    {
-                      value: { isTransitioning: false },
-                      children: octane.createElement(
-                        remix.StaticRouter as never,
-                        {
-                          basename: staticContext.basename ?? "/",
-                          location: state.location,
-                          children: octane.createElement(
-                            fragment.staticFragmentBoundaryTarget
-                              .Provider as never,
-                            { value: boundary, children: fragmentTree },
-                          ),
-                        },
-                      ),
-                    },
-                  ),
-                },
-              ),
-            },
-          ),
-        },
-      )
-      const FragmentRoot = () => fragmentRoot
-
-      return octane.renderToString(FragmentRoot, {})
-    },
-    defaultRouterDocument: routerDocument.RouterDocument,
-  }
+  return (await import("./octane-default-renderer.tsx")).defaultOctaneRenderer
 }
 
-function createShellRouter(
+function createShellRouter<Route extends RouteDefinition>(
   request: Request,
-  app: AppDefinition,
+  app: AppDefinition<Route>,
   routeGraph: readonly unknown[],
   renderer: OctaneRenderer,
 ): { readonly context: StaticDocumentContext; readonly router: unknown } {
@@ -432,6 +324,47 @@ function routeData(context: StaticDocumentContext): unknown {
   return routeId ? (context.loaderData?.[routeId] ?? null) : null
 }
 
+function remapShellRouteError(
+  route: RouteDefinition | null,
+  context: StaticDocumentContext,
+  metadata: readonly GeneratedRouteMetadata[] | undefined,
+): StaticDocumentContext {
+  if (!route || !context.errors) {
+    return context
+  }
+
+  const chain = fragmentMetadataChain(route, metadata)
+  const shell = chain.find((item) => item.kind === "shell")
+  const outlet = shell ? chain[chain.indexOf(shell) + 1] : undefined
+
+  if (!shell || !outlet || !context.errors[shell.id]) {
+    return context
+  }
+
+  const errors = { ...context.errors }
+  const shellError = errors[shell.id]
+
+  delete errors[shell.id]
+  if (errors[outlet.id] === undefined) {
+    errors[outlet.id] = shellError
+  }
+
+  return {
+    ...context,
+    errors,
+  }
+}
+
+function routerRoutes(value: unknown): readonly unknown[] | undefined {
+  if (!value || typeof value !== "object") {
+    return undefined
+  }
+
+  const routes = (value as { readonly routes?: unknown }).routes
+
+  return Array.isArray(routes) ? routes : undefined
+}
+
 function fragmentMetadataChain(
   route: RouteDefinition,
   metadata: readonly GeneratedRouteMetadata[] | undefined,
@@ -470,20 +403,21 @@ function fragmentMetadataChain(
   return chain
 }
 
-function createStaticFragmentArtifact(
+function createRouteFragmentArtifact(
   route: RouteDefinition,
   context: StaticDocumentContext,
   router: unknown,
   renderer: OctaneRenderer,
   fallbackBody: string,
   metadata: readonly GeneratedRouteMetadata[] | undefined,
-): StaticFragmentArtifact {
+): RouteFragmentArtifact {
   const chain = fragmentMetadataChain(route, metadata)
-  const boundaries: StaticFragmentBoundary[] = chain.map((item) => {
+  const boundaries: RouteFragmentBoundary[] = chain.map((item) => {
     const rendered = renderer.renderRouteFragment?.(
       router,
       context,
       item.boundary,
+      { identifierPrefix: outletIdentifierPrefix },
     )
 
     return {
@@ -497,7 +431,7 @@ function createStaticFragmentArtifact(
   const fragmentHtml = boundaries.at(-1)?.html || fallbackBody
 
   return {
-    protocol: staticFragmentProtocol,
+    protocol: routeFragmentProtocol,
     route: route.path,
     boundary: chain.at(-1)?.boundary ?? route.entry,
     html: fragmentHtml,
@@ -508,6 +442,48 @@ function createStaticFragmentArtifact(
   }
 }
 
+function appendCss(documentCss: string, outletCss: string | undefined): string {
+  if (!outletCss || outletCss === documentCss) {
+    return documentCss
+  }
+
+  const tags = new Set(
+    `${documentCss}${outletCss}`.match(/<style\b[^>]*>[\s\S]*?<\/style>/g) ??
+      [],
+  )
+
+  return tags.size === 0 ? `${documentCss}${outletCss}` : [...tags].join("")
+}
+
+function renderDocumentOutlet(
+  route: RouteDefinition | null,
+  context: StaticDocumentContext,
+  router: unknown,
+  renderer: OctaneRenderer,
+  metadata: readonly GeneratedRouteMetadata[] | undefined,
+): { readonly html: string; readonly css: string } | undefined {
+  if (
+    !route ||
+    (route.render !== "server" && route.render !== "static") ||
+    !renderer.renderRouteFragment
+  ) {
+    return undefined
+  }
+
+  const chain = fragmentMetadataChain(route, metadata)
+  const shellIndex = chain.findIndex((item) => item.kind === "shell")
+  const outlet = shellIndex < 0 ? undefined : chain[shellIndex + 1]
+
+  if (!outlet) {
+    return undefined
+  }
+
+  return renderer.renderRouteFragment(router, context, outlet.boundary, {
+    identifierPrefix: outletIdentifierPrefix,
+    includeBoundary: true,
+  })
+}
+
 export function createOctaneDocuments<
   Context = unknown,
   Route extends RouteDefinition = RouteDefinition,
@@ -534,6 +510,8 @@ export function createOctaneDocuments<
   const renderRoute = async (
     request: Request,
     mode: DocumentMode,
+    route: RouteDefinition | null,
+    renderOutlet = false,
   ): Promise<{
     readonly router: DocumentRouter
     readonly dataRouter: unknown
@@ -564,17 +542,43 @@ export function createOctaneDocuments<
       throw result
     }
 
-    const context = result.context as StaticDocumentContext
+    const context = remapShellRouteError(
+      route,
+      result.context as StaticDocumentContext,
+      router.routeMetadata,
+    )
+    const dataRouter =
+      context === result.context
+        ? result.router
+        : renderer.createStaticRouter(
+            routerRoutes(result.router) ?? router.routes,
+            context,
+          )
+    const outlet = renderDocumentOutlet(
+      renderOutlet ? route : null,
+      context,
+      dataRouter,
+      renderer,
+      router.routeMetadata,
+    )
+    const documentProps: RouterDocumentProps = {
+      router: dataRouter,
+      context,
+      ...(outlet ? { outletHtml: outlet.html } : {}),
+    }
+    const rendered = renderer.renderToString(routerDocument, documentProps, {
+      identifierPrefix: shellIdentifierPrefix,
+    })
 
     return {
       router,
-      dataRouter: result.router,
+      dataRouter,
       renderer,
       context,
-      rendered: renderer.renderToString(routerDocument, {
-        router: result.router,
-        context: result.context,
-      }),
+      rendered: {
+        ...rendered,
+        css: appendCss(rendered.css, outlet?.css),
+      },
     }
   }
 
@@ -592,13 +596,17 @@ export function createOctaneDocuments<
     const { context: staticContext, rendered } = await renderRoute(
       sanitizedRequest,
       mode,
+      route,
+      true,
     )
     const status = staticContext.statusCode ?? 200
     const compositionContext: DocumentCompositionContext<Route> = {
       request: sanitizedRequest,
       mode,
       route,
-      params: routeMatch?.params ?? {},
+      params: (routeMatch?.params ?? {}) as Readonly<
+        RouteParams<Route["path"]>
+      >,
       status,
     }
     const parts: DocumentParts = {
@@ -623,20 +631,19 @@ export function createOctaneDocuments<
 
   const renderFragment = async (
     request: Request,
-  ): Promise<StaticFragmentArtifact> => {
+  ): Promise<RouteFragmentArtifact> => {
     const sanitizedRequest = stripFlamefrontProtocolRequest(request)
     const routeMatch = options.app.match(sanitizedRequest.url)
     const route = routeMatch?.data ?? null
 
-    assertRouteMode(route, "static")
-    if (!route) {
+    if (!route || route.render === "client") {
       throw new Response("Not found", { status: 404 })
     }
 
     const { router, dataRouter, renderer, rendered, context } =
-      await renderRoute(sanitizedRequest, "static")
+      await renderRoute(sanitizedRequest, route.render, route)
 
-    return createStaticFragmentArtifact(
+    return createRouteFragmentArtifact(
       route,
       context,
       dataRouter,

package/src/output.ts

@@ -0,0 +1,48 @@
+export type FlamefrontTarget = "node" | "deno" | "bun"
+export type FlamefrontAdapter = "fetch" | "srvx"
+
+export interface FlamefrontOutputOptions {
+  /** Select the runtime family used by the built-in srvx adapter. */
+  readonly target?: FlamefrontTarget
+}
+
+export type ResolvedFlamefrontOutput =
+  | {
+      readonly adapter: "fetch"
+      readonly target?: undefined
+    }
+  | {
+      readonly adapter: "srvx"
+      readonly target: FlamefrontTarget
+    }
+
+const targets: ReadonlySet<FlamefrontTarget> = new Set(["node", "deno", "bun"])
+
+/** Resolve the public output options into the generated server entry kind. */
+export function resolveFlamefrontOutput(
+  options: FlamefrontOutputOptions = {},
+): ResolvedFlamefrontOutput {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("flamefront output options must be an object.")
+  }
+
+  if (options.target !== undefined && !targets.has(options.target)) {
+    throw new TypeError(
+      `flamefront target must be one of "node", "deno", or "bun"; received ${JSON.stringify(options.target)}.`,
+    )
+  }
+
+  const requestedAdapter = (options as { readonly adapter?: unknown }).adapter
+
+  if (requestedAdapter !== undefined) {
+    throw new TypeError(
+      `flamefront adapter is not supported; omit "adapter" and use "target" for srvx or the default Web Fetch entry.`,
+    )
+  }
+
+  if (options.target !== undefined) {
+    return Object.freeze({ adapter: "srvx", target: options.target })
+  }
+
+  return Object.freeze({ adapter: "fetch" })
+}

package/src/remix-route-data.ts

@@ -3,10 +3,12 @@ import {
   type RouteDataLoadOptions,
   type RouteDataRoutingOptions,
 } from "./route-data-client.ts"
+import type { RouteDataForPath } from "./index.ts"
 import {
-  loadStaticFragment,
-  type StaticFragmentLoadOptions,
-  type StaticFragmentRoutingOptions,
+  loadRouteFragment as loadFragmentArtifact,
+  type RouteFragmentCachePolicy,
+  type RouteFragmentLoadOptions,
+  type RouteFragmentRoutingOptions,
 } from "./fragment-client.ts"
 
 export {
@@ -17,7 +19,7 @@ export {
   type RouteDataSource,
 } from "./route-data-client.ts"
 
-export interface ClientLoaderArgs {
+export interface ClientLoaderArgs<_Path extends string = string> {
   readonly request: Request
 }
 
@@ -31,38 +33,44 @@ function client(options: RouteDataOptions) {
 }
 
 /** Load route data through Flamefront's server endpoint during browser navigation. */
-export async function loadRouteData(
-  { request }: ClientLoaderArgs,
+export async function loadRouteData<const Path extends string = string>(
+  { request }: ClientLoaderArgs<Path>,
   options: RouteDataOptions = {},
-): Promise<unknown> {
+): Promise<RouteDataForPath<Path>> {
   const loadOptions: RouteDataLoadOptions = { signal: request.signal }
 
-  return client(options).load(request.url, "live", loadOptions)
+  return client(options).load(request.url, "live", loadOptions) as Promise<
+    RouteDataForPath<Path>
+  >
 }
 
 /** Load a build-time static route artifact during browser navigation. */
-export async function loadStaticRouteData(
-  { request }: ClientLoaderArgs,
+export async function loadStaticRouteData<const Path extends string = string>(
+  { request }: ClientLoaderArgs<Path>,
   options: RouteDataOptions = {},
-): Promise<unknown> {
+): Promise<RouteDataForPath<Path>> {
   const loadOptions: RouteDataLoadOptions = { signal: request.signal }
 
-  return client(options).load(request.url, "static", loadOptions)
+  return client(options).load(request.url, "static", loadOptions) as Promise<
+    RouteDataForPath<Path>
+  >
 }
 
-/** Load a static fragment and expose only its route data to the router. */
-export async function loadStaticRouteFragment(
-  { request }: ClientLoaderArgs,
+/** Load a route fragment and expose only its route data to the router. */
+export async function loadRouteFragment<const Path extends string = string>(
+  { request }: ClientLoaderArgs<Path>,
   options: RouteDataOptions = {},
-): Promise<unknown> {
-  const fragmentOptions: StaticFragmentLoadOptions = {
+  policy: RouteFragmentCachePolicy = "static",
+): Promise<RouteDataForPath<Path>> {
+  const fragmentOptions: RouteFragmentLoadOptions = {
+    policy,
     signal: request.signal,
   }
-  const artifact = await loadStaticFragment(
+  const artifact = await loadFragmentArtifact(
     request.url,
-    options satisfies StaticFragmentRoutingOptions,
+    options satisfies RouteFragmentRoutingOptions,
     fragmentOptions,
   )
 
-  return artifact.routeData
+  return artifact.routeData as RouteDataForPath<Path>
 }

package/src/remix-router.ts

@@ -20,7 +20,7 @@ import {
   type RoutePrefetchCallback,
   type RoutePrefetchResources,
 } from "./route-prefetch.ts"
-import { prefetchStaticFragment } from "./fragment-client.ts"
+import { prefetchRouteFragment } from "./fragment-client.ts"
 import {
   preloadRoute as preloadGeneratedRoute,
   RouterDocument,
@@ -72,9 +72,15 @@ function withDefaultPrefetchResources<
 ): RoutePrefetchResources<Route> {
   return {
     ...resources,
-    staticFragment:
-      resources.staticFragment ??
-      ((url, _route, options) => prefetchStaticFragment(url, routing, options)),
+    routeFragment:
+      resources.routeFragment ??
+      ((url, route, options) => {
+        if (route.render === "client") {
+          return
+        }
+
+        return prefetchRouteFragment(url, route.render, routing, options)
+      }),
   }
 }
 

package/src/route-data-client.ts

@@ -1,4 +1,5 @@
 import { stripFlamefrontProtocolParams } from "./fragment-protocol.ts"
+import type { RouteDataForPath } from "./index.ts"
 
 export type RouteDataSource = "live" | "static"
 
@@ -13,16 +14,25 @@ export interface RouteDataLoadOptions {
 }
 
 export interface RouteDataClient {
-  readonly load: <Data = unknown>(
-    url: string | URL,
-    source: RouteDataSource,
-    options?: RouteDataLoadOptions,
-  ) => Promise<Data>
-  readonly prefetch: (
-    url: string | URL,
-    source: RouteDataSource,
-    options?: RouteDataLoadOptions,
-  ) => Promise<void>
+  readonly load: {
+    <const Url extends string>(
+      url: Url,
+      source: RouteDataSource,
+      options?: RouteDataLoadOptions,
+    ): Promise<RouteDataForPath<Url>>
+    <Data = unknown>(
+      url: string | URL,
+      source: RouteDataSource,
+      options?: RouteDataLoadOptions,
+    ): Promise<Data>
+  }
+  readonly prefetch: {
+    (
+      url: string | URL,
+      source: RouteDataSource,
+      options?: RouteDataLoadOptions,
+    ): Promise<void>
+  }
 }
 
 const defaultRouting = Object.freeze({
@@ -140,7 +150,7 @@ function createIsolatedRouteDataClient(routing: {
 }): RouteDataClient {
   const cache = new Map<string, Promise<unknown>>()
 
-  const load = <Data = unknown>(
+  const load = (<Data = unknown>(
     url: string | URL,
     source: RouteDataSource,
     options: RouteDataLoadOptions = {},
@@ -191,7 +201,7 @@ function createIsolatedRouteDataClient(routing: {
       }
     })
     return abortable(pending, options.signal)
-  }
+  }) as RouteDataClient["load"]
 
   return {
     load,