@meekojs/meeko 0.0.3 → 0.0.4

package/dist/framework/prerender.js

@@ -0,0 +1,104 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { serializeJson } from "../server.js";
+import { href, matchRoute } from "./router.js";
+import { createFrameworkHandler } from "./server.js";
+import { discoverConfiguredRoutes } from "./config.js";
+function hasParams(id) {
+    return /\[(?:\.\.\.)?[A-Za-z_$][\w$]*\]/.test(id);
+}
+/** Writes only fully resolved, successful HTML responses to the prerender output. */
+export async function prerenderRoutes(options) {
+    const outputRoot = resolve(options.outputRoot);
+    const origin = options.origin ?? "http://meeko.local";
+    const urls = new Map();
+    for (const route of options.routes) {
+        const sidecar = route.sidecar && options.loadRoute ? await options.loadRoute(route.sidecar) : undefined;
+        if (sidecar?.render !== "prerender")
+            continue;
+        const dynamic = hasParams(route.id);
+        const entries = dynamic
+            ? typeof sidecar?.prerenderEntries === "function" ? await sidecar.prerenderEntries() : sidecar?.prerenderEntries
+            : [{}];
+        if (!entries?.length)
+            throw new Error(`Dynamic prerender route ${route.id} requires prerenderEntries`);
+        for (const params of entries) {
+            const pathname = href(options.routes, route.id, { params });
+            if (matchRoute(options.routes, pathname)?.route !== route) {
+                throw new Error(`Prerender URL ${pathname} is shadowed by another route`);
+            }
+            const previous = urls.get(pathname);
+            if (previous)
+                throw new Error(`Duplicate prerender URL ${pathname}: ${previous} and ${route.file}`);
+            urls.set(pathname, route.file);
+        }
+    }
+    const outputs = [];
+    await mkdir(outputRoot, { recursive: true });
+    for (const pathname of urls.keys()) {
+        const request = new Request(new URL(pathname, origin));
+        const response = await options.handler(request);
+        if (response.status !== 200 || !(response.headers.get("content-type") ?? "").includes("text/html")) {
+            throw new Error(`Prerender ${pathname} returned HTTP ${response.status} instead of HTML 200`);
+        }
+        const parts = pathname.split("/").filter(Boolean);
+        const output = resolve(outputRoot, ...parts, "index.html");
+        if (!output.startsWith(outputRoot + sep))
+            throw new Error(`Prerender path escaped output: ${pathname}`);
+        await mkdir(resolve(output, ".."), { recursive: true });
+        const html = await response.text();
+        await writeFile(output, options.transformHtml ? await options.transformHtml(html) : html, "utf8");
+        outputs.push(output);
+    }
+    await writeFile(join(outputRoot, "manifest.json"), serializeJson({ paths: [...urls.keys()] }) + "\n", "utf8");
+    return outputs;
+}
+/** Renders from the production server bundle and client manifest. */
+export async function prerenderProject(projectRoot) {
+    const root = resolve(projectRoot);
+    const manifestFile = resolve(root, ".meeko/output/client/.vite/manifest.json");
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(manifestFile, "utf8"));
+    }
+    catch {
+        throw new Error("Client build manifest is missing; run the client build before prerender");
+    }
+    const entry = manifest["app/entry-client.ts"]?.file;
+    if (!entry)
+        throw new Error("Client build manifest has no app/entry-client.ts entry");
+    const serverBundle = resolve(root, ".meeko/output/server/entry.js");
+    let server;
+    try {
+        server = await import(pathToFileURL(serverBundle).href);
+    }
+    catch {
+        throw new Error("Server build is missing; run the server build before prerender");
+    }
+    if (typeof server.loadPage !== "function" || typeof server.loadRoute !== "function") {
+        throw new Error("Server build does not expose the Meeko prerender loaders");
+    }
+    const routes = await discoverConfiguredRoutes(root);
+    const loadPage = (file) => server.loadPage(root, file);
+    const loadRoute = (file) => server.loadRoute(root, file);
+    const handler = createFrameworkHandler({ routes, loadPage, loadRoute, clientEntry: `/${entry}` });
+    const portable = routes.map((route) => ({
+        id: route.id,
+        file: "/" + fileRelative(root, route.file),
+        layouts: route.layouts.map((file) => "/" + fileRelative(root, file)),
+        ...(route.error ? { error: "/" + fileRelative(root, route.error) } : {}),
+    }));
+    return await prerenderRoutes({
+        routes, handler, loadRoute,
+        outputRoot: resolve(root, ".meeko/output/prerender"),
+        transformHtml: (html) => html.replace("</body>", `<script id="meeko-routes" type="application/json">${serializeJson(portable)}</script></body>`),
+    });
+}
+function fileRelative(root, file) {
+    const absolute = resolve(file);
+    if (!absolute.startsWith(root + sep))
+        throw new Error(`Route file escaped project: ${file}`);
+    return absolute.slice(root.length + 1).replaceAll("\\", "/");
+}
+//# sourceMappingURL=prerender.js.map

package/dist/framework/prerender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prerender.js","sourceRoot":"","sources":["../../src/framework/prerender.ts"],"names":[],"mappings":"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","sourcesContent":["import { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { join, resolve, sep } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport { serializeJson } from \"../server.js\";\nimport { href, matchRoute } from \"./router.js\";\nimport type { RouteRecord } from \"./router.js\";\nimport { createFrameworkHandler } from \"./server.js\";\nimport { discoverConfiguredRoutes } from \"./config.js\";\nimport type { PageModule, PageRoute } from \"./server.js\";\n\nexport interface PrerenderOptions {\n  readonly routes: readonly RouteRecord[];\n  readonly handler: (request: Request) => Promise<Response>;\n  readonly loadRoute?: (file: string) => Promise<PageRoute>;\n  readonly outputRoot: string;\n  readonly origin?: string;\n  readonly transformHtml?: (html: string) => string | Promise<string>;\n}\n\nfunction hasParams(id: string): boolean {\n  return /\\[(?:\\.\\.\\.)?[A-Za-z_$][\\w$]*\\]/.test(id);\n}\n\n/** Writes only fully resolved, successful HTML responses to the prerender output. */\nexport async function prerenderRoutes(options: PrerenderOptions): Promise<string[]> {\n  const outputRoot = resolve(options.outputRoot);\n  const origin = options.origin ?? \"http://meeko.local\";\n  const urls = new Map<string, string>();\n  for (const route of options.routes) {\n    const sidecar = route.sidecar && options.loadRoute ? await options.loadRoute(route.sidecar) : undefined;\n    if (sidecar?.render !== \"prerender\") continue;\n    const dynamic = hasParams(route.id);\n    const entries = dynamic\n      ? typeof sidecar?.prerenderEntries === \"function\" ? await sidecar.prerenderEntries() : sidecar?.prerenderEntries\n      : [{}];\n    if (!entries?.length) throw new Error(`Dynamic prerender route ${route.id} requires prerenderEntries`);\n    for (const params of entries) {\n      const pathname = href(options.routes, route.id, { params });\n      if (matchRoute(options.routes, pathname)?.route !== route) {\n        throw new Error(`Prerender URL ${pathname} is shadowed by another route`);\n      }\n      const previous = urls.get(pathname);\n      if (previous) throw new Error(`Duplicate prerender URL ${pathname}: ${previous} and ${route.file}`);\n      urls.set(pathname, route.file);\n    }\n  }\n  const outputs: string[] = [];\n  await mkdir(outputRoot, { recursive: true });\n  for (const pathname of urls.keys()) {\n    const request = new Request(new URL(pathname, origin));\n    const response = await options.handler(request);\n    if (response.status !== 200 || !(response.headers.get(\"content-type\") ?? \"\").includes(\"text/html\")) {\n      throw new Error(`Prerender ${pathname} returned HTTP ${response.status} instead of HTML 200`);\n    }\n    const parts = pathname.split(\"/\").filter(Boolean);\n    const output = resolve(outputRoot, ...parts, \"index.html\");\n    if (!output.startsWith(outputRoot + sep)) throw new Error(`Prerender path escaped output: ${pathname}`);\n    await mkdir(resolve(output, \"..\"), { recursive: true });\n    const html = await response.text();\n    await writeFile(output, options.transformHtml ? await options.transformHtml(html) : html, \"utf8\");\n    outputs.push(output);\n  }\n  await writeFile(join(outputRoot, \"manifest.json\"), serializeJson({ paths: [...urls.keys()] }) + \"\\n\", \"utf8\");\n  return outputs;\n}\n\n/** Renders from the production server bundle and client manifest. */\nexport async function prerenderProject(projectRoot: string): Promise<string[]> {\n  const root = resolve(projectRoot);\n  const manifestFile = resolve(root, \".meeko/output/client/.vite/manifest.json\");\n  let manifest: Record<string, { file?: string }>;\n  try {\n    manifest = JSON.parse(await readFile(manifestFile, \"utf8\")) as Record<string, { file?: string }>;\n  } catch {\n    throw new Error(\"Client build manifest is missing; run the client build before prerender\");\n  }\n  const entry = manifest[\"app/entry-client.ts\"]?.file;\n  if (!entry) throw new Error(\"Client build manifest has no app/entry-client.ts entry\");\n  const serverBundle = resolve(root, \".meeko/output/server/entry.js\");\n  let server: {\n    loadPage(root: string, file: string): Promise<PageModule>;\n    loadRoute(root: string, file: string): Promise<PageRoute>;\n  };\n  try {\n    server = await import(pathToFileURL(serverBundle).href) as typeof server;\n  } catch {\n    throw new Error(\"Server build is missing; run the server build before prerender\");\n  }\n  if (typeof server.loadPage !== \"function\" || typeof server.loadRoute !== \"function\") {\n    throw new Error(\"Server build does not expose the Meeko prerender loaders\");\n  }\n  const routes = await discoverConfiguredRoutes(root);\n  const loadPage = (file: string) => server.loadPage(root, file);\n  const loadRoute = (file: string) => server.loadRoute(root, file);\n  const handler = createFrameworkHandler({ routes, loadPage, loadRoute, clientEntry: `/${entry}` });\n  const portable = routes.map((route) => ({\n    id: route.id,\n    file: \"/\" + fileRelative(root, route.file),\n    layouts: route.layouts.map((file) => \"/\" + fileRelative(root, file)),\n    ...(route.error ? { error: \"/\" + fileRelative(root, route.error) } : {}),\n  }));\n  return await prerenderRoutes({\n    routes, handler, loadRoute,\n    outputRoot: resolve(root, \".meeko/output/prerender\"),\n    transformHtml: (html) => html.replace(\"</body>\", `<script id=\"meeko-routes\" type=\"application/json\">${serializeJson(portable)}</script></body>`),\n  });\n}\n\nfunction fileRelative(root: string, file: string): string {\n  const absolute = resolve(file);\n  if (!absolute.startsWith(root + sep)) throw new Error(`Route file escaped project: ${file}`);\n  return absolute.slice(root.length + 1).replaceAll(\"\\\\\", \"/\");\n}\n"]}

package/dist/framework/router.d.ts

@@ -0,0 +1,39 @@
+/** A route manifest is shared by the server renderer and browser navigator. */
+export interface RouteRecord {
+    readonly id: string;
+    readonly file: string;
+    readonly layouts: readonly string[];
+    readonly error?: string;
+    readonly sidecar?: string;
+}
+export interface RouteMatch {
+    readonly route: RouteRecord;
+    readonly params: Readonly<Record<string, string>>;
+}
+/** Validates collisions before sorting static routes ahead of parameters. */
+export declare function createRouteManifest(routes: readonly RouteRecord[]): readonly RouteRecord[];
+/** Resolves a URL against the same manifest used for SSR and client navigation. */
+export declare function matchRoute(routes: readonly RouteRecord[], pathname: string): RouteMatch | undefined;
+/** Builds a URL from a manifest route and rejects absent or extra parameters. */
+export declare function href(routes: readonly RouteRecord[], id: string, options?: {
+    params?: Readonly<Record<string, string>>;
+    search?: Readonly<Record<string, string | number | boolean | null | undefined>>;
+}): string;
+export interface NavigationContext {
+    readonly url: URL;
+    readonly match: RouteMatch;
+    readonly signal: AbortSignal;
+    /** Longest prefix shared with the previous route's layout chain. */
+    readonly retainedLayouts: number;
+}
+export interface Navigator {
+    navigate(to: string, options?: {
+        replace?: boolean;
+    }): Promise<boolean>;
+    dispose(): void;
+}
+/**
+ * The host owns actual DOM outlet rendering. Its callback receives layout
+ * identity so it can retain matching layout instances and release exited ones.
+ */
+export declare function createNavigator(routes: readonly RouteRecord[], render: (context: NavigationContext) => Promise<void> | void, browser?: Window): Navigator;

package/dist/framework/router.js

@@ -0,0 +1,173 @@
+function segments(id) {
+    if (!id.startsWith("/"))
+        throw new TypeError(`Route must start with /: ${id}`);
+    return id.split("/").slice(1).filter(Boolean).map((part, index, all) => {
+        if (/^\[\.\.\.[A-Za-z_$][\w$]*\]$/.test(part)) {
+            if (index !== all.length - 1)
+                throw new TypeError(`Catch-all must be final: ${id}`);
+            return { kind: "rest", value: part.slice(4, -1) };
+        }
+        if (/^\[[A-Za-z_$][\w$]*\]$/.test(part))
+            return { kind: "param", value: part.slice(1, -1) };
+        if (part.includes("[") || part.includes("]"))
+            throw new TypeError(`Invalid route segment: ${part}`);
+        return { kind: "static", value: part };
+    });
+}
+function rank(id) {
+    return segments(id).map((part) => part.kind === "static" ? 3 : part.kind === "param" ? 2 : 1);
+}
+function compareRoute(a, b) {
+    const left = rank(a.id);
+    const right = rank(b.id);
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const score = (right[index] ?? 0) - (left[index] ?? 0);
+        if (score)
+            return score;
+    }
+    return a.id.localeCompare(b.id);
+}
+function collisionKey(id) {
+    return segments(id).map((part) => part.kind === "static" ? part.value : part.kind === "param" ? "[]" : "[...]").join("/");
+}
+function decodePart(part) {
+    try {
+        const value = decodeURIComponent(part);
+        return value.includes("/") || value.includes("\\") || value === "." || value === ".." ? undefined : value;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Validates collisions before sorting static routes ahead of parameters. */
+export function createRouteManifest(routes) {
+    const keys = new Map();
+    for (const route of routes) {
+        const key = collisionKey(route.id);
+        const previous = keys.get(key);
+        if (previous)
+            throw new Error(`Route collision: ${previous} and ${route.file} both resolve to ${key || "/"}`);
+        keys.set(key, route.file);
+    }
+    return Object.freeze([...routes].sort(compareRoute));
+}
+/** Resolves a URL against the same manifest used for SSR and client navigation. */
+export function matchRoute(routes, pathname) {
+    if (!pathname.startsWith("/"))
+        return undefined;
+    const raw = pathname.split("/").slice(1).filter(Boolean);
+    const path = raw.map(decodePart);
+    if (path.some((part) => part === undefined))
+        return undefined;
+    for (const route of routes) {
+        const pattern = segments(route.id);
+        const params = {};
+        let index = 0;
+        let matched = true;
+        for (const part of pattern) {
+            if (part.kind === "rest") {
+                if (index === path.length) {
+                    matched = false;
+                    break;
+                }
+                params[part.value] = path.slice(index).join("/");
+                index = path.length;
+                break;
+            }
+            const value = path[index++];
+            if (value === undefined || (part.kind === "static" && part.value !== value)) {
+                matched = false;
+                break;
+            }
+            if (part.kind === "param")
+                params[part.value] = value;
+        }
+        if (matched && index === path.length)
+            return { route, params };
+    }
+    return undefined;
+}
+/** Builds a URL from a manifest route and rejects absent or extra parameters. */
+export function href(routes, id, options = {}) {
+    if (!routes.some((route) => route.id === id))
+        throw new Error(`Unknown route: ${id}`);
+    const params = options.params ?? {};
+    const used = new Set();
+    const path = segments(id).map((part) => {
+        if (part.kind === "static")
+            return encodeURIComponent(part.value);
+        const value = params[part.value];
+        if (!value)
+            throw new Error(`Missing route parameter: ${part.value}`);
+        used.add(part.value);
+        if (part.kind === "rest") {
+            const pieces = value.split("/");
+            if (pieces.some((piece) => !piece || piece === "." || piece === ".."))
+                throw new Error(`Invalid catch-all parameter: ${part.value}`);
+            return pieces.map(encodeURIComponent).join("/");
+        }
+        if (value.includes("/") || value === "." || value === "..")
+            throw new Error(`Invalid route parameter: ${part.value}`);
+        return encodeURIComponent(value);
+    });
+    for (const key of Object.keys(params))
+        if (!used.has(key))
+            throw new Error(`Unknown route parameter: ${key}`);
+    const url = new URL(path.length ? `/${path.join("/")}` : "/", "http://meeko.local");
+    for (const [key, value] of Object.entries(options.search ?? {}))
+        if (value !== null && value !== undefined)
+            url.searchParams.set(key, String(value));
+    return url.pathname + url.search;
+}
+/**
+ * The host owns actual DOM outlet rendering. Its callback receives layout
+ * identity so it can retain matching layout instances and release exited ones.
+ */
+export function createNavigator(routes, render, browser = window) {
+    let current = matchRoute(routes, browser.location.pathname);
+    let pending;
+    let disposed = false;
+    const navigate = async (to, options = {}) => {
+        if (disposed)
+            throw new Error("Navigator disposed");
+        const url = new URL(to, browser.location.href);
+        if (url.origin !== browser.location.origin)
+            throw new TypeError("External navigation is not a Meeko route");
+        const match = matchRoute(routes, url.pathname);
+        if (!match)
+            return false;
+        pending?.abort();
+        const controller = new AbortController();
+        pending = controller;
+        let retainedLayouts = 0;
+        if (current) {
+            while (current.route.layouts[retainedLayouts] === match.route.layouts[retainedLayouts]
+                && retainedLayouts < current.route.layouts.length
+                && retainedLayouts < match.route.layouts.length)
+                retainedLayouts++;
+        }
+        await render({ url, match, signal: controller.signal, retainedLayouts });
+        if (controller.signal.aborted || disposed)
+            return false;
+        if (options.replace)
+            browser.history.replaceState(null, "", url);
+        else
+            browser.history.pushState(null, "", url);
+        current = match;
+        pending = undefined;
+        return true;
+    };
+    const onPop = () => {
+        void navigate(browser.location.href, { replace: true });
+    };
+    browser.addEventListener("popstate", onPop);
+    return {
+        navigate,
+        dispose() {
+            disposed = true;
+            pending?.abort();
+            browser.removeEventListener("popstate", onPop);
+        },
+    };
+}
+//# sourceMappingURL=router.js.map

package/dist/framework/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/framework/router.ts"],"names":[],"mappings":"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","sourcesContent":["/** A route manifest is shared by the server renderer and browser navigator. */\nexport interface RouteRecord {\n  readonly id: string;\n  readonly file: string;\n  readonly layouts: readonly string[];\n  readonly error?: string;\n  readonly sidecar?: string;\n}\n\nexport interface RouteMatch {\n  readonly route: RouteRecord;\n  readonly params: Readonly<Record<string, string>>;\n}\n\ntype Segment = { kind: \"static\" | \"param\" | \"rest\"; value: string };\n\nfunction segments(id: string): Segment[] {\n  if (!id.startsWith(\"/\")) throw new TypeError(`Route must start with /: ${id}`);\n  return id.split(\"/\").slice(1).filter(Boolean).map((part, index, all) => {\n    if (/^\\[\\.\\.\\.[A-Za-z_$][\\w$]*\\]$/.test(part)) {\n      if (index !== all.length - 1) throw new TypeError(`Catch-all must be final: ${id}`);\n      return { kind: \"rest\", value: part.slice(4, -1) };\n    }\n    if (/^\\[[A-Za-z_$][\\w$]*\\]$/.test(part)) return { kind: \"param\", value: part.slice(1, -1) };\n    if (part.includes(\"[\") || part.includes(\"]\")) throw new TypeError(`Invalid route segment: ${part}`);\n    return { kind: \"static\", value: part };\n  });\n}\n\nfunction rank(id: string): number[] {\n  return segments(id).map((part) => part.kind === \"static\" ? 3 : part.kind === \"param\" ? 2 : 1);\n}\n\nfunction compareRoute(a: RouteRecord, b: RouteRecord): number {\n  const left = rank(a.id);\n  const right = rank(b.id);\n  for (let index = 0; index < Math.max(left.length, right.length); index++) {\n    const score = (right[index] ?? 0) - (left[index] ?? 0);\n    if (score) return score;\n  }\n  return a.id.localeCompare(b.id);\n}\n\nfunction collisionKey(id: string): string {\n  return segments(id).map((part) => part.kind === \"static\" ? part.value : part.kind === \"param\" ? \"[]\" : \"[...]\").join(\"/\");\n}\n\nfunction decodePart(part: string): string | undefined {\n  try {\n    const value = decodeURIComponent(part);\n    return value.includes(\"/\") || value.includes(\"\\\\\") || value === \".\" || value === \"..\" ? undefined : value;\n  } catch {\n    return undefined;\n  }\n}\n\n/** Validates collisions before sorting static routes ahead of parameters. */\nexport function createRouteManifest(routes: readonly RouteRecord[]): readonly RouteRecord[] {\n  const keys = new Map<string, string>();\n  for (const route of routes) {\n    const key = collisionKey(route.id);\n    const previous = keys.get(key);\n    if (previous) throw new Error(`Route collision: ${previous} and ${route.file} both resolve to ${key || \"/\"}`);\n    keys.set(key, route.file);\n  }\n  return Object.freeze([...routes].sort(compareRoute));\n}\n\n/** Resolves a URL against the same manifest used for SSR and client navigation. */\nexport function matchRoute(routes: readonly RouteRecord[], pathname: string): RouteMatch | undefined {\n  if (!pathname.startsWith(\"/\")) return undefined;\n  const raw = pathname.split(\"/\").slice(1).filter(Boolean);\n  const path = raw.map(decodePart);\n  if (path.some((part) => part === undefined)) return undefined;\n  for (const route of routes) {\n    const pattern = segments(route.id);\n    const params: Record<string, string> = {};\n    let index = 0;\n    let matched = true;\n    for (const part of pattern) {\n      if (part.kind === \"rest\") {\n        if (index === path.length) { matched = false; break; }\n        params[part.value] = path.slice(index).join(\"/\");\n        index = path.length;\n        break;\n      }\n      const value = path[index++];\n      if (value === undefined || (part.kind === \"static\" && part.value !== value)) { matched = false; break; }\n      if (part.kind === \"param\") params[part.value] = value;\n    }\n    if (matched && index === path.length) return { route, params };\n  }\n  return undefined;\n}\n\n/** Builds a URL from a manifest route and rejects absent or extra parameters. */\nexport function href(routes: readonly RouteRecord[], id: string, options: {\n  params?: Readonly<Record<string, string>>;\n  search?: Readonly<Record<string, string | number | boolean | null | undefined>>;\n} = {}): string {\n  if (!routes.some((route) => route.id === id)) throw new Error(`Unknown route: ${id}`);\n  const params = options.params ?? {};\n  const used = new Set<string>();\n  const path = segments(id).map((part) => {\n    if (part.kind === \"static\") return encodeURIComponent(part.value);\n    const value = params[part.value];\n    if (!value) throw new Error(`Missing route parameter: ${part.value}`);\n    used.add(part.value);\n    if (part.kind === \"rest\") {\n      const pieces = value.split(\"/\");\n      if (pieces.some((piece) => !piece || piece === \".\" || piece === \"..\")) throw new Error(`Invalid catch-all parameter: ${part.value}`);\n      return pieces.map(encodeURIComponent).join(\"/\");\n    }\n    if (value.includes(\"/\") || value === \".\" || value === \"..\") throw new Error(`Invalid route parameter: ${part.value}`);\n    return encodeURIComponent(value);\n  });\n  for (const key of Object.keys(params)) if (!used.has(key)) throw new Error(`Unknown route parameter: ${key}`);\n  const url = new URL(path.length ? `/${path.join(\"/\")}` : \"/\", \"http://meeko.local\");\n  for (const [key, value] of Object.entries(options.search ?? {})) if (value !== null && value !== undefined) url.searchParams.set(key, String(value));\n  return url.pathname + url.search;\n}\n\nexport interface NavigationContext {\n  readonly url: URL;\n  readonly match: RouteMatch;\n  readonly signal: AbortSignal;\n  /** Longest prefix shared with the previous route's layout chain. */\n  readonly retainedLayouts: number;\n}\n\nexport interface Navigator {\n  navigate(to: string, options?: { replace?: boolean }): Promise<boolean>;\n  dispose(): void;\n}\n\n/**\n * The host owns actual DOM outlet rendering. Its callback receives layout\n * identity so it can retain matching layout instances and release exited ones.\n */\nexport function createNavigator(routes: readonly RouteRecord[], render: (context: NavigationContext) => Promise<void> | void, browser: Window = window): Navigator {\n  let current = matchRoute(routes, browser.location.pathname);\n  let pending: AbortController | undefined;\n  let disposed = false;\n  const navigate = async (to: string, options: { replace?: boolean } = {}): Promise<boolean> => {\n    if (disposed) throw new Error(\"Navigator disposed\");\n    const url = new URL(to, browser.location.href);\n    if (url.origin !== browser.location.origin) throw new TypeError(\"External navigation is not a Meeko route\");\n    const match = matchRoute(routes, url.pathname);\n    if (!match) return false;\n    pending?.abort();\n    const controller = new AbortController();\n    pending = controller;\n    let retainedLayouts = 0;\n    if (current) {\n      while (current.route.layouts[retainedLayouts] === match.route.layouts[retainedLayouts]\n        && retainedLayouts < current.route.layouts.length\n        && retainedLayouts < match.route.layouts.length) retainedLayouts++;\n    }\n    await render({ url, match, signal: controller.signal, retainedLayouts });\n    if (controller.signal.aborted || disposed) return false;\n    if (options.replace) browser.history.replaceState(null, \"\", url);\n    else browser.history.pushState(null, \"\", url);\n    current = match;\n    pending = undefined;\n    return true;\n  };\n  const onPop = () => {\n    void navigate(browser.location.href, { replace: true });\n  };\n  browser.addEventListener(\"popstate\", onPop);\n  return {\n    navigate,\n    dispose() {\n      disposed = true;\n      pending?.abort();\n      browser.removeEventListener(\"popstate\", onPop);\n    },\n  };\n}\n"]}

package/dist/framework/server.d.ts

@@ -0,0 +1,51 @@
+import type { RequestContext } from "../framework-server/context.js";
+import type { ServerFetch } from "../framework-server/context.js";
+import type { PageSchema } from "./page.js";
+import { StateStore } from "./state.js";
+import type { RouteRecord } from "./router.js";
+/** Discovers pages once; the returned manifest is safe to serialize for the browser. */
+export declare function discoverRoutes(projectRoot: string): Promise<readonly RouteRecord[]>;
+export interface PageModule {
+    css?: string;
+    renderWithState(props: Record<string, unknown>): {
+        html: string;
+        state: Record<string, unknown>;
+    };
+    renderToString?(props: Record<string, unknown>): string;
+}
+export interface PageRoute {
+    params?: PageSchema;
+    search?: PageSchema;
+    load?: (context: PageRequestContext) => Promise<unknown> | unknown;
+    head?: (context: PageRequestContext & {
+        data: unknown;
+    }) => {
+        title?: string;
+    };
+    render?: "ssr" | "prerender" | "client";
+    prerenderEntries?: readonly Readonly<Record<string, string>>[] | (() => Promise<readonly Readonly<Record<string, string>>[]>);
+}
+export interface PageRequestContext {
+    readonly request: Request;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly search: Readonly<Record<string, unknown>>;
+    readonly searchParams: URLSearchParams;
+    readonly signal: AbortSignal;
+    /** Public state transferred from this request to its browser app instance. */
+    readonly state: StateStore;
+    /** Present when the host supplies a per-request context. */
+    readonly context?: RequestContext;
+}
+export interface FrameworkHandlerOptions {
+    readonly routes: readonly RouteRecord[];
+    readonly loadPage: (file: string) => Promise<PageModule>;
+    readonly loadRoute?: (file: string) => Promise<PageRoute>;
+    readonly createContext?: (request: Request) => RequestContext | Promise<RequestContext>;
+    /** Optional in-process dispatcher for automatic API/RPC calls during SSR. */
+    readonly serverFetch?: ServerFetch;
+    /** Optional host layout renderer; default composition uses <component is="props.outlet"/>. */
+    readonly renderLayout?: (file: string, children: string, context: PageRequestContext) => Promise<string> | string;
+    readonly clientEntry?: string;
+}
+/** Portable Fetch handler. Node adapters can pass their Request directly. */
+export declare function createFrameworkHandler(options: FrameworkHandlerOptions): (request: Request) => Promise<Response>;

package/dist/framework/server.js

@@ -0,0 +1,192 @@
+import { readdir, stat } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { escapeHtml, serializeJson } from "../server.js";
+import { withRequestContext } from "../framework-server/context.js";
+import { PageInputError, pageSearchObject, validatePageInputs } from "./page.js";
+import { StateStore, withStateStore } from "./state.js";
+import { createRouteManifest, matchRoute } from "./router.js";
+function routeId(relativeFile) {
+    const parts = relativeFile.slice(0, -".meeko".length).split(sep);
+    if (parts.at(-1) === "index")
+        parts.pop();
+    const visible = parts.filter((part) => !/^\([^/()]+\)$/.test(part));
+    return visible.length ? `/${visible.join("/")}` : "/";
+}
+/** Discovers pages once; the returned manifest is safe to serialize for the browser. */
+export async function discoverRoutes(projectRoot) {
+    const pagesRoot = resolve(projectRoot, "app", "pages");
+    const files = new Set();
+    async function walk(directory) {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                await walk(path);
+            else if (entry.isFile())
+                files.add(path);
+        }
+    }
+    await walk(pagesRoot);
+    const appShell = resolve(projectRoot, "app", "app.meeko");
+    let hasAppShell = false;
+    try {
+        hasAppShell = (await stat(appShell)).isFile();
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const routes = [];
+    for (const file of files) {
+        if (!file.endsWith(".meeko") || basename(file).startsWith("+"))
+            continue;
+        const directory = dirname(file);
+        const layouts = hasAppShell ? [appShell] : [];
+        let cursor = pagesRoot;
+        const relativeDirectory = relative(pagesRoot, directory);
+        if (files.has(join(cursor, "+layout.meeko")))
+            layouts.push(join(cursor, "+layout.meeko"));
+        if (relativeDirectory)
+            for (const segment of relativeDirectory.split(sep)) {
+                cursor = join(cursor, segment);
+                if (files.has(join(cursor, "+layout.meeko")))
+                    layouts.push(join(cursor, "+layout.meeko"));
+            }
+        let error;
+        let errorCursor = directory;
+        while (errorCursor.startsWith(pagesRoot)) {
+            const candidate = join(errorCursor, "+error.meeko");
+            if (files.has(candidate)) {
+                error = candidate;
+                break;
+            }
+            if (errorCursor === pagesRoot)
+                break;
+            errorCursor = dirname(errorCursor);
+        }
+        const sidecar = file.slice(0, -".meeko".length) + ".route.ts";
+        routes.push({
+            id: routeId(relative(pagesRoot, file)),
+            file,
+            layouts,
+            ...(error ? { error } : {}),
+            ...(files.has(sidecar) ? { sidecar } : {}),
+        });
+    }
+    return createRouteManifest(routes);
+}
+/** Portable Fetch handler. Node adapters can pass their Request directly. */
+export function createFrameworkHandler(options) {
+    return async (request) => {
+        if (request.method !== "GET" && request.method !== "HEAD")
+            return new Response(null, { status: 405, headers: { Allow: "GET, HEAD" } });
+        const url = new URL(request.url);
+        const match = matchRoute(options.routes, url.pathname);
+        if (!match)
+            return new Response("Not Found", { status: 404 });
+        const stateStore = new StateStore();
+        let requestContext;
+        const finish = (response) => {
+            if (!requestContext)
+                return response;
+            const headers = new Headers(response.headers);
+            headers.set("x-request-id", requestContext.requestId);
+            headers.set("x-meeko-csrf-token", requestContext.session.current?.csrfToken ?? "");
+            if (requestContext.session.cookieHeader)
+                headers.append("set-cookie", requestContext.session.cookieHeader);
+            return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+        };
+        try {
+            requestContext = await options.createContext?.(request);
+            if (requestContext && requestContext.request !== request)
+                throw new TypeError("Request context belongs to another request");
+            const render = async () => {
+                const sidecar = match.route.sidecar && options.loadRoute ? await options.loadRoute(match.route.sidecar) : undefined;
+                const validated = await validatePageInputs(sidecar, match.params, pageSearchObject(url.searchParams));
+                const context = {
+                    request, params: validated.params, search: validated.search, searchParams: url.searchParams, signal: request.signal, state: stateStore,
+                    ...(requestContext ? { context: requestContext } : {}),
+                };
+                const data = sidecar?.load ? await sidecar.load(context) : undefined;
+                if (data instanceof Response)
+                    return finish(data);
+                const props = {
+                    params: validated.params,
+                    search: validated.search,
+                    ...(data === undefined ? {} : { data }),
+                };
+                let module = await options.loadPage(match.route.file);
+                const styles = [];
+                if (module.css)
+                    styles.push(module.css);
+                let input = props;
+                let rendered;
+                if (options.renderLayout) {
+                    rendered = withStateStore(stateStore, () => module.renderWithState(input));
+                    for (const layout of [...match.route.layouts].reverse()) {
+                        const layoutModule = await options.loadPage(layout);
+                        if (layoutModule.css)
+                            styles.unshift(layoutModule.css);
+                        rendered = { html: await options.renderLayout(layout, rendered.html, context), state: rendered.state };
+                    }
+                }
+                else {
+                    for (const layout of [...match.route.layouts].reverse()) {
+                        const child = module;
+                        const childInput = input;
+                        const outlet = {
+                            renderWithState: () => child.renderWithState(childInput),
+                            renderToString: () => child.renderToString?.(childInput) ?? child.renderWithState(childInput).html,
+                            hydrateScope: () => { throw new Error("Server outlet cannot hydrate"); },
+                        };
+                        module = await options.loadPage(layout);
+                        if (module.css)
+                            styles.unshift(module.css);
+                        input = { outlet };
+                    }
+                    rendered = withStateStore(stateStore, () => module.renderWithState(input));
+                }
+                const head = sidecar?.head?.({ ...context, data });
+                const title = head?.title ? `<title>${escapeHtml(head.title)}</title>` : "";
+                const styleTags = [...new Set(styles)].map((css) => `<style>${css.replaceAll("<", "\\3C ")}</style>`).join("");
+                const payload = serializeJson({ route: match.route.id, props, state: rendered.state, sharedState: stateStore.snapshot() });
+                if (request.headers.get("accept")?.split(",").some((value) => value.trim().startsWith("application/meeko+json"))) {
+                    return finish(new Response(request.method === "HEAD" ? null : payload, {
+                        status: 200, headers: { "content-type": "application/meeko+json; charset=utf-8", "cache-control": "no-store" },
+                    }));
+                }
+                const script = options.clientEntry ? `<script type="module" src="${escapeHtml(options.clientEntry)}"></script>` : "";
+                const csrfMeta = requestContext?.session.current ? `<meta name="meeko-csrf-token" content="${escapeHtml(requestContext.session.current.csrfToken)}">` : "";
+                const document = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="icon" href="data:,">${csrfMeta}${styleTags}${title}</head><body><div id="app">${rendered.html}</div><script id="meeko-payload" type="application/json">${payload}</script>${script}</body></html>`;
+                return finish(new Response(request.method === "HEAD" ? null : document, {
+                    status: 200, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+                }));
+            };
+            return requestContext ? await withRequestContext(requestContext, options.serverFetch, render) : await render();
+        }
+        catch (error) {
+            if (error instanceof Response)
+                return finish(error);
+            if (error instanceof PageInputError)
+                return finish(new Response(error.code, {
+                    status: 400, headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
+                }));
+            if (match.route.error) {
+                try {
+                    const errorPage = await options.loadPage(match.route.error);
+                    const errorRendered = withStateStore(stateStore, () => errorPage.renderWithState({
+                        status: 500, message: "Internal Server Error",
+                    }));
+                    const document = `<!doctype html><html><head><meta charset="utf-8"><title>Error</title></head><body><div id="app">${errorRendered.html}</div></body></html>`;
+                    return finish(new Response(request.method === "HEAD" ? null : document, {
+                        status: 500, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+                    }));
+                }
+                catch {
+                    // The error route failed; keep private errors out of the response.
+                }
+            }
+            return finish(new Response(request.method === "HEAD" ? null : "Internal Server Error", { status: 500 }));
+        }
+    };
+}
+//# sourceMappingURL=server.js.map