flamefront 0.1.0-alpha.0 → 0.1.0

package/package.json

@@ -1,17 +1,16 @@
 {
   "name": "flamefront",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0",
   "private": false,
   "description": "Typed centralized route manifests for Octane.",
   "license": "FSL-1.1-MIT",
+  "repository": "https://github.com/aleclarson/flamefront",
   "files": [
-    "LICENSE.md",
-    "README.md",
     "bin",
     "src"
   ],
   "engines": {
-    "node": ">=22.22.2"
+    "node": ">=26.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -22,45 +21,69 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./fragment": "./src/fragment.ts",
-    "./octane": "./src/octane.ts",
+    "./entry": "./src/entry.ts",
+    "./fetch": "./src/fetch.ts",
+    "./fragment": "./src/fragment.tsx",
+    "./octane": "./src/octane.tsx",
     "./octane/client": "./src/octane-client.ts",
     "./octane/router-document": "./src/octane-router-document.ts",
     "./remix-router": "./src/remix-router.ts",
     "./remix-router/data": "./src/remix-route-data.ts",
     "./server": "./src/server.ts",
+    "./output": "./src/output.ts",
     "./srvx": "./src/srvx.ts",
     "./vite": "./src/vite.ts"
   },
+  "scripts": {
+    "dev": "pnpm --filter flamefront-playground dev",
+    "build": "pnpm --filter flamefront-playground build",
+    "preview": "pnpm --filter flamefront-playground preview",
+    "typegen": "pnpm --filter flamefront-playground typegen",
+    "routes": "pnpm --filter flamefront-playground routes",
+    "typecheck": "tsc -p tsconfig.json && pnpm --filter flamefront-playground typecheck",
+    "test": "vitest run",
+    "test:e2e": "pnpm --filter flamefront-playground build && vitest run --config vitest.e2e.config.ts",
+    "check": "oxlint && prettier --check . && pnpm typecheck && pnpm test && pnpm test:e2e",
+    "format": "oxlint --fix && prettier --write ."
+  },
   "dependencies": {
     "@alloc/cmd-ts": "0.17.1",
-    "@babel/generator": "^7.29.8",
-    "@babel/parser": "^7.29.8",
-    "@babel/traverse": "^7.29.8",
-    "@babel/types": "^7.29.8",
+    "@babel/generator": "^8.0.5",
+    "@babel/parser": "^8.0.5",
+    "@babel/traverse": "^8.0.5",
+    "@babel/types": "^8.0.5",
     "@remix-run/route-pattern": "0.24.0",
-    "babel-dead-code-elimination": "^1.0.12",
-    "srvx": "0.12.5"
+    "babel-dead-code-elimination": "^2.0.0",
+    "satteri": "^0.10.5",
+    "srvx": "1.0.4",
+    "vite-plugin-satteri": "^0.3.5"
   },
   "devDependencies": {
+    "@octanejs/remix-router": "0.1.48",
+    "@octanejs/vite-plugin": "0.1.54",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@tsrx/prettier-plugin": "^0.3.137",
     "@types/babel__generator": "^7.27.0",
     "@types/babel__traverse": "^7.28.0",
-    "@types/node": "26.1.1",
+    "@types/node": "26.5.1",
+    "octane": "0.2.7",
+    "oxc-tsrx": "0.6.1",
+    "oxlint": "^1.82.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "playwright": "1.63.0",
+    "prettier": "^3.9.6",
     "typescript": "5.9.3",
-    "vite": "latest"
+    "vite": "8.3.0",
+    "vitest": "^5.0.0"
   },
   "peerDependencies": {
-    "@octanejs/remix-router": "0.1.36",
-    "octane": "0.1.40",
-    "vite": "^8.0.16"
+    "@octanejs/remix-router": "0.1.48",
+    "octane": "0.2.7",
+    "vite": "^8.3.0"
   },
   "peerDependenciesMeta": {
     "@octanejs/remix-router": {
       "optional": true
     }
-  },
-  "scripts": {
-    "test": "node --test test/*.test.ts",
-    "typecheck": "tsc -p tsconfig.json"
   }
-}
+}

package/src/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { relative } from "node:path"
 import {
   binary,
   command,
@@ -16,6 +17,7 @@ import {
   loadProject,
   previewProject,
 } from "./lifecycle.ts"
+import { generateProjectTypes } from "./typegen.ts"
 
 const routes = command({
   name: "routes",
@@ -73,11 +75,24 @@ const preview = command({
   handler: () => previewProject(),
 })
 
+const typegen = command({
+  name: "typegen",
+  description: "Generate route import declarations for the current app.",
+  args: {},
+  async handler() {
+    const result = await generateProjectTypes()
+    const status = result.written ? "Generated" : "Unchanged"
+    const file = relative(process.cwd(), result.file) || "."
+
+    console.log(`${status} ${file}.`)
+  },
+})
+
 const cli = subcommands({
   name: "ff",
   version: "0.1.0-alpha.0",
   description: "Flamefront, a small compiler-oriented framework for Octane.",
-  cmds: { build, dev, preview, routes },
+  cmds: { build, dev, preview, routes, typegen },
 })
 
 await run(binary(cli), process.argv)

package/src/entry.ts

@@ -0,0 +1,49 @@
+import type { RouteDefinition } from "./index.ts"
+
+export type {
+  FetchMiddleware,
+  FetchServerAssets,
+  FetchServerEntryOptions,
+  FlamefrontFetchServerEntry,
+  ResponseHeaders,
+  ResponseHeadersContext,
+  ResponseHeadersHook,
+  ServerDocuments,
+  ServerEntryLifecycle,
+  StaticFragmentContext,
+  StaticFragmentLoader,
+  TemplateContext,
+  TemplateLoader,
+} from "./fetch.ts"
+export type {
+  FlamefrontServerEntry,
+  ServerAssets,
+  SrvxMiddleware,
+  SrvxServerEntryOptions,
+} from "./srvx.ts"
+
+import type {
+  FetchServerEntryOptions,
+  FlamefrontFetchServerEntry,
+} from "./fetch.ts"
+import type { FlamefrontServerEntry, SrvxServerEntryOptions } from "./srvx.ts"
+
+export type ServerEntryOptions<
+  Route extends RouteDefinition = RouteDefinition,
+> = FetchServerEntryOptions<Route> | SrvxServerEntryOptions<Route>
+
+export type ServerEntry = FlamefrontFetchServerEntry | FlamefrontServerEntry
+
+/**
+ * Create the server entry selected by the `flamefront` Vite plugin options.
+ * Vite replaces this placeholder with the generated adapter module at build
+ * time; the direct-import error prevents an accidental unconfigured entry.
+ */
+export function createServerEntry<
+  Route extends RouteDefinition = RouteDefinition,
+>(options: ServerEntryOptions<Route>): ServerEntry {
+  void options
+  throw new Error(
+    "flamefront/entry must be loaded through the flamefront Vite plugin.",
+  )
+}

package/src/fetch.ts

@@ -0,0 +1,280 @@
+import {
+  joinBasename,
+  type AppDefinition,
+  type RouteDefinition,
+} from "./index.ts"
+import type { OctaneDocuments } from "./octane.tsx"
+import type { DocumentMode, RenderedDocument } from "./server.ts"
+import {
+  isRouteFragmentRequest,
+  stripFlamefrontProtocolRequest,
+} from "./fragment-protocol.ts"
+import type { RouteFragmentArtifact } from "./fragment-client.ts"
+
+export interface TemplateContext<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly request: Request
+  readonly route: Route | null
+  readonly mode: DocumentMode
+}
+
+export type TemplateLoader<Route extends RouteDefinition = RouteDefinition> = (
+  context: TemplateContext<Route>,
+) => string | Promise<string>
+
+export interface StaticFragmentContext<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly request: Request
+  readonly route: Route
+}
+
+/** Load a pre-rendered static fragment from the host's asset system. */
+export type StaticFragmentLoader<
+  Route extends RouteDefinition = RouteDefinition,
+> = (
+  context: StaticFragmentContext<Route>,
+) =>
+  RouteFragmentArtifact | undefined | Promise<RouteFragmentArtifact | undefined>
+
+export interface ResponseHeadersContext<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly request: Request
+  readonly route: Route | null
+  readonly mode: DocumentMode
+  readonly document: RenderedDocument
+}
+
+export type ResponseHeaders = HeadersInit
+
+/** Add or override response headers after document rendering. */
+export type ResponseHeadersHook<
+  Route extends RouteDefinition = RouteDefinition,
+> = (
+  context: ResponseHeadersContext<Route>,
+) => ResponseHeaders | Promise<ResponseHeaders>
+
+export type FetchMiddleware = (
+  request: Request,
+  next: () => Response | Promise<Response>,
+) => Response | Promise<Response>
+
+export type ServerDocuments = Pick<
+  OctaneDocuments,
+  "renderDocument" | "loadRouteData"
+> &
+  Partial<Pick<OctaneDocuments, "renderFragment">>
+
+/** Lifecycle operations shared by all Flamefront server adapters. */
+export interface ServerEntryLifecycle {
+  readonly renderDocument: OctaneDocuments["renderDocument"]
+  readonly loadRouteData: OctaneDocuments["loadRouteData"]
+  readonly renderFragment?: OctaneDocuments["renderFragment"]
+}
+
+/** A Web Fetch-compatible server entry. */
+export interface FlamefrontFetchServerEntry extends ServerEntryLifecycle {
+  readonly fetch: (request: Request) => Response | Promise<Response>
+}
+
+export interface FetchServerAssets<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly loadTemplate: TemplateLoader<Route>
+  readonly loadStaticFragment?: StaticFragmentLoader<Route>
+}
+
+export interface FetchServerEntryOptions<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly app: AppDefinition<Route>
+  readonly documents: ServerDocuments
+  readonly assets: FetchServerAssets<Route>
+  /** Applied outermost first, in declaration order. */
+  readonly middleware?: readonly FetchMiddleware[]
+  readonly headers?: ResponseHeadersHook<Route>
+}
+
+function mergeHeaders(target: Headers, source: HeadersInit | undefined): void {
+  if (source === undefined) {
+    return
+  }
+
+  for (const [name, value] of new Headers(source)) {
+    target.set(name, value)
+  }
+}
+
+function composeMiddleware(
+  middleware: readonly FetchMiddleware[],
+  handler: (request: Request) => Promise<Response>,
+): (request: Request) => Promise<Response> {
+  return middleware.reduceRight<(request: Request) => Promise<Response>>(
+    (next, current) => async (request) => current(request, () => next(request)),
+    handler,
+  )
+}
+
+/**
+ * Create the transport-neutral Flamefront request handler. Hosts can expose
+ * the returned `fetch` function directly or wrap it in their own adapter.
+ */
+export function createFetchServerEntry<
+  Route extends RouteDefinition = RouteDefinition,
+>(options: FetchServerEntryOptions<Route>): FlamefrontFetchServerEntry {
+  const defaultClientRoute = options.app.routes.find(
+    (route) => route.render === "client",
+  )
+
+  const handleRequest = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url)
+    const match = options.app.match(url)
+
+    try {
+      if (
+        url.pathname === options.app.routing.basename &&
+        !match &&
+        defaultClientRoute
+      ) {
+        return new Response(null, {
+          status: 302,
+          headers: {
+            Location: joinBasename(
+              options.app.routing.basename,
+              defaultClientRoute.path,
+            ),
+          },
+        })
+      }
+
+      if (url.pathname === options.app.routing.dataPath) {
+        return options.documents.loadRouteData(request)
+      }
+
+      if (isRouteFragmentRequest(url)) {
+        const sanitizedRequest = stripFlamefrontProtocolRequest(request)
+        const fragmentMatch = options.app.match(sanitizedRequest.url)
+
+        if (!fragmentMatch || fragmentMatch.data.render === "client") {
+          return new Response("Not found", { status: 404 })
+        }
+
+        let artifact: RouteFragmentArtifact | undefined
+
+        if (
+          fragmentMatch.data.render === "static" &&
+          options.assets.loadStaticFragment
+        ) {
+          artifact = await options.assets.loadStaticFragment({
+            request: sanitizedRequest,
+            route: fragmentMatch.data,
+          })
+        }
+
+        if (!artifact && options.documents.renderFragment) {
+          artifact = await options.documents.renderFragment(sanitizedRequest)
+        }
+
+        if (!artifact) {
+          return new Response("Not found", { status: 404 })
+        }
+
+        const responseHeaders = new Headers({
+          "Content-Type":
+            "application/vnd.flamefront.fragment+json; charset=utf-8",
+        })
+
+        if (options.headers) {
+          mergeHeaders(
+            responseHeaders,
+            await options.headers({
+              request: sanitizedRequest,
+              route: fragmentMatch.data,
+              mode: fragmentMatch.data.render,
+              document: {
+                html: artifact.html,
+                routeData: artifact.routeData,
+                status: artifact.status,
+              },
+            }),
+          )
+        }
+
+        return new Response(JSON.stringify(artifact), {
+          status: artifact.status ?? 200,
+          headers: responseHeaders,
+        })
+      }
+
+      if (!match) {
+        return new Response("Not found", { status: 404 })
+      }
+
+      const mode: DocumentMode = url.searchParams.has("__flamefront_shell")
+        ? "shell"
+        : match.data.render
+      const template = await options.assets.loadTemplate({
+        request,
+        route: match.data,
+        mode,
+      })
+      const document = await options.documents.renderDocument(
+        template,
+        request,
+        { mode },
+      )
+      const responseHeaders = new Headers({
+        "Content-Type": "text/html; charset=utf-8",
+      })
+
+      mergeHeaders(responseHeaders, document.headers)
+      if (options.headers) {
+        mergeHeaders(
+          responseHeaders,
+          await options.headers({
+            request,
+            route: match.data,
+            mode,
+            document,
+          }),
+        )
+      }
+
+      return new Response(document.html, {
+        status: document.status ?? 200,
+        headers: responseHeaders,
+      })
+    } catch (error) {
+      if (error instanceof Response) {
+        return error
+      }
+
+      throw error
+    }
+  }
+
+  const composedFetch = composeMiddleware(
+    options.middleware ?? [],
+    handleRequest,
+  )
+  const fetch = async (request: Request): Promise<Response> => {
+    try {
+      return await composedFetch(request)
+    } catch (error) {
+      if (error instanceof Response) {
+        return error
+      }
+
+      throw error
+    }
+  }
+
+  return {
+    fetch,
+    renderDocument: options.documents.renderDocument,
+    loadRouteData: options.documents.loadRouteData,
+    renderFragment: options.documents.renderFragment,
+  }
+}