flamefront 0.0.0 → 0.1.0

package/LICENSE.md

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Alec Larson
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# Flamefront
+
+Flamefront brings routing, server rendering, and static pages to Octane.
+One route list connects your pages to the server, browser router, and build.
+
+## Why try it?
+
+- **Render each page where it makes sense.** On the server, at build time, or
+  in the browser.
+- **React Router-style loaders.** Load data beside your page component and read
+  it with `useLoaderData`.
+- **Shared layouts.** Keep navigation and shared UI in place as pages change.
+- **Persistent shell state.** Keep players running, uploads progressing, and
+  other shared UI state intact between pages without making the whole app
+  client-rendered.
+- **Control interactivity.** Activate a page immediately, when it becomes
+  visible, or when someone interacts with it.
+- **Markdown routes.** Use Markdown and MDX files as pages.
+
+## One route list
+
+```ts
+import { clientRoute, defineApp, serverRoute, staticRoute } from "flamefront"
+
+export const app = defineApp({
+  shell: "/src/AppShell.tsrx",
+  routes: [
+    serverRoute("/", "/src/HomePage.tsrx"),
+    staticRoute("/docs", "/src/DocsPage.tsrx"),
+    clientRoute("/settings", "/src/SettingsPage.tsrx"),
+  ],
+})
+```
+
+The shell holds shared UI. Each route pairs a URL with an Octane page component
+and chooses how it renders.
+
+## Quickstart
+
+[Try the included app](./docs/getting-started.md): build a static page, inspect
+its generated HTML, and serve it locally. Then [create your own app](./docs/create-app.md).
+
+## Before you try it
+
+Flamefront is an early alpha and requires Node.js 26+. Expect changes before
+1.0. Follow the setup guide for matching packages.
+
+There is no built-in form action or mutation API yet. If your current framework
+already covers your needs, there's no need to switch.
+
+Licensed under [FSL-1.1-MIT](./LICENSE.md).
+
+## Learn more
+
+- [How Flamefront fits](./docs/index.md)
+- [Route rendering and data](./docs/routes.md)
+- [Build and deployment](./docs/deployment.md)
+- [Migrating an existing app](./docs/brownfield-migration.md)

package/bin/ff-loader.mjs

@@ -0,0 +1,18 @@
+import { readFile } from "node:fs/promises"
+import { stripTypeScriptTypes } from "node:module"
+
+const extensions = [".cts", ".mts", ".ts", ".tsx"]
+
+export async function load(url, context, nextLoad) {
+  if (!extensions.some((extension) => url.endsWith(extension))) {
+    return nextLoad(url, context)
+  }
+
+  const source = await readFile(new URL(url), "utf8")
+
+  return {
+    format: "module",
+    shortCircuit: true,
+    source: stripTypeScriptTypes(source, { mode: "strip" }),
+  }
+}

package/bin/ff.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { register } from "node:module"
+
+register("./ff-loader.mjs", import.meta.url)
+await import("../src/cli.ts")

package/package.json

@@ -1,13 +1,89 @@
 {
   "name": "flamefront",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
+  "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": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ff": "./bin/ff.js"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.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": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "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": "^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": "^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.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": "8.3.0",
+    "vitest": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@octanejs/remix-router": "0.1.48",
+    "octane": "0.2.7",
+    "vite": "^8.3.0"
   },
-  "keywords": [],
-  "author": "",
-  "license": "All rights reserved",
-  "type": "commonjs"
+  "peerDependenciesMeta": {
+    "@octanejs/remix-router": {
+      "optional": true
+    }
+  }
 }

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,98 @@
+#!/usr/bin/env node
+
+import { relative } from "node:path"
+import {
+  binary,
+  command,
+  flag,
+  number,
+  option,
+  optional,
+  run,
+  subcommands,
+} from "@alloc/cmd-ts"
+import {
+  buildProject,
+  devProject,
+  loadProject,
+  previewProject,
+} from "./lifecycle.ts"
+import { generateProjectTypes } from "./typegen.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 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, 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.",
+  )
+}