mates-fullstack 1.0.0-beta.1

package/dist/build-prod.js

@@ -0,0 +1,1014 @@
+/**
+ * mates-fullstack — build-prod.ts
+ *
+ * Production bundler using esbuild.
+ * Same tool as dev (build-esbuild.ts) but runs a full bundle pass
+ * with minification, tree-shaking, content-hashed output, and
+ * the RPC stub + server guard plugins.
+ *
+ * Plugins:
+ *   1. rpcStubPlugin     — replaces server/api/ imports with RPC stubs
+ *   2. serverGuardPlugin — build error if server/helpers/ imported from client
+ *   3. emptyCssPlugin    — removes JS-side CSS imports; CSS is linked separately
+ *   4. dedupePlugin      — forces single mates + lit-html instance
+ *
+ * CSS:
+ *   CSS is bundled separately into one stylesheet by buildStyles() and linked
+ *   in the HTML shell. Client JS imports of .css files are compatibility no-ops.
+ *
+ * Output:
+ *   dist/assets/client-[hash].js
+ *   dist/assets/styles-[hash].css
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import * as esbuild from "esbuild";
+import { findMatesPath } from "./project-resolver.js";
+import { getBundlerDefines } from "./env-loader.js";
+import { devWarn } from "./log.js";
+import { INTERNAL_MATES_PREFIX } from "./internal-prefixes.js";
+// ─── Reserved export names (matches rpc-registry.ts) ─────────────────────────
+const RESERVED_NAMES = new Set([
+    "default",
+    "loader",
+    "meta",
+    "layout",
+    "staticPaths",
+    "onConnect",
+    "onDisconnect",
+    "then",
+    "catch",
+    "finally",
+]);
+// ─── Main build function ──────────────────────────────────────────────────────
+/**
+ * Build the client bundle for production using esbuild.
+ * Writes output to dist/assets/.
+ *
+ * @throws Error if the build fails or no client entry is found.
+ */
+export async function buildProduction(options) {
+    const { paths, minify = true, sourcemap = false, dev = false } = options;
+    const devBuild = dev || !minify;
+    if (!paths.clientEntry) {
+        throw new Error("[mates-fullstack] No client entry found.\n" +
+            "Create client/client.ts that calls renderX(App, container).");
+    }
+    // Ensure output directory exists
+    const assetsDir = path.join(paths.outDir, "assets");
+    fs.mkdirSync(assetsDir, { recursive: true });
+    // Remove stale entry/chunk/css files before each build. Production hashes are
+    // content-addressed, but start() reads a manifest; this cleanup keeps the
+    // output easy to inspect and prevents old dev assets from being served.
+    for (const file of fs.readdirSync(assetsDir)) {
+        if (/^(client|chunk)-?.*\.(js|css|map)$/.test(file) ||
+            file === "manifest.json") {
+            try {
+                fs.unlinkSync(path.join(assetsDir, file));
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    // Run esbuild
+    const result = await esbuild.build(createClientBuildOptions({ paths, minify, sourcemap, dev }));
+    return clientBuildResultFromMetafile(result, paths);
+}
+/**
+ * Build the client bundle for development.
+ * Same as production but no minification and inline sourcemaps
+ * so the browser debugger shows original .ts source.
+ */
+export async function buildDev(options) {
+    return buildProduction({
+        ...options,
+        minify: false,
+        // External sourcemaps keep client.js small in bundled dev mode. The browser
+        // fetches the .map file separately on demand. No tradeoff — same debugging
+        // quality, vastly smaller JS file for page load.
+        sourcemap: true,
+        dev: true,
+    });
+}
+/**
+ * Create incremental esbuild contexts for the dev server.
+ *
+ * `esbuild.context().rebuild()` keeps esbuild's parsed module graph warm across
+ * file changes. The production path keeps using one-shot builds so CLI build
+ * output remains deterministic and contexts never leak after completion.
+ */
+export async function createDevBuildContext(paths) {
+    let clientCtx = null;
+    let serverCtx = null;
+    let serverEntriesKey = "";
+    async function ensureClientCtx() {
+        if (clientCtx)
+            return clientCtx;
+        if (!paths.clientEntry) {
+            throw new Error("[mates-fullstack] No client entry found.\n" +
+                "Create client/client.ts that calls renderX(App, container).");
+        }
+        prepareClientAssetsDir(paths);
+        clientCtx = await esbuild.context(createClientBuildOptions({
+            paths,
+            // External sourcemaps keep client.js small. The .map is a separate file
+            // loaded by the browser devtools on demand.
+            minify: false,
+            sourcemap: true,
+            dev: true,
+        }));
+        return clientCtx;
+    }
+    async function ensureContext(forceRecreate = false) {
+        const entryPoints = collectServerRuntimeEntries(paths);
+        const nextKey = JSON.stringify(Object.entries(entryPoints).sort());
+        const serverDir = path.join(paths.outDir, "server");
+        if (forceRecreate || nextKey !== serverEntriesKey) {
+            await serverCtx?.dispose();
+            serverCtx = null;
+            serverEntriesKey = nextKey;
+            fs.rmSync(serverDir, { recursive: true, force: true });
+            fs.mkdirSync(serverDir, { recursive: true });
+        }
+        if (Object.keys(entryPoints).length === 0) {
+            return { ctx: null, result: getServerRuntimeResult(paths) };
+        }
+        if (!serverCtx) {
+            fs.mkdirSync(serverDir, { recursive: true });
+            serverCtx = await esbuild.context(createServerRuntimeBuildOptions(paths, entryPoints));
+        }
+        return { ctx: serverCtx, result: getServerRuntimeResult(paths) };
+    }
+    return {
+        async rebuildClient() {
+            const ctx = await ensureClientCtx();
+            const result = await ctx.rebuild();
+            return clientBuildResultFromMetafile(result, paths);
+        },
+        async rebuildServerRuntime(options = {}) {
+            const { ctx } = await ensureContext(options.forceRecreate ?? false);
+            if (ctx)
+                await ctx.rebuild();
+            return getServerRuntimeResult(paths);
+        },
+        async dispose() {
+            await Promise.all([
+                clientCtx?.dispose() ?? Promise.resolve(),
+                serverCtx?.dispose() ?? Promise.resolve(),
+            ]);
+            clientCtx = null;
+            serverCtx = null;
+        },
+    };
+}
+// ─── Server runtime build (Model B) ────────────────────────────────────────────
+export async function buildServerRuntime(paths) {
+    const serverDir = path.join(paths.outDir, "server");
+    fs.rmSync(serverDir, { recursive: true, force: true });
+    fs.mkdirSync(serverDir, { recursive: true });
+    const entryPoints = collectServerRuntimeEntries(paths);
+    if (Object.keys(entryPoints).length > 0) {
+        await esbuild.build(createServerRuntimeBuildOptions(paths, entryPoints));
+    }
+    return getServerRuntimeResult(paths);
+}
+function prepareClientAssetsDir(paths) {
+    const assetsDir = path.join(paths.outDir, "assets");
+    fs.mkdirSync(assetsDir, { recursive: true });
+    for (const file of fs.readdirSync(assetsDir)) {
+        if (/^(client|chunk)-?.*\.(js|css|map)$/.test(file) ||
+            file === "manifest.json") {
+            try {
+                fs.unlinkSync(path.join(assetsDir, file));
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    return assetsDir;
+}
+function clientBuildResultFromMetafile(result, paths) {
+    const assetsDir = path.join(paths.outDir, "assets");
+    if (!paths.clientEntry) {
+        throw new Error("[mates-fullstack] No client entry found.");
+    }
+    const clientFilename = _findEntryOutput(result, paths.clientEntry, assetsDir);
+    if (!clientFilename) {
+        throw new Error("[mates-fullstack] Client build produced no output file.");
+    }
+    const clientBundlePath = path.join(assetsDir, clientFilename);
+    const cssFilename = _findCssOutput(result, assetsDir);
+    fs.writeFileSync(path.join(assetsDir, "manifest.json"), JSON.stringify({ client: clientFilename, css: cssFilename }, null, 2), "utf-8");
+    _warnBundleSize(clientBundlePath);
+    return { clientBundlePath, clientFilename, cssFilename };
+}
+function createClientBuildOptions(options) {
+    const { paths, minify = true, sourcemap = false, dev = false } = options;
+    const devBuild = dev || !minify;
+    const projectRoot = paths.projectRoot;
+    const apiDir = paths.apiDir ? path.resolve(paths.apiDir) : null;
+    const serverDir = path.join(projectRoot, "server");
+    const matesPath = findMatesPath(projectRoot);
+    const defines = getBundlerDefines(devBuild ? "development" : "production");
+    const assetsDir = path.join(paths.outDir, "assets");
+    if (!paths.clientEntry) {
+        throw new Error("[mates-fullstack] No client entry found.\n" +
+            "Create client/client.ts that calls renderX(App, container).");
+    }
+    return {
+        entryPoints: [paths.clientEntry],
+        outdir: assetsDir,
+        entryNames: devBuild ? "client" : "client-[hash]",
+        chunkNames: devBuild ? "chunk-[name]" : "chunk-[hash]",
+        assetNames: devBuild ? "[name]" : "[name]-[hash]",
+        // File-loader assets are emitted next to the JS in dist/assets, but their
+        // runtime URL must be absolute from the server root. Without publicPath,
+        // esbuild emits "./s-HASH.svg" and <img src> resolves it against the page
+        // URL ("/s-HASH.svg") instead of the static asset route.
+        publicPath: "/assets",
+        format: "esm",
+        platform: "browser",
+        target: ["es2020", "chrome90", "firefox90", "safari14"],
+        bundle: true,
+        splitting: !devBuild,
+        minify,
+        sourcemap,
+        metafile: true,
+        external: ["node:*", "*.node", `${INTERNAL_MATES_PREFIX}/*`],
+        loader: {
+            ".png": "file",
+            ".jpg": "file",
+            ".jpeg": "file",
+            ".gif": "file",
+            ".webp": "file",
+            ".avif": "file",
+            ".ico": "file",
+            ".bmp": "file",
+            ".tiff": "file",
+            ".svg": "file",
+            ".woff": "file",
+            ".woff2": "file",
+            ".ttf": "file",
+            ".otf": "file",
+            ".eot": "file",
+            ".mp4": "file",
+            ".webm": "file",
+            ".ogg": "file",
+            ".mov": "file",
+            ".avi": "file",
+            ".mkv": "file",
+            ".mp3": "file",
+            ".wav": "file",
+            ".flac": "file",
+            ".aac": "file",
+            ".m4a": "file",
+            ".opus": "file",
+            ".pdf": "file",
+            ".doc": "file",
+            ".docx": "file",
+            ".xls": "file",
+            ".xlsx": "file",
+            ".ppt": "file",
+            ".pptx": "file",
+            ".txt": "file",
+            ".csv": "file",
+            ".glb": "file",
+            ".gltf": "file",
+            ".obj": "file",
+            ".fbx": "file",
+            ".wasm": "file",
+            ".json5": "file",
+            ".geojson": "file",
+            ".toml": "file",
+            ".yaml": "file",
+            ".yml": "file",
+            ".zip": "file",
+            ".tar": "file",
+            ".gz": "file",
+        },
+        plugins: [
+            _emptyCssImportPlugin(),
+            _rpcStubPlugin(apiDir, projectRoot),
+            _serverBoundaryPlugin(serverDir, apiDir, projectRoot),
+            _matesFullstackBrowserPlugin(projectRoot),
+            _dedupePlugin(matesPath, projectRoot),
+        ],
+        define: defines,
+        logLevel: "warning",
+    };
+}
+function _emptyCssImportPlugin() {
+    const filter = /\.css$/i;
+    return {
+        name: "mates-empty-css-imports",
+        setup(build) {
+            build.onLoad({ filter }, () => ({
+                contents: "// CSS is bundled into one linked stylesheet by mates-fullstack.\n" +
+                    "export default {};\n",
+                loader: "js",
+            }));
+        },
+    };
+}
+function createServerRuntimeBuildOptions(paths, entryPoints) {
+    return {
+        entryPoints,
+        outdir: path.join(paths.outDir, "server"),
+        outbase: paths.projectRoot,
+        bundle: true,
+        platform: "node",
+        format: "esm",
+        target: "node20",
+        sourcemap: true,
+        packages: "external",
+        external: [
+            "node:*",
+            "*.node",
+            "mates",
+            "lit-html",
+            "mates-fullstack",
+            `${_getOwnPackageName()}`,
+            `${_getOwnPackageName()}/*`,
+        ],
+        plugins: [_ssrRuntimeRpcStubPlugin(paths.apiDir), _assetStubPlugin()],
+        logLevel: "warning",
+    };
+}
+function getServerRuntimeResult(paths) {
+    const serverDir = path.join(paths.outDir, "server");
+    return {
+        serverDir,
+        appFile: fileIfExists(path.join(serverDir, "App.js")),
+        apiDir: dirIfExists(path.join(serverDir, "api")),
+        mainFile: fileIfExists(path.join(serverDir, "main.js")),
+        socketDir: dirIfExists(path.join(serverDir, "socket")),
+    };
+}
+function collectServerRuntimeEntries(paths) {
+    const entries = {};
+    if (paths.appFile)
+        entries.App = paths.appFile;
+    if (paths.mainFile)
+        entries.main = paths.mainFile;
+    addDirEntries(entries, paths.apiDir, "api");
+    addDirEntries(entries, paths.socketDir, "socket");
+    addDirEntries(entries, paths.sharedDir, "shared");
+    return entries;
+}
+function addDirEntries(entries, dir, prefix) {
+    if (!dir || !fs.existsSync(dir))
+        return;
+    for (const file of listRuntimeSourceFiles(dir)) {
+        const rel = path.relative(dir, file).replace(/\.(ts|tsx|js|jsx|mjs)$/, "");
+        entries[path.posix.join(prefix, rel.split(path.sep).join("/"))] = file;
+    }
+}
+function listRuntimeSourceFiles(dir) {
+    const files = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listRuntimeSourceFiles(full));
+            continue;
+        }
+        if (/\.(ts|tsx|js|jsx|mjs)$/.test(entry.name))
+            files.push(full);
+    }
+    return files;
+}
+function fileIfExists(filePath) {
+    return fs.existsSync(filePath) && fs.statSync(filePath).isFile()
+        ? filePath
+        : null;
+}
+function dirIfExists(dirPath) {
+    return fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory()
+        ? dirPath
+        : null;
+}
+// ─── esbuild plugins ──────────────────────────────────────────────────────────
+/**
+ * Ignore stylesheet imports in the Node/SSR server runtime bundle.
+ * CSS is handled separately by buildStyles() and linked in the HTML shell.
+ */
+function _ssrRuntimeRpcStubPlugin(apiDir) {
+    if (!apiDir)
+        return { name: "mates-ssr-runtime-rpc-stub", setup() { } };
+    const normalApiDir = path.resolve(apiDir);
+    const extensions = [
+        "",
+        ".ts",
+        ".js",
+        ".tsx",
+        ".jsx",
+        ".mjs",
+        "/index.ts",
+        "/index.js",
+        "/index.mjs",
+    ];
+    function resolveImport(importer, specifier) {
+        if (!specifier.startsWith("."))
+            return null;
+        const base = path.resolve(path.dirname(importer), specifier);
+        for (const ext of extensions) {
+            const candidate = base + ext;
+            try {
+                if (fs.statSync(candidate).isFile())
+                    return path.resolve(candidate);
+            }
+            catch {
+                /* try next */
+            }
+        }
+        return null;
+    }
+    return {
+        name: "mates-ssr-runtime-rpc-stub",
+        setup(build) {
+            build.onResolve({ filter: /^\.\.?\// }, (args) => {
+                if (!args.importer)
+                    return undefined;
+                const resolved = resolveImport(args.importer, args.path);
+                if (!resolved)
+                    return undefined;
+                if (resolved !== normalApiDir &&
+                    !resolved.startsWith(normalApiDir + path.sep)) {
+                    return undefined;
+                }
+                const importer = path.resolve(args.importer);
+                if (importer.startsWith(normalApiDir + path.sep))
+                    return undefined;
+                return { path: resolved, namespace: "mates-ssr-rpc-stub" };
+            });
+            build.onLoad({ filter: /.*/, namespace: "mates-ssr-rpc-stub" }, (args) => {
+                const source = fs.readFileSync(args.path, "utf-8");
+                const names = _extractExportNames(source).filter((n) => !RESERVED_NAMES.has(n));
+                const lines = [
+                    `import { lookupRpcFn } from ${JSON.stringify(`${_getOwnPackageName()}/internal`)};`,
+                    `import { getSSRContext } from ${JSON.stringify(`${_getOwnPackageName()}/internal`)};`,
+                    "",
+                ];
+                for (const name of names) {
+                    const url = _deriveRuntimeRpcUrl(normalApiDir, args.path, name);
+                    lines.push(`export async function ${name}(payload = {}) {`, `  const entry = lookupRpcFn(${JSON.stringify(url)});`, `  if (!entry) throw new Error(${JSON.stringify(`[mates-fullstack] SSR RPC function not found: ${url}`)});`, `  const ssrCtx = getSSRContext();`, `  const auth = ssrCtx?.auth ?? null;`, `  return entry.fn(payload, { auth });`, `}`, "");
+                }
+                return { contents: lines.join("\n"), loader: "js" };
+            });
+        },
+    };
+}
+function _deriveRuntimeRpcUrl(apiDir, filePath, fnName) {
+    const rel = path.relative(apiDir, filePath);
+    const withoutExt = rel.replace(/\.(ts|js|tsx|jsx|mjs)$/, "");
+    let modulePath = withoutExt.split(path.sep).join("/");
+    if (modulePath.endsWith("/index"))
+        modulePath = modulePath.slice(0, -6);
+    else if (modulePath === "index")
+        modulePath = "";
+    return modulePath ? `/api/${modulePath}/${fnName}` : `/api/${fnName}`;
+}
+function _assetStubPlugin() {
+    return {
+        name: "mates-asset-stub",
+        setup(build) {
+            build.onLoad({
+                filter: /\.(css|svg|png|jpe?g|gif|webp|avif|ico|bmp|tiff|woff2?|ttf|otf|eot|mp4|webm|ogg|mov|avi|mkv|mp3|wav|flac|aac|m4a|opus|pdf|docx?|xlsx?|pptx?|txt|csv|glb|gltf|obj|fbx|wasm|json5|geojson|toml|ya?ml|zip|tar|gz)$/i,
+            }, () => ({
+                contents: "export default {};",
+                loader: "js",
+            }));
+        },
+    };
+}
+/**
+ * mates-fullstack browser plugin.
+ *
+ * Replaces any import of "mates-fullstack" from client code with the
+ * browser-safe subset (errors, redirect helpers, etc.).
+ * This prevents Node.js-specific code (node:fs, node:http, etc.) from
+ * entering the browser bundle.
+ */
+function _getOwnPackageName() {
+    const thisDir = path.dirname(new URL(import.meta.url).pathname);
+    try {
+        const pkgJson = path.resolve(thisDir, "..", "package.json");
+        if (fs.existsSync(pkgJson)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
+            if (pkg.name)
+                return pkg.name;
+        }
+    }
+    catch {
+        /* use default */
+    }
+    return "mates-fullstack";
+}
+function _matesFullstackBrowserPlugin(_projectRoot) {
+    // Resolve the browser.ts path relative to this file (build-prod.ts)
+    const thisDir = path.dirname(new URL(import.meta.url).pathname);
+    const browserFile = path.resolve(thisDir, "browser.js");
+    const browserFileDev = path.resolve(thisDir, "browser.ts");
+    const browserEntry = fs.existsSync(browserFile)
+        ? browserFile
+        : browserFileDev;
+    // Detect own package name from package.json so the filter works
+    // whether installed as "mates-fullstack", etc.
+    const ownName = _getOwnPackageName();
+    // Escape for use in regex
+    const escaped = ownName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const filter = new RegExp(`^${escaped}$`);
+    return {
+        name: "mates-fullstack-browser",
+        setup(build) {
+            build.onResolve({ filter }, () => ({
+                path: browserEntry,
+            }));
+        },
+    };
+}
+/**
+ * RPC stub plugin.
+ *
+ * Intercepts every import of a file inside server/api/.
+ * Replaces the ENTIRE file with a lightweight stub module that
+ * calls __rpcCall() — the real server code never enters the bundle.
+ *
+ * server/api/users.ts  →  import { __rpcCall } from "/_mates/rpc-client.js";
+ *                          export async function getUsers(payload = {}) {
+ *                            return __rpcCall("/api/users/getUsers", payload);
+ *                          }
+ */
+function _rpcStubPlugin(apiDir, projectRoot) {
+    if (!apiDir)
+        return { name: "mates-rpc-stub", setup() { } };
+    // Build a regex that matches absolute paths inside apiDir only.
+    // Escape path separators for regex safety.
+    const escaped = apiDir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const filter = new RegExp(`^${escaped}[/\\\\].+\\.(ts|js|tsx|jsx)$`);
+    return {
+        name: "mates-rpc-stub",
+        setup(build) {
+            build.onLoad({ filter }, (args) => {
+                let source;
+                try {
+                    source = fs.readFileSync(args.path, "utf-8");
+                }
+                catch {
+                    return undefined; // let esbuild handle the error
+                }
+                const stub = _generateRpcStub(source, args.path, apiDir, `${_getOwnPackageName()}/client`);
+                return {
+                    contents: stub,
+                    loader: "js",
+                };
+            });
+        },
+    };
+}
+/**
+ * Server boundary plugin.
+ *
+ * Client code may import server/api/** only; those imports are replaced by RPC
+ * stubs by _rpcStubPlugin. Any other server/** import is a build error.
+ */
+function _serverBoundaryPlugin(serverDir, apiDir, projectRoot) {
+    if (!fs.existsSync(serverDir)) {
+        return { name: "mates-server-boundary", setup() { } };
+    }
+    const extensions = [
+        "",
+        ".ts",
+        ".js",
+        ".tsx",
+        ".jsx",
+        "/index.ts",
+        "/index.js",
+    ];
+    function resolveImport(importer, specifier) {
+        if (!specifier.startsWith("."))
+            return null;
+        const base = path.resolve(path.dirname(importer), specifier);
+        for (const ext of extensions) {
+            const candidate = base + ext;
+            try {
+                if (fs.statSync(candidate).isFile())
+                    return path.resolve(candidate);
+            }
+            catch {
+                /* try next */
+            }
+        }
+        return null;
+    }
+    return {
+        name: "mates-server-boundary",
+        setup(build) {
+            build.onResolve({ filter: /.*/ }, (args) => {
+                if (!args.importer)
+                    return undefined;
+                const resolved = resolveImport(args.importer, args.path);
+                if (!resolved)
+                    return undefined;
+                if (!resolved.startsWith(serverDir + path.sep))
+                    return undefined;
+                if (apiDir &&
+                    (resolved.startsWith(apiDir + path.sep) || resolved === apiDir)) {
+                    return undefined;
+                }
+                return {
+                    errors: [
+                        {
+                            text: `[mates-fullstack] Import blocked: ` +
+                                `"${path.relative(projectRoot, args.importer)}" cannot import ` +
+                                `"${path.relative(projectRoot, resolved)}".\n` +
+                                `Only server/api/** may be imported by client code; it is converted to RPC stubs. ` +
+                                `All other server/** files are server-only.`,
+                        },
+                    ],
+                };
+            });
+        },
+    };
+}
+/**
+ * Dedupe plugin.
+ *
+ * Forces all imports of "mates" and "lit-html" to resolve to the same
+ * single physical file. Without this, if the project has multiple copies
+ * of these packages (e.g. in a monorepo), esbuild may bundle two separate
+ * instances with independent module-level state — breaking the renderer.
+ */
+function _dedupePlugin(matesPath, projectRoot) {
+    const litHtmlDir = path.join(projectRoot, "node_modules", "lit-html");
+    const litHtmlMain = path.join(litHtmlDir, "lit-html.js");
+    return {
+        name: "mates-dedupe",
+        setup(build) {
+            // Dedupe "mates"
+            if (matesPath) {
+                build.onResolve({ filter: /^mates$/ }, () => ({
+                    path: matesPath,
+                }));
+            }
+            // Dedupe "lit-html" bare import
+            if (fs.existsSync(litHtmlMain)) {
+                build.onResolve({ filter: /^lit-html$/ }, () => ({
+                    path: litHtmlMain,
+                }));
+            }
+            // Dedupe "lit-html/directives/*" and other subpaths
+            if (fs.existsSync(litHtmlDir)) {
+                build.onResolve({ filter: /^lit-html\// }, (args) => {
+                    const subpath = args.path.slice("lit-html/".length);
+                    const resolved = path.join(litHtmlDir, subpath);
+                    if (fs.existsSync(resolved))
+                        return { path: resolved };
+                    return undefined;
+                });
+            }
+        },
+    };
+}
+// ─── RPC stub generation ──────────────────────────────────────────────────────
+/**
+ * Generate an RPC stub module for a server/api/ file.
+ * Scans the source for exported async function names (via regex),
+ * filters reserved names, and returns a browser-safe stub.
+ */
+export function generateRpcStub(source, filePath, apiDir) {
+    return _generateRpcStub(source, filePath, apiDir, `${_getOwnPackageName()}/client`);
+}
+function _generateRpcStub(source, filePath, apiDir, clientImport) {
+    const names = _extractExportNames(source);
+    const filtered = names.filter((n) => !RESERVED_NAMES.has(n));
+    if (filtered.length === 0) {
+        return "// No RPC exports found\n";
+    }
+    // Derive module path: users.ts → users, posts/index.ts → posts
+    const rel = path.relative(apiDir, filePath);
+    const modulePath = rel
+        .replace(/\.(ts|js|tsx|jsx)$/, "")
+        .split(path.sep)
+        .join("/")
+        .replace(/\/index$/, "");
+    const stubs = filtered
+        .map((name) => {
+        // Avoid double-slash when modulePath is empty (server/api/index.ts)
+        const url = modulePath ? `/api/${modulePath}/${name}` : `/api/${name}`;
+        return (`export async function ${name}(payload) {\n` +
+            `  return __rpcCall(${JSON.stringify(url)}, payload);\n` +
+            `}`);
+    })
+        .join("\n\n");
+    return `import { __rpcCall } from ${JSON.stringify(clientImport)};\n\n${stubs}\n`;
+}
+/**
+ * Extract exported async function names from TypeScript source.
+ * Regex-based — covers all common patterns without a full AST parse.
+ */
+export function extractExportNames(source) {
+    return _extractExportNames(source);
+}
+function _extractExportNames(source) {
+    const names = [];
+    const seen = new Set();
+    const add = (n) => {
+        if (!seen.has(n)) {
+            seen.add(n);
+            names.push(n);
+        }
+    };
+    let m;
+    // export async function NAME(
+    const fnPat = /^export\s+async\s+function\s+(\w+)\s*\(/gm;
+    while ((m = fnPat.exec(source)) !== null)
+        add(m[1]);
+    // export const NAME = async (
+    // export const NAME = async function(
+    const constPat = /^export\s+const\s+(\w+)\s*=\s*async\s*(?:function\s*)?\(/gm;
+    while ((m = constPat.exec(source)) !== null)
+        add(m[1]);
+    return names;
+}
+let _cssDevState = null;
+/** Clear incremental CSS state — call before a full rebuild / cleanDist. */
+export function clearCssDevState() {
+    _cssDevState = null;
+}
+/**
+ * Patch a single CSS file in the dev bundle without running a full esbuild
+ * build pass.
+ *
+ * Returns the output filename on success, or null when the changed path is
+ * not tracked (e.g. a new file was added) — the caller should fall back to
+ * a full buildStyles().
+ */
+export async function patchCssFile(changedAbsPath) {
+    const state = _cssDevState;
+    if (!state)
+        return null;
+    const abs = path.resolve(changedAbsPath);
+    if (!state.cache.has(abs))
+        return null; // file not in bundle → need full rebuild
+    try {
+        const raw = fs.readFileSync(abs, "utf-8");
+        const result = await esbuild.transform(raw, {
+            loader: "css",
+            minify: true,
+            sourcemap: false,
+        });
+        state.cache.set(abs, result.code);
+    }
+    catch {
+        // Transform error — leave old cached content so the page keeps working.
+        // The browser will show DevTools errors when it tries to apply the styles.
+    }
+    const bundled = state.fileOrder
+        .map((f) => state.cache.get(f) ?? "")
+        .join("\n");
+    fs.writeFileSync(state.outPath, bundled, "utf-8");
+    return state.outFilename;
+}
+/**
+ * Bundle all CSS files found in the project into a single stylesheet.
+ *
+ * Dev:  dist/assets/styles.css        (stable URL for HMR)
+ * Prod: dist/assets/styles-[hash].css (content-hashed)
+ *
+ * Returns the output CSS basename, or null if no style files found.
+ */
+export async function buildStyles(projectRoot, options = {}) {
+    const { minify = false, outDir = path.join(projectRoot, "dist", "assets"), hash = minify, } = options;
+    fs.mkdirSync(outDir, { recursive: true });
+    // Remove stale styles files before writing. This also handles the case where
+    // the last CSS file was deleted during dev HMR.
+    for (const f of fs.readdirSync(outDir)) {
+        if (/^styles.*\.css$/.test(f) || /^styles.*\.css\.map$/.test(f)) {
+            try {
+                fs.unlinkSync(path.join(outDir, f));
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    // Collect styles from the whole project, not only client/.
+    // This supports patterns like importing ../public/style.css from client code
+    // while still emitting a single CSS bundle linked in the HTML shell.
+    const styleFiles = _collectStyleFiles(projectRoot);
+    if (styleFiles.length === 0)
+        return null;
+    // Synthesize an entry that @imports every style file in source order.
+    const entryContents = styleFiles
+        .map((f) => `@import ${JSON.stringify(f)};`)
+        .join("\n");
+    const tempDir = path.join(projectRoot, ".mates-dev");
+    fs.mkdirSync(tempDir, { recursive: true });
+    const tempEntry = path.join(tempDir, "_styles-entry.css");
+    fs.writeFileSync(tempEntry, entryContents, "utf-8");
+    let result;
+    try {
+        result = (await esbuild.build({
+            entryPoints: [tempEntry],
+            outdir: outDir,
+            entryNames: hash ? "styles-[hash]" : "styles",
+            bundle: true,
+            minify,
+            sourcemap: false,
+            metafile: true,
+            logLevel: "warning",
+            publicPath: "/assets",
+            assetNames: hash ? "[name]-[hash]" : "[name]",
+            loader: {
+                ".css": "css",
+                ".png": "file",
+                ".jpg": "file",
+                ".jpeg": "file",
+                ".gif": "file",
+                ".webp": "file",
+                ".avif": "file",
+                ".ico": "file",
+                ".bmp": "file",
+                ".tiff": "file",
+                ".svg": "file",
+                ".woff": "file",
+                ".woff2": "file",
+                ".ttf": "file",
+                ".otf": "file",
+                ".eot": "file",
+            },
+        }));
+    }
+    finally {
+        try {
+            fs.unlinkSync(tempEntry);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    let outFilename = null;
+    for (const outFile of Object.keys(result.metafile.outputs)) {
+        if (outFile.endsWith(".css")) {
+            outFilename = path.basename(outFile);
+            break;
+        }
+    }
+    // Build per-file incremental cache for dev HMR (stable output name only).
+    // Each file is individually transformed so patchCssFile() can swap one entry
+    // and rebuild the bundle by concatenation — no full esbuild pass needed.
+    if (!hash && outFilename) {
+        const cache = new Map();
+        await Promise.all(styleFiles.map(async (f) => {
+            try {
+                const raw = fs.readFileSync(f, "utf-8");
+                const r = await esbuild.transform(raw, {
+                    loader: "css",
+                    minify: true,
+                    sourcemap: false,
+                });
+                cache.set(f, r.code);
+            }
+            catch {
+                cache.set(f, fs.readFileSync(f, "utf-8"));
+            }
+        }));
+        _cssDevState = {
+            fileOrder: styleFiles,
+            cache,
+            outPath: path.join(outDir, outFilename),
+            outFilename,
+        };
+    }
+    else {
+        // Production build — clear any stale dev state.
+        _cssDevState = null;
+    }
+    return outFilename;
+}
+function _collectStyleFiles(dir) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (["node_modules", "dist", ".mates-dev", ".git", "coverage"].includes(entry.name)) {
+                continue;
+            }
+            results.push(..._collectStyleFiles(full));
+        }
+        else if (/\.css$/i.test(entry.name)) {
+            results.push(full);
+        }
+    }
+    return results.sort();
+}
+// ─── Public dir copying ───────────────────────────────────────────────────────
+/**
+ * Recursively copy public/ to outDir.
+ * Used by the production build and SSG commands.
+ */
+export function copyPublicDir(publicDir, outDir) {
+    if (!fs.existsSync(publicDir))
+        return;
+    fs.mkdirSync(outDir, { recursive: true });
+    _copyDirSync(publicDir, outDir);
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+/**
+ * Find the extracted CSS output filename from an esbuild metafile.
+ * Returns just the basename, e.g. "client-abc12345.css", or null if no CSS.
+ *
+ * esbuild automatically extracts CSS imports into a separate .css file
+ * when `loader: { ".css": "css" }` is set and CSS files are imported.
+ */
+function _findCssOutput(result, assetsDir) {
+    for (const outFile of Object.keys(result.metafile.outputs)) {
+        if (!outFile.endsWith(".css"))
+            continue;
+        // Only return the entry-level CSS (not chunk CSS)
+        return path.basename(outFile);
+    }
+    return null;
+}
+/**
+ * Find the entry output filename from an esbuild metafile.
+ * Returns just the basename, e.g. "client-abc12345.js".
+ */
+function _findEntryOutput(result, entryPoint, assetsDir) {
+    const normalEntry = path.resolve(entryPoint);
+    for (const [outFile, meta] of Object.entries(result.metafile.outputs)) {
+        if (!meta.entryPoint)
+            continue;
+        const normalMeta = path.resolve(meta.entryPoint);
+        if (normalMeta === normalEntry) {
+            return path.basename(outFile);
+        }
+    }
+    // Fallback: find the largest .js output (likely the entry)
+    let largest = 0;
+    let largestFile = null;
+    for (const outFile of Object.keys(result.metafile.outputs)) {
+        if (!outFile.endsWith(".js"))
+            continue;
+        const fullPath = path.isAbsolute(outFile)
+            ? outFile
+            : path.join(assetsDir, path.basename(outFile));
+        try {
+            const size = fs.statSync(fullPath).size;
+            if (size > largest) {
+                largest = size;
+                largestFile = path.basename(outFile);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return largestFile;
+}
+function _warnBundleSize(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        const kb = Math.round(stat.size / 1024);
+        if (kb > 500) {
+            devWarn(`Client bundle is ${kb}KB. ` +
+                "Consider code splitting with dynamic imports.");
+        }
+    }
+    catch {
+        /* ignore */
+    }
+}
+function _copyDirSync(src, dest) {
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            fs.mkdirSync(destPath, { recursive: true });
+            _copyDirSync(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+/**
+ * Content hash for cache-busting fallback (SHA-256, first 8 chars).
+ */
+export function contentHash(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return crypto
+            .createHash("sha256")
+            .update(content)
+            .digest("hex")
+            .slice(0, 8);
+    }
+    catch {
+        return Date.now().toString(36);
+    }
+}
+//# sourceMappingURL=build-prod.js.map