frappebun 0.0.0

package/src/ssr/handler.ts

@@ -0,0 +1,56 @@
+/**
+ * HTTP handler — matches a request URL against loaded pages, invokes the
+ * page's `getContext()` if present, and returns either a full SSR'd HTML
+ * response (initial page load) or a JSON payload (SPA navigation).
+ */
+
+import { response } from "../response"
+import type { LoadedPage } from "./page-loader"
+import { renderPage } from "./renderer"
+
+export interface PageMatcher {
+  find(pathname: string): LoadedPage | null
+  readonly pages: LoadedPage[]
+}
+
+/** Phase 2 router: pathname equality against a map of static routes. */
+export function createPageMatcher(pages: LoadedPage[]): PageMatcher {
+  const byPath = new Map(pages.map((p) => [p.routePath, p]))
+  return {
+    pages,
+    find: (pathname) => {
+      const normalized = pathname.length > 1 ? pathname.replace(/\/$/, "") : pathname
+      return byPath.get(normalized) ?? null
+    },
+  }
+}
+
+/**
+ * Attempt to handle a request as a page. Returns `null` if no page matches,
+ * so the caller can fall through to API routing / 404.
+ */
+export async function handlePageRequest(
+  req: Request,
+  url: URL,
+  matcher: PageMatcher,
+  opts: { title?: string } = {},
+): Promise<Response | null> {
+  if (req.method !== "GET") return null
+
+  const page = matcher.find(url.pathname)
+  if (!page) return null
+
+  const query = Object.fromEntries(url.searchParams.entries())
+  const contextData = page.getContext ? await page.getContext({ params: {}, query }) : null
+
+  // SPA navigation hint → return JSON only.
+  if (req.headers.get("accept")?.includes("application/json")) {
+    return response.ok(contextData)
+  }
+
+  const html = await renderPage(page, contextData, { title: opts.title })
+  return new Response(html, {
+    status: 200,
+    headers: { "Content-Type": "text/html; charset=utf-8" },
+  })
+}

package/src/ssr/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Server-side rendering — Vue SFC → HTML with server-side data fetching.
+ */
+
+export { loadPages, relPathToRoute } from "./page-loader"
+export type { LoadedPage, GetContextFn, GetContextArgs } from "./page-loader"
+export { renderPage, renderComponent, FRAPPE_CONTEXT_KEY } from "./renderer"
+export type { RenderOptions } from "./renderer"
+export { useContext } from "./use-context"
+export { handlePageRequest, createPageMatcher } from "./handler"
+export type { PageMatcher } from "./handler"

package/src/ssr/page-loader.ts

@@ -0,0 +1,200 @@
+/**
+ * Page loader — discovers `.vue` files under `<moduleDir>/pages/` and
+ * compiles each one into a server-renderable Vue component, plus an
+ * optional server-only `getContext()` function from `<script context>`.
+ *
+ * Phase 2 scope: static routes only (no `[name].vue`).
+ *   pages/index.vue          → /
+ *   pages/about.vue          → /about
+ *   pages/portal/index.vue   → /portal
+ *   pages/portal/faq.vue     → /portal/faq
+ *
+ * Pipeline for each SFC:
+ *   1. parse SFC → descriptor
+ *   2. write `<script context>` content to a cache .ts → import → getContext()
+ *   3. compile `<script setup>` via compileScript (SSR mode)
+ *   4. compile `<template>` via compileTemplate (SSR mode)
+ *   5. write a generated .mjs module combining setup + ssrRender
+ *   6. dynamic import → Component
+ */
+
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { compileScript, compileTemplate, parse as parseSFC } from "@vue/compiler-sfc"
+import type { Component } from "vue"
+
+// ─── Types ────────────────────────────────────────────────
+
+export interface LoadedPage {
+  /** URL path this page is mounted at — e.g. "/", "/portal", "/portal/faq". */
+  routePath: string
+
+  /** Absolute source file path. */
+  sourcePath: string
+
+  /** Compiled SSR Vue component. */
+  component: Component
+
+  /** Server-only data fetcher from `<script context>`, if present. */
+  getContext?: GetContextFn
+}
+
+export type GetContextFn = (args: GetContextArgs) => Promise<unknown> | unknown
+
+export interface GetContextArgs {
+  params: Record<string, string | string[]>
+  query: Record<string, string>
+}
+
+// ─── Public API ───────────────────────────────────────────
+
+/**
+ * Scan the pages directory and load every `.vue` file it contains.
+ */
+export async function loadPages(moduleDir: string): Promise<LoadedPage[]> {
+  const pagesDir = join(moduleDir, "pages")
+  if (!existsSync(pagesDir)) return []
+
+  const cacheDir = join(moduleDir, ".frappe-cache", "pages")
+  mkdirSync(cacheDir, { recursive: true })
+
+  const pages: LoadedPage[] = []
+  for (const relPath of walkVueFiles(pagesDir)) {
+    pages.push(await loadPage(join(pagesDir, relPath), relPath, cacheDir))
+  }
+
+  return pages.sort((a, b) => a.routePath.localeCompare(b.routePath))
+}
+
+/**
+ * Convert a pages-relative path into a URL route path.
+ *   "index.vue"         → "/"
+ *   "about.vue"         → "/about"
+ *   "portal/index.vue"  → "/portal"
+ *   "portal/faq.vue"    → "/portal/faq"
+ */
+export function relPathToRoute(relPath: string): string {
+  const withoutExt = relPath.replace(/\.vue$/, "")
+  const parts = withoutExt.split("/").filter((p) => p !== "index")
+  return parts.length === 0 ? "/" : "/" + parts.join("/")
+}
+
+// ─── Discovery ────────────────────────────────────────────
+
+function* walkVueFiles(root: string, prefix = ""): Generator<string> {
+  for (const entry of readdirSync(root).sort()) {
+    const abs = join(root, entry)
+    const rel = prefix ? `${prefix}/${entry}` : entry
+    if (statSync(abs).isDirectory()) yield* walkVueFiles(abs, rel)
+    else if (entry.endsWith(".vue")) yield rel
+  }
+}
+
+// ─── Per-page compilation ────────────────────────────────
+
+async function loadPage(absPath: string, relPath: string, cacheDir: string): Promise<LoadedPage> {
+  const source = readFileSync(absPath, "utf-8")
+  const { descriptor } = parseSFC(source, { filename: absPath })
+
+  // Hash the source content so edits produce a new cache file path —
+  // Bun caches module imports by path, so a changing id is the cheapest
+  // way to force a re-import.
+  const id = createHash("md5").update(absPath).update(source).digest("hex").slice(0, 10)
+  const baseName = relPath.replace(/[\\/]/g, "__").replace(/\.vue$/, "")
+
+  const getContext = await extractGetContext(descriptor, baseName, id, cacheDir)
+  const component = await compilePage(descriptor, absPath, baseName, id, cacheDir)
+
+  return { routePath: relPathToRoute(relPath), sourcePath: absPath, component, getContext }
+}
+
+// ─── <script context> extraction ──────────────────────────
+
+/**
+ * Detect and extract a `<script context>` block. The SFC parser treats a
+ * bare `<script>` as `descriptor.script`, so we identify it by the
+ * `context` attribute. When found we move it out of the descriptor so it
+ * does not confuse `compileScript` (which otherwise fails when the
+ * context script's `lang` differs from scriptSetup's).
+ */
+async function extractGetContext(
+  // oxlint-disable-next-line typescript/no-explicit-any
+  descriptor: any,
+  baseName: string,
+  id: string,
+  cacheDir: string,
+): Promise<GetContextFn | undefined> {
+  const isContextScript = Boolean(descriptor.script?.attrs?.context)
+  const block = isContextScript
+    ? descriptor.script
+    : descriptor.customBlocks.find(
+        // oxlint-disable-next-line typescript/no-explicit-any
+        (b: any) => b.type === "context" || (b.type === "script" && b.attrs?.context),
+      )
+  if (!block) return undefined
+
+  if (isContextScript) descriptor.script = null
+
+  const file = join(cacheDir, `${baseName}.${id}.context.ts`)
+  writeFileSync(file, block.content)
+  const mod = (await import(file)) as { default?: GetContextFn }
+  return typeof mod.default === "function" ? mod.default : undefined
+}
+
+// ─── SFC → component compilation ──────────────────────────
+
+async function compilePage(
+  // oxlint-disable-next-line typescript/no-explicit-any
+  descriptor: any,
+  absPath: string,
+  baseName: string,
+  id: string,
+  cacheDir: string,
+): Promise<Component> {
+  const hasScriptSetup = Boolean(descriptor.scriptSetup || descriptor.script)
+  const templateSource = descriptor.template?.content ?? ""
+
+  // Compile <script setup> (SSR-friendly). compileScript produces the
+  // component's bindingMetadata — the template compiler needs it to know
+  // which identifiers are setup bindings vs globals.
+  let scriptCode = "const __sfc__ = {}"
+  // oxlint-disable-next-line typescript/no-explicit-any
+  let bindingMetadata: any = undefined
+  if (hasScriptSetup) {
+    const compiled = compileScript(descriptor, {
+      id,
+      inlineTemplate: false,
+      genDefaultAs: "__sfc__",
+    })
+    scriptCode = compiled.content
+    bindingMetadata = compiled.bindings
+  }
+
+  // Compile <template> to an SSR render function.
+  const templateResult = compileTemplate({
+    source: templateSource,
+    filename: absPath,
+    id,
+    ssr: true,
+    ssrCssVars: [],
+    compilerOptions: { bindingMetadata },
+  })
+
+  const moduleSource = [
+    scriptCode,
+    templateResult.code,
+    `__sfc__.ssrRender = ssrRender`,
+    `__sfc__.__file = ${JSON.stringify(absPath)}`,
+    `export default __sfc__`,
+  ].join("\n\n")
+
+  // Write as .ts so Bun can transpile any TypeScript that survived
+  // compileScript (its output preserves TS syntax from lang="ts" blocks).
+  const outFile = join(cacheDir, `${baseName}.${id}.page.ts`)
+  writeFileSync(outFile, moduleSource)
+
+  const mod = (await import(outFile)) as { default: Component }
+  return mod.default
+}

package/src/ssr/renderer.ts

@@ -0,0 +1,94 @@
+/**
+ * SSR renderer — takes a loaded page + its server-side context data and
+ * produces a full HTML document for the first render. The page's reactive
+ * data is embedded as `window.__FRAPPE_CONTEXT__` for future client hydration.
+ */
+
+import { renderToString } from "@vue/server-renderer"
+import { createSSRApp, ref } from "vue"
+import type { Component } from "vue"
+
+import type { LoadedPage } from "./page-loader"
+
+export interface RenderOptions {
+  /** Page title rendered into `<head>`. */
+  title?: string
+  /** Stylesheet URLs to include. */
+  stylesheets?: string[]
+}
+
+/**
+ * Render a single page to a full HTML document.
+ *
+ * The server context data is injected into the root component's `setup()`
+ * via a provide/inject pair that `useContext()` reads from. This keeps
+ * the page component pure — it accepts context through the composable,
+ * not via props.
+ */
+export async function renderPage(
+  page: LoadedPage,
+  contextData: unknown,
+  opts: RenderOptions = {},
+): Promise<string> {
+  const appHtml = await renderComponent(page.component, contextData)
+  return htmlShell({
+    appHtml,
+    contextJson: JSON.stringify(contextData ?? null),
+    title: opts.title ?? "Frappe",
+    stylesheets: opts.stylesheets ?? [],
+  })
+}
+
+/**
+ * Render just the component to an HTML string, with context provided.
+ */
+export async function renderComponent(component: Component, contextData: unknown): Promise<string> {
+  const app = createSSRApp(component)
+  app.provide(FRAPPE_CONTEXT_KEY, ref(contextData))
+  return renderToString(app)
+}
+
+// ─── useContext() composable ──────────────────────────────
+
+/**
+ * Key shared between the renderer (provide) and `useContext()` (inject).
+ * Kept as a plain string so pages don't have to import a Symbol.
+ */
+export const FRAPPE_CONTEXT_KEY = "__frappe_context__"
+
+// ─── HTML shell ───────────────────────────────────────────
+
+interface ShellOptions {
+  appHtml: string
+  contextJson: string
+  title: string
+  stylesheets: string[]
+}
+
+function htmlShell({ appHtml, contextJson, title, stylesheets }: ShellOptions): string {
+  const styleTags = stylesheets
+    .map((href) => `<link rel="stylesheet" href="${escapeHtml(href)}">`)
+    .join("\n    ")
+  return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${escapeHtml(title)}</title>
+    ${styleTags}
+  </head>
+  <body>
+    <div id="app">${appHtml}</div>
+    <script>window.__FRAPPE_CONTEXT__ = ${contextJson};</script>
+  </body>
+</html>
+`
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+}

package/src/ssr/use-context.ts

@@ -0,0 +1,41 @@
+/**
+ * `useContext()` composable — reads the server-side data injected by the
+ * SSR renderer. On the client, falls back to `window.__FRAPPE_CONTEXT__`.
+ *
+ * Page components declare their context shape as a generic type parameter:
+ *
+ *   const { user, invoices } = useContext<{ user: User; invoices: Invoice[] }>()
+ *
+ * During SSR the data is synchronously available. On the client after
+ * hydration, the same data has already been serialized into the HTML.
+ */
+
+import { inject, ref } from "vue"
+import type { Ref } from "vue"
+
+import { FRAPPE_CONTEXT_KEY } from "./renderer"
+
+// oxlint-disable-next-line typescript/no-explicit-any
+type AnyRecord = Record<string, any>
+
+/**
+ * Return the page's server-provided context as a plain object. Destructuring
+ * the result gives you each field as a plain value — reactivity is not
+ * needed for the Phase 2 static-render loop.
+ */
+export function useContext<T extends AnyRecord = AnyRecord>(): T {
+  // SSR: read from the provide/inject chain.
+  const injected = inject<Ref<T> | undefined>(FRAPPE_CONTEXT_KEY, undefined)
+  if (injected) return injected.value
+
+  // Client: read from the embedded global.
+  if (typeof globalThis !== "undefined") {
+    const g = globalThis as { __FRAPPE_CONTEXT__?: T }
+    if (g.__FRAPPE_CONTEXT__) return g.__FRAPPE_CONTEXT__
+  }
+
+  return {} as T
+}
+
+// Re-export a Vue-less no-op ref for modules that need a sentinel.
+export { ref }