toiljs 0.0.1

package/src/client/match.ts

@@ -0,0 +1,39 @@
+/** Extracted dynamic route parameters, e.g. `{ id: "42" }` for `/blog/:id` matching `/blog/42`. */
+export type RouteParams = Record<string, string>;
+
+/**
+ * Matches a route pattern against a pathname, returning extracted params or `null` if no match.
+ * Pure and runtime-agnostic (used by the router and unit-tested directly).
+ *   matchRoute('/', '/')                  -> {}
+ *   matchRoute('/blog/:id', '/blog/42')   -> { id: '42' }
+ *   matchRoute('/docs/*slug', '/docs/a/b') -> { slug: 'a/b' }   (catch-all)
+ *   matchRoute('/about', '/x')            -> null
+ */
+export function matchRoute(pattern: string, pathname: string): RouteParams | null {
+    const patternSegs = pattern.split('/').filter(Boolean);
+    const pathSegs = pathname.split('/').filter(Boolean);
+
+    const params: RouteParams = {};
+    for (let i = 0; i < patternSegs.length; i++) {
+        const p = patternSegs[i];
+
+        // Catch-all (`*slug`): captures the rest of the path (one or more segments).
+        if (p.startsWith('*')) {
+            const rest = pathSegs.slice(i);
+            if (rest.length === 0) return null;
+            params[p.slice(1)] = rest.map((s) => decodeURIComponent(s)).join('/');
+            return params;
+        }
+
+        if (i >= pathSegs.length) return null;
+        const value = pathSegs[i];
+        if (p.startsWith(':')) {
+            params[p.slice(1)] = decodeURIComponent(value);
+        } else if (p !== value) {
+            return null;
+        }
+    }
+
+    // No catch-all consumed the tail: lengths must match exactly.
+    return patternSegs.length === pathSegs.length ? params : null;
+}

package/src/client/runtime.tsx

@@ -0,0 +1,190 @@
+import {
+    createContext,
+    lazy,
+    Suspense,
+    useContext,
+    useEffect,
+    useState,
+    type ComponentType,
+    type MouseEvent,
+    type ReactNode,
+} from 'react';
+import { createRoot } from 'react-dom/client';
+
+import { matchRoute, type RouteParams } from './match.js';
+
+/** A route entry produced by the compiler: a URL pattern and a lazy loader for its page component. */
+export interface RouteDef {
+    readonly pattern: string;
+    readonly load: () => Promise<{ default: ComponentType }>;
+}
+
+/** Optional root layout loader (wraps every page). */
+export type LayoutLoader =
+    | (() => Promise<{ default: ComponentType<{ children?: ReactNode }> }>)
+    | null;
+
+/** Optional custom not-found (404) page loader, rendered when no route matches. */
+export type NotFoundLoader = (() => Promise<{ default: ComponentType }>) | null;
+
+const listeners = new Set<() => void>();
+
+/** Navigates to `href` without a full page reload (history pushState + re-render). */
+export function navigate(href: string): void {
+    window.history.pushState({}, '', href);
+    for (const listener of listeners) listener();
+}
+
+const ParamsContext = createContext<RouteParams>({});
+
+/** Current dynamic route params, e.g. `{ id }` inside `/blog/:id`. */
+export function useParams(): RouteParams {
+    return useContext(ParamsContext);
+}
+
+/** Returns the imperative `navigate(href)` function. */
+export function useNavigate(): (href: string) => void {
+    return navigate;
+}
+
+/** Subscribes to and returns the current `location.pathname`. */
+export function useLocation(): string {
+    const [pathname, setPathname] = useState<string>(() => window.location.pathname);
+    useEffect(() => {
+        const update = (): void => {
+            setPathname(window.location.pathname);
+        };
+        listeners.add(update);
+        window.addEventListener('popstate', update);
+        return () => {
+            listeners.delete(update);
+            window.removeEventListener('popstate', update);
+        };
+    }, []);
+    return pathname;
+}
+
+/** Client-side navigation link. Falls back to default browser behavior for modified clicks. */
+export function Link(props: { href: string; className?: string; children?: ReactNode }): ReactNode {
+    const { href, className, children } = props;
+    const onClick = (e: MouseEvent): void => {
+        if (
+            e.defaultPrevented ||
+            e.button !== 0 ||
+            e.metaKey ||
+            e.ctrlKey ||
+            e.shiftKey ||
+            e.altKey
+        )
+            return;
+        e.preventDefault();
+        navigate(href);
+    };
+    return (
+        <a
+            href={href}
+            className={className}
+            onClick={onClick}>
+            {children}
+        </a>
+    );
+}
+
+const pageCache = new Map<RouteDef, ComponentType>();
+function pageComponent(route: RouteDef): ComponentType {
+    let component = pageCache.get(route);
+    if (!component) {
+        component = lazy(route.load);
+        pageCache.set(route, component);
+    }
+    return component;
+}
+
+let layoutComponent: ComponentType<{ children?: ReactNode }> | null = null;
+let layoutLoader: LayoutLoader = null;
+function resolveLayout(loader: NonNullable<LayoutLoader>): ComponentType<{ children?: ReactNode }> {
+    if (layoutLoader !== loader || !layoutComponent) {
+        layoutComponent = lazy(loader);
+        layoutLoader = loader;
+    }
+    return layoutComponent;
+}
+
+let notFoundComponent: ComponentType | null = null;
+let notFoundLoader: NotFoundLoader = null;
+function resolveNotFound(loader: NonNullable<NotFoundLoader>): ComponentType {
+    if (notFoundLoader !== loader || !notFoundComponent) {
+        notFoundComponent = lazy(loader);
+        notFoundLoader = loader;
+    }
+    return notFoundComponent;
+}
+
+/** Matches the current location to a route and renders it, optionally wrapped in the root layout. */
+export function Router(props: {
+    routes: RouteDef[];
+    layout?: LayoutLoader;
+    notFound?: NotFoundLoader;
+}): ReactNode {
+    const { routes, layout = null, notFound = null } = props;
+    const pathname = useLocation();
+
+    let matched: RouteDef | undefined;
+    let params: RouteParams = {};
+    for (const route of routes) {
+        const result = matchRoute(route.pattern, pathname);
+        if (result) {
+            matched = route;
+            params = result;
+            break;
+        }
+    }
+
+    let page: ReactNode;
+    if (matched) {
+        const Page = pageComponent(matched);
+        page = (
+            <Suspense fallback={null}>
+                <Page />
+            </Suspense>
+        );
+    } else if (notFound) {
+        const NotFound = resolveNotFound(notFound);
+        page = (
+            <Suspense fallback={null}>
+                <NotFound />
+            </Suspense>
+        );
+    } else {
+        page = <div style={{ padding: 24, fontFamily: 'system-ui' }}>404 — Not found</div>;
+    }
+
+    const withParams = <ParamsContext.Provider value={params}>{page}</ParamsContext.Provider>;
+
+    if (layout) {
+        const Layout = resolveLayout(layout);
+        return (
+            <Suspense fallback={null}>
+                <Layout>{withParams}</Layout>
+            </Suspense>
+        );
+    }
+    return withParams;
+}
+
+/** Mounts the toil client app into `#root`. Called by the generated `.toil/entry.tsx`. */
+export function mount(
+    routes: RouteDef[],
+    layout: LayoutLoader = null,
+    notFound: NotFoundLoader = null,
+): void {
+    const el = document.getElementById('root');
+    if (!el) throw new Error('toil: #root element not found');
+    createRoot(el).render(
+        <Router
+            routes={routes}
+            layout={layout}
+            notFound={notFound}
+        />,
+    );
+}

package/src/compiler/config.ts

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runnerImport, type InlineConfig } from 'vite';
+
+/**
+ * Client-side (TSX/React/Vite) configuration. All fields optional; sensible defaults applied.
+ */
+export interface ClientConfig {
+    /** Client source directory, relative to root. Default `client`. */
+    readonly srcDir?: string;
+    /** Routes directory, relative to `srcDir`. Default `routes`. */
+    readonly routesDir?: string;
+    /** Production output directory, relative to root. Default `dist`. */
+    readonly outDir?: string;
+    /** Public base path. Default `/`. */
+    readonly base?: string;
+    /** Dev server port. Default `3000`. */
+    readonly port?: number;
+    /**
+     * Raw Vite escape hatch, deep-merged over the framework's opinionated config.
+     * This is NOT the client config itself — toil owns the Vite setup; use this only
+     * to override specific Vite options.
+     */
+    readonly vite?: InlineConfig;
+}
+
+/**
+ * Server-side (AssemblyScript → WASM) configuration. Reserved: the compiler does not yet
+ * build the server target via `toil build`; today it is compiled by `toilscript` directly.
+ */
+export interface ServerConfig {
+    /** Server source directory, relative to root. Default `server`. */
+    readonly srcDir?: string;
+    /** Server build output directory, relative to root. Default `build/server`. */
+    readonly outDir?: string;
+}
+
+/**
+ * The `toil.config` schema (Next.js-style). All fields optional; sensible defaults applied.
+ * Client and server are configured in separate sections.
+ */
+export interface ToilConfig {
+    /** Project root. Defaults to the current working directory. */
+    readonly root?: string;
+    /** Client (TSX/React/Vite) configuration. */
+    readonly client?: ClientConfig;
+    /** Server (AssemblyScript/WASM) configuration. */
+    readonly server?: ServerConfig;
+}
+
+/** Fully-resolved config with absolute paths, used internally by the compiler. */
+export interface ResolvedToilConfig {
+    readonly root: string;
+    readonly srcDir: string;
+    readonly clientAbsDir: string;
+    readonly routesAbsDir: string;
+    readonly toilDir: string;
+    readonly outDir: string;
+    readonly base: string;
+    readonly port: number;
+    /** Absolute path to the framework client runtime (`toiljs/client`). */
+    readonly runtimePath: string;
+    readonly vite: InlineConfig;
+}
+
+/** Identity helper for typed config files: `export default defineConfig({ ... })`. */
+export function defineConfig(config: ToilConfig): ToilConfig {
+    return config;
+}
+
+const CONFIG_NAMES = ['toil.config.ts', 'toil.config.mts', 'toil.config.js', 'toil.config.mjs'];
+
+/** Path to the built client runtime (`build/client/index.js`), sibling to `build/compiler`. */
+function resolveRuntimePath(): string {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../client/index.js');
+}
+
+/** Finds and loads `toil.config.*` from `root` (via Vite's bundling loader), then resolves defaults. */
+export async function loadConfig(
+    opts: { root?: string; port?: number } = {},
+): Promise<ResolvedToilConfig> {
+    const root = path.resolve(opts.root ?? process.cwd());
+
+    let user: ToilConfig = {};
+    for (const name of CONFIG_NAMES) {
+        const candidate = path.join(root, name);
+        if (fs.existsSync(candidate)) {
+            // Vite's module runner bundles/transforms the (possibly .ts) config and returns it
+            // typed as our `ToilConfig` — no cast needed.
+            const { module } = await runnerImport<{ default?: ToilConfig }>(candidate);
+            if (module.default) user = module.default;
+            break;
+        }
+    }
+
+    const client = user.client ?? {};
+    const srcDir = client.srcDir ?? 'client';
+    const routesDir = client.routesDir ?? 'routes';
+    const clientAbsDir = path.join(root, srcDir);
+
+    return {
+        root,
+        srcDir,
+        clientAbsDir,
+        routesAbsDir: path.join(clientAbsDir, routesDir),
+        toilDir: path.join(root, '.toil'),
+        outDir: client.outDir ?? 'dist',
+        base: client.base ?? '/',
+        port: opts.port ?? client.port ?? 3000,
+        runtimePath: resolveRuntimePath(),
+        vite: client.vite ?? {},
+    };
+}

package/src/compiler/generate.ts

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { type ResolvedToilConfig } from './config.js';
+import { scanRoutes, type ScannedRoute } from './routes.js';
+
+/** Returns a `./`-prefixed POSIX path from the `.toil` dir to `abs`, for use in generated imports. */
+function relFromToil(cfg: ResolvedToilConfig, abs: string): string {
+    let rel = path.relative(cfg.toilDir, abs).replace(/\\/g, '/');
+    if (!rel.startsWith('.')) rel = './' + rel;
+    return rel;
+}
+
+function findLayout(cfg: ResolvedToilConfig): string | undefined {
+    return ['layout.tsx', 'layout.jsx']
+        .map((name) => path.join(cfg.clientAbsDir, name))
+        .find((p) => fs.existsSync(p));
+}
+
+/** Finds an optional custom not-found page at `client/404.{tsx,jsx}`. */
+function findNotFound(cfg: ResolvedToilConfig): string | undefined {
+    return ['404.tsx', '404.jsx']
+        .map((name) => path.join(cfg.clientAbsDir, name))
+        .find((p) => fs.existsSync(p));
+}
+
+/**
+ * Generates the `.toil/` working dir (routes table, mount entry, HTML) and returns the scanned
+ * routes. Called before every dev/build and on route add/remove during dev.
+ */
+export function generate(cfg: ResolvedToilConfig): ScannedRoute[] {
+    const routes = scanRoutes(cfg.routesAbsDir);
+    fs.mkdirSync(cfg.toilDir, { recursive: true });
+
+    const layoutFile = findLayout(cfg);
+    const notFoundFile = findNotFound(cfg);
+    const routesSrc =
+        `// AUTO-GENERATED by toil — do not edit.\n` +
+        `import type { RouteDef, LayoutLoader, NotFoundLoader } from 'toiljs/client';\n\n` +
+        `export const routes: RouteDef[] = [\n` +
+        routes
+            .map(
+                (r) =>
+                    `  { pattern: ${JSON.stringify(r.pattern)}, load: () => import(${JSON.stringify(relFromToil(cfg, r.file))}) },`,
+            )
+            .join('\n') +
+        `\n];\n\n` +
+        `export const layout: LayoutLoader = ${layoutFile ? `() => import(${JSON.stringify(relFromToil(cfg, layoutFile))})` : 'null'};\n` +
+        `export const notFound: NotFoundLoader = ${notFoundFile ? `() => import(${JSON.stringify(relFromToil(cfg, notFoundFile))})` : 'null'};\n`;
+    fs.writeFileSync(path.join(cfg.toilDir, 'routes.ts'), routesSrc);
+
+    const entrySrc =
+        `// AUTO-GENERATED by toil — do not edit.\n` +
+        `import { mount } from 'toiljs/client';\n` +
+        `import { BinaryWriter, BinaryReader, FastMap, FastSet } from 'toiljs/io';\n` +
+        `import { routes, layout, notFound } from './routes';\n\n` +
+        `// Expose toiljs IO as native globals (typed via ./toil-env.d.ts).\n` +
+        `Object.assign(globalThis, { BinaryWriter, BinaryReader, FastMap, FastSet });\n\n` +
+        `mount(routes, layout, notFound);\n`;
+    fs.writeFileSync(path.join(cfg.toilDir, 'entry.tsx'), entrySrc);
+
+    // Ambient global types so `new BinaryWriter()` etc. resolve in the IDE without an import.
+    // Written at the project root (not inside `.toil`) because TypeScript's `include` globs skip
+    // dot-directories — same reason Next.js keeps `next-env.d.ts` at the root. The consumer's
+    // tsconfig lists `toil-env.d.ts` in `include`.
+    const envSrc =
+        `// AUTO-GENERATED by toil — do not edit.\n` +
+        `import type {\n` +
+        `    BinaryWriter as ToilBinaryWriter,\n` +
+        `    BinaryReader as ToilBinaryReader,\n` +
+        `    FastMap as ToilFastMap,\n` +
+        `    FastSet as ToilFastSet,\n` +
+        `} from 'toiljs/io';\n\n` +
+        `declare global {\n` +
+        `    const BinaryWriter: typeof ToilBinaryWriter;\n` +
+        `    const BinaryReader: typeof ToilBinaryReader;\n` +
+        `    const FastMap: typeof ToilFastMap;\n` +
+        `    const FastSet: typeof ToilFastSet;\n` +
+        `}\n\n` +
+        `export {};\n`;
+    fs.writeFileSync(path.join(cfg.root, 'toil-env.d.ts'), envSrc);
+
+    const htmlSrc =
+        `<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n` +
+        `    <meta name="viewport" content="width=device-width, initial-scale=1" />\n` +
+        `    <title>Toil App</title>\n  </head>\n  <body>\n    <div id="root"></div>\n` +
+        `    <script type="module" src="./entry.tsx"></script>\n  </body>\n</html>\n`;
+    fs.writeFileSync(path.join(cfg.toilDir, 'index.html'), htmlSrc);
+
+    return routes;
+}

package/src/compiler/index.ts

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { build as viteBuild, createServer, type ViteDevServer } from 'vite';
+import { startBackend, type RunningBackend } from 'toiljs/backend';
+
+import { loadConfig } from './config.js';
+import { generate } from './generate.js';
+import { createViteConfig } from './vite.js';
+
+export interface ToilCommandOptions {
+    readonly root?: string;
+    readonly port?: number;
+}
+
+/** Starts the Vite dev server (HMR + transforms) for the client app. Returns the running server. */
+export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer> {
+    const cfg = await loadConfig(opts);
+    generate(cfg);
+    const server = await createServer(createViteConfig(cfg));
+    await server.listen();
+    server.printUrls();
+    return server;
+}
+
+/** Produces an optimized production SPA bundle in the configured `outDir`. */
+export async function build(opts: ToilCommandOptions = {}): Promise<void> {
+    const cfg = await loadConfig(opts);
+    generate(cfg);
+    await viteBuild(createViteConfig(cfg));
+}
+
+/**
+ * Self-hosts the built client over the high-performance hyper-express backend (uWebSockets.js),
+ * serving the configured `outDir` with an SPA fallback plus a WebSocket channel. Requires a prior
+ * `build`. Returns the running backend.
+ */
+export async function start(opts: ToilCommandOptions = {}): Promise<RunningBackend> {
+    const cfg = await loadConfig(opts);
+    const outDir = path.resolve(cfg.root, cfg.outDir);
+    if (!fs.existsSync(path.join(outDir, 'index.html'))) {
+        throw new Error(`No build found in ${outDir}. Run \`toiljs build\` first.`);
+    }
+    return startBackend({ root: outDir, port: cfg.port });
+}
+
+export { defineConfig } from './config.js';
+export type { ToilConfig } from './config.js';
+export type { RunningBackend, BackendOptions } from 'toiljs/backend';

package/src/compiler/plugin.ts

@@ -0,0 +1,26 @@
+import { type Plugin } from 'vite';
+
+import { type ResolvedToilConfig } from './config.js';
+import { generate } from './generate.js';
+
+/**
+ * Vite plugin that keeps the generated route table in sync during dev: when a route file is
+ * added or removed, it regenerates `.toil/routes.ts` and triggers a full reload. Editing a
+ * route file's contents hot-reloads through `@vitejs/plugin-react` as usual.
+ */
+export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
+    return {
+        name: 'toil',
+        configureServer(server) {
+            const onChange = (file: string): void => {
+                if (file.replace(/\\/g, '/').startsWith(cfg.routesAbsDir.replace(/\\/g, '/'))) {
+                    generate(cfg);
+                    server.ws.send({ type: 'full-reload' });
+                }
+            };
+            server.watcher.add(cfg.routesAbsDir);
+            server.watcher.on('add', onChange);
+            server.watcher.on('unlink', onChange);
+        },
+    };
+}

package/src/compiler/routes.ts

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** A discovered route: the source file and the URL pattern it serves. */
+export interface ScannedRoute {
+    readonly file: string;
+    readonly pattern: string;
+}
+
+const ROUTE_EXT = /\.(tsx|jsx)$/;
+
+/**
+ * Derives a route pattern from a route file path (relative to the routes dir).
+ *   index.tsx          -> /
+ *   about.tsx          -> /about
+ *   blog/index.tsx     -> /blog
+ *   blog/[id].tsx      -> /blog/:id
+ *   docs/[...slug].tsx -> /docs/*slug   (catch-all)
+ */
+export function filePathToRoute(relPath: string): string {
+    const withoutExt = relPath.replace(/\\/g, '/').replace(ROUTE_EXT, '');
+    const segments = withoutExt.split('/').filter(Boolean);
+    const out: string[] = [];
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        if (segment === 'index' && i === segments.length - 1) continue;
+        out.push(
+            segment
+                .replace(/^\[\.\.\.(.+)\]$/, '*$1') // catch-all [...slug] -> *slug
+                .replace(/^\[(.+)\]$/, ':$1'), // dynamic [id] -> :id
+        );
+    }
+    return '/' + out.join('/');
+}
+
+/**
+ * Ranks a pattern so more specific routes match first: static segments beat dynamic (`:x`),
+ * which beat catch-all (`*x`); deeper routes beat shallower ones.
+ */
+function specificity(pattern: string): number {
+    const segments = pattern.split('/').filter(Boolean);
+    let score = segments.length * 10;
+    for (const segment of segments) {
+        if (segment.startsWith('*')) score -= 5; // catch-all: lowest
+        else if (!segment.startsWith(':')) score += 5; // static: highest
+    }
+    return score;
+}
+
+/** Recursively scans `routesDir` for `.tsx`/`.jsx` files, returning routes sorted by specificity. */
+export function scanRoutes(routesDir: string): ScannedRoute[] {
+    if (!fs.existsSync(routesDir)) return [];
+    const found: ScannedRoute[] = [];
+    const walk = (dir: string): void => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            } else if (ROUTE_EXT.test(entry.name)) {
+                found.push({
+                    file: full,
+                    pattern: filePathToRoute(path.relative(routesDir, full)),
+                });
+            }
+        }
+    };
+    walk(routesDir);
+    found.sort((a, b) => specificity(b.pattern) - specificity(a.pattern));
+    return found;
+}

package/src/compiler/vite.ts

@@ -0,0 +1,90 @@
+import path from 'node:path';
+
+import react from '@vitejs/plugin-react';
+import { nodePolyfills } from 'vite-plugin-node-polyfills';
+import { mergeConfig, type InlineConfig } from 'vite';
+
+import { type ResolvedToilConfig } from './config.js';
+import { toilPlugin } from './plugin.js';
+
+/** Image extensions routed to `images/` in the build output. */
+const IMAGE_EXT = /^(png|jpe?g|svg|gif|tiff|bmp|ico|webp|avif)$/i;
+/** Font extensions routed to `fonts/`. */
+const FONT_EXT = /^(woff|woff2|eot|ttf|otf)$/i;
+
+/** Routes a built asset to a typed sub-folder (`images/`, `fonts/`, `css/`, else `assets/`). */
+function assetFileName(name: string): string {
+    const ext = name.split('.').pop() ?? '';
+    if (IMAGE_EXT.test(ext)) return 'images/[name][extname]';
+    if (FONT_EXT.test(ext)) return 'fonts/[name][extname]';
+    if (/^css$/i.test(ext)) return 'css/[name][extname]';
+    return 'assets/[name][extname]';
+}
+
+/** Splits React's runtime into its own long-lived chunk for better caching. */
+function manualChunks(id: string): string | undefined {
+    if (!id.includes('node_modules')) return undefined;
+    if (
+        id.includes('node_modules/react-dom') ||
+        id.includes('node_modules/react/') ||
+        id.includes('node_modules/scheduler')
+    ) {
+        return 'react';
+    }
+    return undefined;
+}
+
+/**
+ * Builds the framework-owned Vite config. Vite's `root` is the generated `.toil` dir so its
+ * `index.html` emits at the output root (assets resolve correctly); `fs.allow` opens the
+ * project (for `client/`) and the framework runtime. The opinionated default — Node polyfills
+ * (Buffer/global/process), React plugin, toil route plugin, typed asset folders, React chunk
+ * splitting and tuned build options — is applied here; `toiljs/client` is aliased to the
+ * runtime, and the user's `client.vite` overrides deep-merge on top.
+ */
+export function createViteConfig(cfg: ResolvedToilConfig): InlineConfig {
+    // .../build/client/index.js -> framework package root (covers build/ + node_modules in dev)
+    const frameworkRoot = path.resolve(path.dirname(cfg.runtimePath), '..', '..');
+
+    const base: InlineConfig = {
+        root: cfg.toilDir,
+        base: cfg.base,
+        configFile: false,
+        plugins: [
+            nodePolyfills({ globals: { Buffer: true, global: true, process: true } }),
+            react(),
+            toilPlugin(cfg),
+        ],
+        resolve: {
+            alias: {
+                'toiljs/client': cfg.runtimePath,
+            },
+            dedupe: ['react', 'react-dom'],
+        },
+        server: {
+            port: cfg.port,
+            fs: { allow: [cfg.root, frameworkRoot] },
+        },
+        build: {
+            outDir: path.resolve(cfg.root, cfg.outDir),
+            emptyOutDir: true,
+            target: 'es2020',
+            modulePreload: false,
+            cssCodeSplit: false,
+            assetsInlineLimit: 10000,
+            chunkSizeWarningLimit: 3000,
+            commonjsOptions: {
+                strictRequires: true,
+                transformMixedEsModules: true,
+            },
+            rollupOptions: {
+                output: {
+                    chunkFileNames: 'assets/[name]-[hash].js',
+                    assetFileNames: (assetInfo) => assetFileName(assetInfo.names[0] ?? ''),
+                    manualChunks,
+                },
+            },
+        },
+    };
+    return mergeConfig(base, cfg.vite);
+}