flamefront 0.1.1 → 0.1.3

package/README.md

@@ -3,19 +3,30 @@
 Flamefront brings routing, server rendering, and static pages to Octane.
 One route list connects your pages to the server, browser router, and build.
 
+Use only the rendering your project needs. Pre-rendering, server-side rendering
+(SSR), and client-side rendering (CSR) are available as requirements evolve;
+you do not need to use all three to benefit. The same framework can serve
+many or all of your Octane projects, even when each uses a different mode.
+
 ## 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`.
+- **Typed server actions and forms.** Call validated server functions from
+  browser code, or use forms that work without JavaScript and gain pending
+  states and loader refreshes when enhanced. [Add a mutation](./docs/forms-and-mutations.md).
+- **Reuse unchanged static pages between builds.** Cache prerendered content and regenerate the deployment output on each build.
+  [Enable incremental prerendering](./docs/incremental-prerendering.md).
 - **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.
+- **Choose when parts of a page become interactive.** Defer hydration until
+  needed—for example, when content becomes visible or someone interacts with it.
+- **Write pages in Markdown or MDX.** Include them alongside your Octane
+  components in the route list.
 
 ## One route list
 
@@ -37,16 +48,27 @@ 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).
+Create and start an app with Node.js 26 or newer:
+
+```sh
+pnpm create flamefront@latest my-app
+cd my-app
+pnpm dev
+```
+
+See [Create a one-page app](./docs/create-app.md) for the generated files and
+how the server-rendered route works. To evaluate Flamefront without creating a
+project, [try the included app](./docs/getting-started.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.
+Flamefront is an early alpha and requires Node.js 26+. Octane, Vite, and
+`@octanejs/remix-router` are required peer dependencies. Follow the
+[setup guide](./docs/create-app.md) for matching packages. Expect changes before 1.0.
 
-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.
+Flamefront supports [server actions and forms](./docs/forms-and-mutations.md).
+Static-only hosting still needs a server-backed route or an application-owned
+endpoint for writes.
 
 Licensed under [MIT](./LICENSE.md).
 
@@ -54,5 +76,6 @@ Licensed under [MIT](./LICENSE.md).
 
 - [How Flamefront fits](./docs/index.md)
 - [Route rendering and data](./docs/routes.md)
+- [Forms and mutations](./docs/forms-and-mutations.md)
 - [Build and deployment](./docs/deployment.md)
 - [Migrating an existing app](./docs/brownfield-migration.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flamefront",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "description": "Typed centralized route manifests for Octane.",
   "license": "MIT",
@@ -21,6 +21,7 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./action-client": "./src/action-client.ts",
     "./entry": "./src/entry.ts",
     "./fetch": "./src/fetch.ts",
     "./fragment": "./src/fragment.tsx",
@@ -32,6 +33,7 @@
     "./server": "./src/server.ts",
     "./output": "./src/output.ts",
     "./srvx": "./src/srvx.ts",
+    "./prerender": "./src/prerender.ts",
     "./vite": "./src/vite.ts"
   },
   "scripts": {
@@ -54,6 +56,7 @@
     "@babel/types": "^8.0.5",
     "@remix-run/route-pattern": "^0.24.0",
     "babel-dead-code-elimination": "^2.0.0",
+    "devalue": "^5.8.2",
     "satteri": "^0.10.5",
     "srvx": "^1.0.4",
     "vite-plugin-satteri": "^0.3.5"
@@ -80,10 +83,5 @@
     "@octanejs/remix-router": ">=0.1.48",
     "octane": ">=0.2.7",
     "vite": ">=8.3.0"
-  },
-  "peerDependenciesMeta": {
-    "@octanejs/remix-router": {
-      "optional": true
-    }
   }
 }

package/src/action-client.ts

@@ -0,0 +1,187 @@
+import * as devalue from "devalue"
+import { data } from "@octanejs/remix-router"
+import {
+  actionProtocolEnvelope,
+  actionResponseInit,
+  type ActionEnvelope,
+  type ActionFunction,
+} from "./action.ts"
+import {
+  invalidateRouteDataCache,
+  type RouteDataRoutingOptions,
+} from "./route-data-client.ts"
+import { invalidateRouteFragments } from "./fragment-client.ts"
+
+export interface ActionRequestOptions extends RouteDataRoutingOptions {
+  readonly signal?: AbortSignal
+  /** Return router data helpers for page action submissions. */
+  readonly router?: boolean
+}
+
+function resolveOrigin(url: string | URL): URL {
+  const browserOrigin =
+    typeof location === "undefined" ? undefined : location.origin
+
+  if (!browserOrigin && typeof url === "string" && !URL.canParse(url)) {
+    throw new TypeError(
+      "flamefront action requests require an absolute URL outside the browser.",
+    )
+  }
+
+  return new URL(url, browserOrigin)
+}
+
+function actionEndpoint(
+  routing: RouteDataRoutingOptions,
+  origin: string | URL,
+): URL {
+  return new URL(
+    routing.dataPath ?? "/__flamefront/data",
+    resolveOrigin(origin).origin,
+  )
+}
+
+function isRedirect(response: Response): boolean {
+  return response.status >= 300 && response.status < 400
+}
+
+function headersFromEnvelope(envelope: ActionEnvelope): Headers | undefined {
+  return envelope.headers.length > 0
+    ? new Headers(
+        envelope.headers.map(
+          ([name, value]) => [name, value] as [string, string],
+        ),
+      )
+    : undefined
+}
+
+function actionError(envelope: ActionEnvelope): Error {
+  const serialized = envelope.error
+  const error = new Error(
+    serialized?.message ?? "Flamefront action request failed.",
+  )
+
+  error.name = serialized?.name ?? "ActionError"
+  Object.defineProperty(error, "status", {
+    configurable: true,
+    enumerable: true,
+    value: envelope.status,
+  })
+
+  if (serialized?.issues) {
+    Object.defineProperty(error, "issues", {
+      configurable: false,
+      enumerable: true,
+      value: serialized.issues,
+    })
+  }
+
+  return error
+}
+
+async function decodeActionResponse(
+  response: Response,
+  options: ActionRequestOptions,
+): Promise<unknown> {
+  if (isRedirect(response)) {
+    invalidateRouteDataCache()
+    invalidateRouteFragments()
+    throw response
+  }
+
+  const contentType = response.headers.get("Content-Type") ?? ""
+
+  if (
+    !contentType
+      .toLowerCase()
+      .includes("application/vnd.flamefront.action+devalue")
+  ) {
+    if (response.ok) {
+      invalidateRouteDataCache()
+      invalidateRouteFragments()
+    }
+
+    return response
+  }
+
+  let value: unknown
+
+  try {
+    value = devalue.parse(await response.text())
+  } catch (error) {
+    throw new Error(
+      `flamefront action request returned an invalid response (${response.status}).`,
+      { cause: error },
+    )
+  }
+
+  if (!actionProtocolEnvelope(value)) {
+    throw new Error("flamefront action response has an invalid protocol.")
+  }
+
+  const headers = headersFromEnvelope(value)
+  const init = actionResponseInit(value)
+
+  if (value.type === "error") {
+    if (options.router && value.value !== undefined) {
+      throw data(value.value, init)
+    }
+
+    throw actionError(value)
+  }
+
+  if (value.status >= 200 && value.status < 300) {
+    invalidateRouteDataCache()
+    invalidateRouteFragments()
+  }
+
+  if (options.router && (value.status !== 200 || headers)) {
+    return data(value.value, init)
+  }
+
+  return value.value
+}
+
+/** Call a generated action proxy from browser code. */
+export function createActionProxy<
+  Args extends readonly unknown[] = readonly unknown[],
+  Result = unknown,
+>(
+  actionId: string,
+  routing: RouteDataRoutingOptions = {},
+): ActionFunction<Args, Result> {
+  return (async (...args: Args): Promise<Result> => {
+    const endpoint = actionEndpoint(routing, location.href)
+
+    endpoint.searchParams.set("action", actionId)
+    const response = await globalThis.fetch(endpoint, {
+      method: "POST",
+      credentials: "same-origin",
+      redirect: "manual",
+      headers: {
+        "Content-Type": "application/vnd.flamefront.action+devalue",
+        Accept: "application/vnd.flamefront.action+devalue",
+      },
+      body: devalue.stringify(args),
+    })
+
+    return (await decodeActionResponse(response, {})) as Result
+  }) as ActionFunction<Args, Result>
+}
+
+/** Submit a page action request from the generated router action binding. */
+export async function submitRouteAction(
+  { request }: { readonly request: Request },
+  options: ActionRequestOptions = {},
+): Promise<unknown> {
+  const url = new URL(request.url)
+
+  url.searchParams.set("__flamefront_action", "1")
+  const source = request.clone()
+  const response = await globalThis.fetch(new Request(url, source), {
+    redirect: "manual",
+    credentials: "same-origin",
+  })
+
+  return decodeActionResponse(response, { ...options, router: true })
+}

package/src/action-transform.ts

@@ -0,0 +1,258 @@
+import { createHash } from "node:crypto"
+import { stringLiteral } from "@babel/types"
+import { generate, parse, traverse, type Babel } from "./babel.ts"
+import type { NormalizedRoutingOptions } from "./index.ts"
+
+export interface ActionExport {
+  readonly exportedName: string
+  readonly localName: string
+  readonly id: string
+  readonly call: Babel.CallExpression
+}
+
+export interface ActionModuleTransform {
+  readonly code: string
+  readonly map: unknown
+  readonly actions: readonly ActionExport[]
+}
+
+const actionModuleNames = new Set(["flamefront", "flamefront/server"])
+
+function cleanModuleId(id: string): string {
+  return id.split("?", 1)[0].replaceAll("\\", "/")
+}
+
+function exportedName(node: Babel.Identifier | Babel.StringLiteral): string {
+  return node.type === "Identifier" ? node.name : node.value
+}
+
+function unwrapExpression(
+  node: Babel.Expression | null,
+): Babel.Expression | null {
+  let current = node
+
+  while (
+    current &&
+    (current.type === "TSAsExpression" ||
+      current.type === "TSTypeAssertion" ||
+      current.type === "TypeCastExpression")
+  ) {
+    current = current.expression
+  }
+
+  return current
+}
+
+function actionCall(
+  node: Babel.Expression | null | undefined,
+  bindings: ReadonlySet<string>,
+): Babel.CallExpression | undefined {
+  const expression = unwrapExpression(node ?? null)
+
+  if (
+    !expression ||
+    expression.type !== "CallExpression" ||
+    expression.callee.type !== "Identifier" ||
+    !bindings.has(expression.callee.name)
+  ) {
+    return undefined
+  }
+
+  return expression
+}
+
+function actionId(moduleId: string, localName: string): string {
+  const digest = createHash("sha256")
+    .update(`${cleanModuleId(moduleId)}#${localName}`)
+    .digest("hex")
+    .slice(0, 24)
+
+  return `flamefront:action:${digest}`
+}
+
+/** Find named action exports in a module that can be proxied to the browser. */
+export function findActionExports(
+  source: string,
+  id = "action.ts",
+): readonly ActionExport[] {
+  const ast = parse(source, {
+    sourceFilename: id,
+    sourceType: "module",
+    plugins: ["typescript", "jsx"],
+  })
+  const actionBindings = new Set<string>()
+
+  traverse(ast, {
+    ImportDeclaration(path) {
+      if (!actionModuleNames.has(path.node.source.value)) {
+        return
+      }
+
+      for (const specifier of path.node.specifiers) {
+        if (specifier.type !== "ImportSpecifier") {
+          continue
+        }
+
+        const imported = specifier.imported
+        const importedName =
+          imported.type === "Identifier" ? imported.name : imported.value
+
+        if (importedName === "action") {
+          actionBindings.add(specifier.local.name)
+        }
+      }
+    },
+  })
+
+  if (actionBindings.size === 0) {
+    return []
+  }
+
+  const calls = new Map<string, Babel.CallExpression>()
+  const addDeclaration = (declaration: Babel.VariableDeclaration) => {
+    for (const declarator of declaration.declarations) {
+      if (declarator.id.type !== "Identifier") {
+        continue
+      }
+
+      const call = actionCall(declarator.init, actionBindings)
+
+      if (call) {
+        calls.set(declarator.id.name, call)
+      }
+    }
+  }
+
+  for (const statement of ast.program.body) {
+    if (statement.type === "VariableDeclaration") {
+      addDeclaration(statement)
+    } else if (
+      statement.type === "ExportNamedDeclaration" &&
+      statement.declaration?.type === "VariableDeclaration"
+    ) {
+      addDeclaration(statement.declaration)
+    }
+  }
+
+  const exports: ActionExport[] = []
+  const seen = new Set<string>()
+  const addExport = (localName: string, name: string) => {
+    const call = calls.get(localName)
+
+    if (!call || !name || name === "default") {
+      return
+    }
+
+    const key = `${name}\0${localName}`
+
+    if (seen.has(key)) {
+      return
+    }
+
+    seen.add(key)
+    exports.push({
+      exportedName: name,
+      localName,
+      id: actionId(id, localName),
+      call,
+    })
+  }
+
+  for (const statement of ast.program.body) {
+    if (statement.type !== "ExportNamedDeclaration") {
+      continue
+    }
+
+    if (statement.declaration?.type === "VariableDeclaration") {
+      for (const declarator of statement.declaration.declarations) {
+        if (declarator.id.type === "Identifier") {
+          addExport(declarator.id.name, declarator.id.name)
+        }
+      }
+    }
+
+    for (const specifier of statement.specifiers) {
+      if (specifier.type !== "ExportSpecifier") {
+        continue
+      }
+
+      if (specifier.local.type === "Identifier") {
+        addExport(specifier.local.name, exportedName(specifier.exported))
+      }
+    }
+  }
+
+  return exports
+}
+
+/** Attach stable IDs to server-side action calls. */
+export function transformServerActions(
+  source: string,
+  id = "action.ts",
+): ActionModuleTransform | null {
+  const ast = parse(source, {
+    sourceFilename: id,
+    sourceType: "module",
+    plugins: ["typescript", "jsx"],
+  })
+  const actions = findActionExports(source, id)
+
+  if (actions.length === 0) {
+    return null
+  }
+
+  const actionIds = new Map(
+    actions.map((action) => [action.localName, action.id] as const),
+  )
+
+  traverse(ast, {
+    VariableDeclarator(path) {
+      if (path.node.id.type !== "Identifier") {
+        return
+      }
+
+      const id = actionIds.get(path.node.id.name)
+      const call = unwrapExpression(path.node.init ?? null)
+
+      if (!id || !call || call.type !== "CallExpression") {
+        return
+      }
+
+      const first = call.arguments[0]
+
+      if (first?.type === "StringLiteral" && first.value === id) {
+        return
+      }
+
+      call.arguments.unshift(stringLiteral(id))
+    },
+  })
+
+  const generated = generate(ast, {
+    sourceMaps: true,
+    filename: id,
+    sourceFileName: cleanModuleId(id),
+  })
+
+  return { code: generated.code, map: generated.map, actions }
+}
+
+function validExportName(name: string): boolean {
+  return /^[$A-Z_a-z][$\w]*$/.test(name)
+}
+
+/** Generate a browser module containing typed-at-source action proxies. */
+export function generateActionProxyModule(
+  actions: readonly ActionExport[],
+  routing: NormalizedRoutingOptions,
+): string {
+  const exports = actions
+    .filter((action) => validExportName(action.exportedName))
+    .map(
+      (action) =>
+        `export const ${action.exportedName} = createActionProxy(${JSON.stringify(action.id)}, routing);`,
+    )
+    .join("\n")
+
+  return `// Generated by Flamefront.\nimport { createActionProxy } from "flamefront/action-client";\nconst routing = ${JSON.stringify(routing)};\n\n${exports}\n`
+}