flamefront 0.0.0 → 0.1.0-alpha.0

package/package.json

@@ -1,13 +1,66 @@
 {
   "name": "flamefront",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.1.0-alpha.0",
+  "private": false,
+  "description": "Typed centralized route manifests for Octane.",
+  "license": "FSL-1.1-MIT",
+  "files": [
+    "LICENSE.md",
+    "README.md",
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ff": "./bin/ff.js"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./fragment": "./src/fragment.ts",
+    "./octane": "./src/octane.ts",
+    "./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",
+    "./srvx": "./src/srvx.ts",
+    "./vite": "./src/vite.ts"
+  },
+  "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",
+    "@remix-run/route-pattern": "0.24.0",
+    "babel-dead-code-elimination": "^1.0.12",
+    "srvx": "0.12.5"
   },
-  "keywords": [],
-  "author": "",
-  "license": "All rights reserved",
-  "type": "commonjs"
-}
+  "devDependencies": {
+    "@types/babel__generator": "^7.27.0",
+    "@types/babel__traverse": "^7.28.0",
+    "@types/node": "26.1.1",
+    "typescript": "5.9.3",
+    "vite": "latest"
+  },
+  "peerDependencies": {
+    "@octanejs/remix-router": "0.1.36",
+    "octane": "0.1.40",
+    "vite": "^8.0.16"
+  },
+  "peerDependenciesMeta": {
+    "@octanejs/remix-router": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}

package/src/babel.ts

@@ -0,0 +1,22 @@
+import generatorModule from "@babel/generator"
+import { parse, type ParseResult } from "@babel/parser"
+import type { NodePath } from "@babel/traverse"
+import traverseModule from "@babel/traverse"
+import type * as Babel from "@babel/types"
+
+type DefaultImport<T> = T | { default: T }
+
+function unwrapDefault<T>(value: DefaultImport<T>): T {
+  return (value as { default?: T }).default ?? (value as T)
+}
+
+// Babel's CommonJS packages have different shapes across Node and bundlers.
+const traverse = unwrapDefault(
+  traverseModule as DefaultImport<typeof import("@babel/traverse").default>,
+)
+const generate = unwrapDefault(
+  generatorModule as DefaultImport<typeof import("@babel/generator").default>,
+)
+
+export { generate, parse, traverse }
+export type { Babel, NodePath, ParseResult }

package/src/cli.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import {
+  binary,
+  command,
+  flag,
+  number,
+  option,
+  optional,
+  run,
+  subcommands,
+} from "@alloc/cmd-ts"
+import {
+  buildProject,
+  devProject,
+  loadProject,
+  previewProject,
+} from "./lifecycle.ts"
+
+const routes = command({
+  name: "routes",
+  aliases: ["route"],
+  description: "List the centralized route manifest for the current app.",
+  args: {
+    json: flag({
+      long: "json",
+      description: "Print the manifest as JSON.",
+    }),
+  },
+  async handler({ json }) {
+    const { app } = await loadProject()
+
+    if (json) {
+      console.log(JSON.stringify(app.routes, null, 2))
+      return
+    }
+
+    for (const route of app.routes) {
+      const hydration =
+        typeof route.hydration === "object"
+          ? JSON.stringify(route.hydration)
+          : (route.hydration ?? "default")
+
+      console.log(`${route.path}\t${route.render}\t${hydration}`)
+    }
+  },
+})
+
+const dev = command({
+  name: "dev",
+  description: "Start the development server for every render mode.",
+  args: {
+    port: option({
+      long: "port",
+      type: optional(number),
+      description: "Port for the development server.",
+    }),
+  },
+  handler: ({ port }) => devProject(process.cwd(), port),
+})
+
+const build = command({
+  name: "build",
+  description: "Build client and server bundles, then prerender static routes.",
+  args: {},
+  handler: () => buildProject(),
+})
+
+const preview = command({
+  name: "preview",
+  description: "Serve a production build locally.",
+  args: {},
+  handler: () => previewProject(),
+})
+
+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 },
+})
+
+await run(binary(cli), process.argv)

package/src/fragment-client.ts

@@ -0,0 +1,231 @@
+import type {
+  GeneratedHydration,
+  GeneratedRouteMetadata,
+  HydrationMode,
+  RouteBoundaryKind,
+} from "./index.ts"
+import {
+  stripFlamefrontProtocolParams,
+  withStaticFragmentProtocol,
+} from "./fragment-protocol.ts"
+
+export const staticFragmentProtocol = "flamefront-static-fragment-v1" as const
+
+export interface StaticFragmentBoundary {
+  readonly id: string
+  readonly boundary: string
+  readonly kind: RouteBoundaryKind
+  readonly parent?: string
+  readonly html: string
+}
+
+export interface StaticFragmentArtifact {
+  readonly protocol: typeof staticFragmentProtocol
+  readonly route: string
+  readonly boundary: string
+  readonly html: string
+  readonly routeData: unknown
+  readonly boundaries: readonly StaticFragmentBoundary[]
+  readonly hydration?: HydrationMode
+  readonly status?: number
+}
+
+export interface StaticFragmentLoadOptions {
+  readonly signal?: AbortSignal
+  readonly reload?: boolean
+}
+
+export interface StaticFragmentRoutingOptions {
+  readonly basename?: string
+}
+
+export function shouldHydrateStaticFragment(
+  hydration: HydrationMode | undefined,
+): boolean {
+  return hydration !== "none"
+}
+
+const fragmentCache = new Map<string, Promise<StaticFragmentArtifact>>()
+
+function resolveRouteUrl(input: string | URL): URL {
+  const browserOrigin =
+    typeof location === "undefined" ? undefined : location.origin
+
+  if (!browserOrigin && typeof input === "string" && !URL.canParse(input)) {
+    throw new TypeError(
+      "flamefront static fragments require an absolute URL outside the browser.",
+    )
+  }
+
+  return new URL(input, browserOrigin)
+}
+
+function basenamePath(pathname: string, basename: string): string | null {
+  if (basename === "/") {
+    return pathname
+  }
+
+  if (pathname === basename) {
+    return "/"
+  }
+
+  if (!pathname.startsWith(`${basename}/`)) {
+    return null
+  }
+
+  return pathname.slice(basename.length) || "/"
+}
+
+function fragmentKey(input: string | URL, basename = "/"): string {
+  const url = stripFlamefrontProtocolParams(resolveRouteUrl(input))
+  const pathname = basenamePath(url.pathname, basename) ?? url.pathname
+
+  return `${url.origin}${pathname}`
+}
+
+function abortable<Data>(
+  pending: Promise<Data>,
+  signal: AbortSignal | undefined,
+): Promise<Data> {
+  if (!signal) {
+    return pending
+  }
+
+  if (signal.aborted) {
+    return Promise.reject(signal.reason)
+  }
+
+  return new Promise<Data>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason)
+
+    signal.addEventListener("abort", onAbort, { once: true })
+    pending.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort)
+        resolve(value)
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort)
+        reject(error)
+      },
+    )
+  })
+}
+
+export function isStaticFragmentArtifact(
+  value: unknown,
+): value is StaticFragmentArtifact {
+  if (!value || typeof value !== "object") {
+    return false
+  }
+
+  const artifact = value as Partial<StaticFragmentArtifact>
+
+  return (
+    artifact.protocol === staticFragmentProtocol &&
+    typeof artifact.route === "string" &&
+    typeof artifact.boundary === "string" &&
+    typeof artifact.html === "string" &&
+    Array.isArray(artifact.boundaries)
+  )
+}
+
+export function assertStaticFragmentArtifact(
+  value: unknown,
+): StaticFragmentArtifact {
+  if (!isStaticFragmentArtifact(value)) {
+    throw new Error(
+      "flamefront static fragment response has an invalid protocol.",
+    )
+  }
+
+  return value
+}
+
+export function getStaticFragment(
+  url: string | URL,
+  routing: StaticFragmentRoutingOptions = {},
+): StaticFragmentArtifact | undefined {
+  const pending = fragmentCache.get(fragmentKey(url, routing.basename ?? "/"))
+
+  return pending && "value" in pending
+    ? (
+        pending as Promise<StaticFragmentArtifact> & {
+          value?: StaticFragmentArtifact
+        }
+      ).value
+    : undefined
+}
+
+function rememberArtifact(
+  key: string,
+  pending: Promise<StaticFragmentArtifact>,
+): Promise<StaticFragmentArtifact> {
+  const tracked = pending.then((artifact) => {
+    ;(
+      tracked as Promise<StaticFragmentArtifact> & {
+        value?: StaticFragmentArtifact
+      }
+    ).value = artifact
+    return artifact
+  })
+
+  fragmentCache.set(key, tracked)
+  void tracked.catch(() => {
+    if (fragmentCache.get(key) === tracked) {
+      fragmentCache.delete(key)
+    }
+  })
+  return tracked
+}
+
+export function loadStaticFragment(
+  url: string | URL,
+  routing: StaticFragmentRoutingOptions = {},
+  options: StaticFragmentLoadOptions = {},
+): Promise<StaticFragmentArtifact> {
+  const routeUrl = resolveRouteUrl(url)
+  const key = fragmentKey(routeUrl, routing.basename ?? "/")
+
+  if (options.reload) {
+    fragmentCache.delete(key)
+  }
+
+  const cached = fragmentCache.get(key)
+
+  if (cached) {
+    return abortable(cached, options.signal)
+  }
+
+  const endpoint = withStaticFragmentProtocol(routeUrl)
+  const pending = globalThis
+    .fetch(endpoint, {
+      headers: { Accept: "application/vnd.flamefront.fragment+json" },
+      ...(options.signal ? { signal: options.signal } : {}),
+    })
+    .then(async (response) => {
+      if (!response.ok) {
+        throw new Error(
+          `flamefront static fragment request failed with ${response.status}.`,
+        )
+      }
+
+      return assertStaticFragmentArtifact(await response.json())
+    })
+
+  return abortable(rememberArtifact(key, pending), options.signal)
+}
+
+export async function prefetchStaticFragment(
+  url: string | URL,
+  routing: StaticFragmentRoutingOptions = {},
+  options?: StaticFragmentLoadOptions,
+): Promise<void> {
+  await loadStaticFragment(url, routing, options)
+}
+
+export type {
+  GeneratedHydration,
+  GeneratedRouteMetadata,
+  HydrationMode,
+} from "./index.ts"

package/src/fragment-protocol.ts

@@ -0,0 +1,39 @@
+export const flamefrontFragmentQueryParam = "__flamefront_fragment"
+export const flamefrontShellQueryParam = "__flamefront_shell"
+export const flamefrontFragmentQueryValue = "1"
+
+/** Remove framework-only query parameters before a URL reaches app code. */
+export function stripFlamefrontProtocolParams(input: string | URL): URL {
+  const url = new URL(input, "http://flamefront.local")
+
+  url.searchParams.delete(flamefrontFragmentQueryParam)
+  url.searchParams.delete(flamefrontShellQueryParam)
+  return url
+}
+
+export function isStaticFragmentRequest(input: string | URL): boolean {
+  const url = new URL(input, "http://flamefront.local")
+
+  return (
+    url.searchParams.get(flamefrontFragmentQueryParam) ===
+    flamefrontFragmentQueryValue
+  )
+}
+
+/** Mark a route URL for the static-fragment transport. */
+export function withStaticFragmentProtocol(input: string | URL): URL {
+  const url = stripFlamefrontProtocolParams(input)
+
+  url.searchParams.set(
+    flamefrontFragmentQueryParam,
+    flamefrontFragmentQueryValue,
+  )
+  return url
+}
+
+/** Pass a request to a loader without leaking framework protocol parameters. */
+export function stripFlamefrontProtocolRequest(request: Request): Request {
+  const url = stripFlamefrontProtocolParams(request.url)
+
+  return new Request(url, request)
+}