@fluixi/start 0.1.0-alpha.43

package/dist/commands/prerender.js

@@ -0,0 +1,78 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { resolve, join, dirname } from 'node:path';
+import { resolveConfig } from '../config.js';
+import { createProdHandler } from '../adapter.js';
+import { step, done, c } from '../ui.js';
+// dist/client path for a route url: '/' → index.html, '/about' → about/index.html
+export function htmlPath(url) {
+    const clean = url.split(/[?#]/)[0].replace(/\/+$/, '');
+    return clean === '' ? 'index.html' : `${clean.replace(/^\//, '')}/index.html`;
+}
+// internal links from rendered HTML — skip files (.js/.css/…), anchors, queries, external
+export function extractLinks(html) {
+    const out = new Set();
+    for (const m of html.matchAll(/href=["'](\/[^"'#?]*)["']/g)) {
+        const href = m[1];
+        if (/\.[a-z0-9]+$/i.test(href))
+            continue;
+        out.add(href.replace(/\/+$/, '') || '/');
+    }
+    return [...out];
+}
+const norm = (u) => {
+    const p = (u.startsWith('/') ? u : '/' + u).replace(/\/+$/, '');
+    return p || '/';
+};
+/**
+ * Render routes to static HTML in dist/client, via the real prod handler — so each page is
+ * byte-identical to what `fluixi start` would serve (assets, __FX_DATA__, hydration), it just
+ * lives on disk. Seeds from `prerender.routes` (default `/`) and, when `crawl`, follows internal
+ * links. Returns the written route paths.
+ */
+export async function prerender(config = {}) {
+    const cfg = resolveConfig(config);
+    if (!cfg.prerender)
+        return [];
+    if (!cfg.ssr) {
+        process.stdout.write(`  ${c.yellow('!')} prerender needs ssr:true — skipped\n`);
+        return [];
+    }
+    step('prerender');
+    const clientDir = resolve(cfg.root, 'dist/client');
+    const handler = await createProdHandler(config);
+    const { routes, crawl } = cfg.prerender;
+    const queue = routes.map(norm);
+    const seen = new Set();
+    const written = [];
+    while (queue.length) {
+        const url = queue.shift();
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        let html;
+        try {
+            const res = await handler(new Request('http://prerender.local' + url));
+            if (!res.ok) {
+                process.stdout.write(`    ${c.yellow('skip')} ${url} ${c.gray('→ ' + res.status)}\n`);
+                continue;
+            }
+            if (!(res.headers.get('content-type') || '').includes('html'))
+                continue;
+            html = await res.text();
+        }
+        catch (e) {
+            process.stdout.write(`    ${c.yellow('skip')} ${url} ${c.gray('→ ' + e.message)}\n`);
+            continue;
+        }
+        const file = join(clientDir, htmlPath(url));
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, html);
+        written.push(url);
+        if (crawl)
+            for (const link of extractLinks(html))
+                if (!seen.has(link))
+                    queue.push(link);
+    }
+    done(`${c.bold('prerendered')} ${c.bold(String(written.length))} page(s)  ${c.gray('→ dist/client')}\n`);
+    return written;
+}

package/dist/commands/start.d.ts

@@ -0,0 +1,9 @@
+import type { FluixiConfig } from '../config.js';
+/**
+ * Production server: build the runtime-neutral SSR fetch handler from the `fluixi
+ * build` output and serve it via the Node adapter (static files from dist/client +
+ * SSR for everything else). Other runtimes (edge/Bun/Deno) use the same
+ * `createProdHandler` with their own adapter — `export default { fetch }`.
+ */
+export declare function start(config?: FluixiConfig): Promise<void>;
+//# sourceMappingURL=start.d.ts.map

package/dist/commands/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/commands/start.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAKjD;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQpE"}

package/dist/commands/start.js

@@ -0,0 +1,18 @@
+import { resolve } from 'node:path';
+import { resolveConfig } from '../config.js';
+import { installCrashGuards, loadServerEnv } from '../internal.js';
+import { createProdHandler, nodeAdapter } from '../adapter.js';
+/**
+ * Production server: build the runtime-neutral SSR fetch handler from the `fluixi
+ * build` output and serve it via the Node adapter (static files from dist/client +
+ * SSR for everything else). Other runtimes (edge/Bun/Deno) use the same
+ * `createProdHandler` with their own adapter — `export default { fetch }`.
+ */
+export async function start(config = {}) {
+    const cfg = resolveConfig(config);
+    installCrashGuards();
+    await loadServerEnv(cfg.root, 'production'); // .env → process.env (server-only secrets)
+    const clientDir = resolve(cfg.root, 'dist/client');
+    const handler = await createProdHandler(cfg);
+    await nodeAdapter.serve({ handler, cfg, clientDir });
+}

package/dist/config.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Fluixi app config. Place in `fluixi.config.{ts,js,mjs}` at the app root and wrap
+ * with `defineConfig` for types. Everything is optional — the defaults match the
+ * conventional layout (src/entry-server.ts, src/entry-client.ts, index.html).
+ */
+export interface FluixiConfig {
+    /** App root directory. Default: process.cwd(). */
+    root?: string;
+    /**
+     * Render mode. `true` (default) = SSR: the server entry renders HTML per request. `false`
+     * = SPA: the server serves the static shell and the client renders — but you still get the
+     * full @fluixi/start server (file routing, middleware, env, and `/_server` server functions).
+     * The same app code runs either way; flip this to choose where the first paint happens.
+     */
+    ssr?: boolean;
+    /** Dev/prod server port. Default: 3000. */
+    port?: number;
+    /** Server entry exporting `render(url): string | Promise<string>`. Default: src/entry-server.ts */
+    serverEntry?: string;
+    /** Client hydration entry. Default: src/entry-client.ts */
+    clientEntry?: string;
+    /** HTML template. Default: index.html */
+    template?: string;
+    /** Element id the app HTML is injected into (`<div id="…"></div>`). Default: root */
+    mountId?: string;
+    /** File-routes directory (passed to fluixiRoutesPlugin). Default: src/routes */
+    routesDir?: string;
+    /** File-based API routes directory; files export GET/POST/… handlers served at `/api/*`. Default: src/api */
+    apiDir?: string;
+    /** Request middleware module (default-exports `defineMiddleware([...])`). Default: src/middleware.ts */
+    middleware?: string;
+    /** SSR deps Vite must bundle (no-external) — e.g. ESM packages without file extensions. */
+    ssrNoExternal?: string[];
+    /**
+     * Built-in i18n auto-discovery. Scans `<dir>/<locale>.json` and exposes them as
+     * `virtual:fluixi-i18n` (`{ messages, locales, defaultLocale }`) to feed `createI18n`.
+     * `false` disables it; an object configures the folder / locales / default. Default: enabled
+     * with `src/i18n` — a no-op until that folder has `*.json` files, so it's effectively opt-in.
+     */
+    i18n?: boolean | {
+        dir?: string;
+        defaultLocale?: string;
+        locales?: string[];
+    };
+    /**
+     * Static Site Generation. When set, `fluixi build` prerenders routes to static HTML in
+     * `dist/client` (served by any static host; hydrates on the client). `true` prerenders `/`
+     * and crawls internal `<a href>` links. An object sets explicit `routes` (for dynamic paths
+     * with no incoming link) and toggles `crawl`. Requires `ssr: true` (it renders to prerender).
+     */
+    prerender?: boolean | {
+        routes?: string[];
+        crawl?: boolean;
+    };
+}
+/** Resolved i18n discovery config (or `false` when disabled). */
+export interface ResolvedI18n {
+    dir: string;
+    defaultLocale?: string;
+    locales?: string[];
+}
+/** Resolved SSG config (or `false` when disabled). */
+export interface ResolvedPrerender {
+    routes: string[];
+    crawl: boolean;
+}
+export type ResolvedConfig = Required<Omit<FluixiConfig, 'ssrNoExternal' | 'i18n' | 'prerender'>> & {
+    ssrNoExternal: string[];
+    i18n: ResolvedI18n | false;
+    prerender: ResolvedPrerender | false;
+};
+/** Identity helper for editor types in `fluixi.config.ts`. */
+export declare function defineConfig(config: FluixiConfig): FluixiConfig;
+/** Apply defaults. */
+export declare function resolveConfig(config?: FluixiConfig): ResolvedConfig;
+/**
+ * Load `fluixi.config.{ts,mts,mjs,js}` from the app root. TypeScript configs are
+ * bundled on the fly with esbuild and imported; plain ESM is imported directly.
+ * No config is fine too — every field has a default.
+ */
+export declare function loadConfig(root?: string): Promise<FluixiConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mGAAmG;IACnG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6GAA6G;IAC7G,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9E;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9D;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC,GAAG;IAClG,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,EAAE,YAAY,GAAG,KAAK,CAAC;IAC3B,SAAS,EAAE,iBAAiB,GAAG,KAAK,CAAC;CACtC,CAAC;AAEF,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D;AAED,sBAAsB;AACtB,wBAAgB,aAAa,CAAC,MAAM,GAAE,YAAiB,GAAG,cAAc,CAiBvE;AAgCD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,SAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAM5E"}

package/dist/config.js

@@ -0,0 +1,116 @@
+import { pathToFileURL } from 'node:url';
+import { existsSync } from 'node:fs';
+import { writeFile, unlink } from 'node:fs/promises';
+import { resolve, isAbsolute } from 'node:path';
+/** Identity helper for editor types in `fluixi.config.ts`. */
+export function defineConfig(config) {
+    return config;
+}
+/** Apply defaults. */
+export function resolveConfig(config = {}) {
+    const root = resolve(config.root ?? process.cwd());
+    return {
+        root,
+        ssr: config.ssr ?? true,
+        port: config.port ?? 3000,
+        serverEntry: config.serverEntry ?? 'src/entry-server.ts',
+        clientEntry: config.clientEntry ?? 'src/entry-client.ts',
+        template: config.template ?? 'index.html',
+        mountId: config.mountId ?? 'root',
+        routesDir: config.routesDir ?? 'src/routes',
+        apiDir: config.apiDir ?? 'src/api',
+        middleware: config.middleware ?? 'src/middleware.ts',
+        ssrNoExternal: config.ssrNoExternal ?? [],
+        i18n: resolveI18n(config.i18n),
+        prerender: resolvePrerender(config.prerender),
+    };
+}
+/** `false`/unset → disabled; `true` → crawl from `/`; object → explicit routes + crawl toggle. */
+function resolvePrerender(prerender) {
+    if (!prerender)
+        return false;
+    const opts = typeof prerender === 'object' ? prerender : {};
+    return {
+        routes: opts.routes?.length ? opts.routes : ['/'],
+        crawl: opts.crawl ?? true,
+    };
+}
+/** `false` → disabled; otherwise a folder (default `src/i18n`) + optional locales/default. */
+function resolveI18n(i18n) {
+    if (i18n === false)
+        return false;
+    const opts = typeof i18n === 'object' ? i18n : {};
+    return {
+        dir: opts.dir ?? 'src/i18n',
+        defaultLocale: opts.defaultLocale,
+        locales: opts.locales,
+    };
+}
+// Config filenames probed, in order. TS first so a `.ts` config wins over a stray
+// build artifact; `.mts`/`.mjs`/`.js` cover plain-ESM configs.
+const CONFIG_NAMES = [
+    'fluixi.config.ts',
+    'fluixi.config.mts',
+    'fluixi.config.mjs',
+    'fluixi.config.js',
+];
+/**
+ * Load `fluixi.config.{ts,mts,mjs,js}` from the app root. TypeScript configs are
+ * bundled on the fly with esbuild and imported; plain ESM is imported directly.
+ * No config is fine too — every field has a default.
+ */
+export async function loadConfig(root = process.cwd()) {
+    for (const name of CONFIG_NAMES) {
+        const file = resolve(root, name);
+        if (existsSync(file))
+            return loadConfigFile(file);
+    }
+    return {};
+}
+async function loadConfigFile(file) {
+    // Plain ESM (.mjs/.js) — import directly, no transform needed.
+    if (!/\.[mc]?ts$/.test(file)) {
+        const mod = await import(/* @vite-ignore */ pathToFileURL(file).href);
+        return (mod.default ?? mod);
+    }
+    // TypeScript — bundle with esbuild, keeping bare specifiers external so
+    // `import { defineConfig } from '@fluixi/start'` and node builtins resolve from
+    // the app. Relative imports (shared constants, env helpers) ARE bundled in. The
+    // output is written to a temp `.mjs` beside the source so those externals resolve
+    // against the app's node_modules, then imported and removed.
+    const esbuild = await import('esbuild');
+    const { outputFiles } = await esbuild.build({
+        entryPoints: [file],
+        bundle: true,
+        write: false,
+        format: 'esm',
+        platform: 'node',
+        target: `node${process.versions.node.split('.')[0]}`,
+        sourcemap: 'inline',
+        plugins: [
+            {
+                name: 'fluixi:externalize-bare',
+                setup(b) {
+                    b.onResolve({ filter: /.*/ }, (args) => {
+                        if (args.kind === 'entry-point')
+                            return null;
+                        if (args.path.startsWith('.') || isAbsolute(args.path))
+                            return null;
+                        return { path: args.path, external: true };
+                    });
+                },
+            },
+        ],
+    });
+    const tempFile = `${file}.timestamp-${Date.now()}-${Math.random()
+        .toString(16)
+        .slice(2)}.mjs`;
+    await writeFile(tempFile, outputFiles[0].text);
+    try {
+        const mod = await import(/* @vite-ignore */ pathToFileURL(tempFile).href);
+        return (mod.default ?? mod);
+    }
+    finally {
+        await unlink(tempFile).catch(() => { });
+    }
+}

package/dist/di.d.ts

@@ -0,0 +1,63 @@
+export interface Token<T> {
+    readonly id: symbol;
+    readonly name: string;
+    /** Tree-shakable root default (Angular's `providedIn: 'root'`). Used when no provider is found. */
+    readonly factory?: () => T;
+}
+/** Create a typed injection token. Give it a `factory` to be self-providing at the root. */
+export declare function injectionToken<T>(name: string, options?: {
+    factory?: () => T;
+}): Token<T>;
+export type Provider<T = any> = {
+    provide: Token<T>;
+    useValue: T;
+} | {
+    provide: Token<T>;
+    useClass: new (...args: any[]) => T;
+    deps?: ReadonlyArray<Token<any>>;
+} | {
+    provide: Token<T>;
+    useFactory: (...deps: any[]) => T;
+    deps?: ReadonlyArray<Token<any>>;
+} | {
+    provide: Token<T>;
+    useExisting: Token<T>;
+};
+interface Rec {
+    provider: Provider;
+    built: boolean;
+    building: boolean;
+    value: unknown;
+}
+export declare class Injector {
+    #private;
+    readonly parent: Injector | null;
+    readonly records: Map<symbol, Rec>;
+    constructor(parent?: Injector | null);
+    register(providers: ReadonlyArray<Provider>): this;
+    /** Resolve a token from this injector, walking up the parent chain, then the token's factory. */
+    get<T>(token: Token<T>): T;
+    /** Run every built service's `onDestroy()`. Owner-scoped injectors call this on cleanup. */
+    dispose(): void;
+}
+/** Resolve a dependency from the current injection context. */
+export declare function inject<T>(token: Token<T>): T;
+/**
+ * Provide services for the CURRENT component/route and its descendants (owner-scoped). The
+ * injector is disposed — running each service's `onDestroy()` — when the component unmounts.
+ */
+export declare function provide(providers: ReadonlyArray<Provider>): Injector;
+/**
+ * Provide app-wide services. On the client these are singletons; during SSR each request gets
+ * its OWN instances (the root injector is per-request) — so a stateful root service can never
+ * leak between concurrent requests. Call at module load (e.g. in entry-client / entry-server).
+ */
+export declare function provideRoot(providers: ReadonlyArray<Provider>): void;
+/** Run `fn` with an explicit injector as the injection context (e.g. inside a server function). */
+export declare function runInInjectionContext<R>(injector: Injector, fn: () => R): R;
+/** The injector for the current scope (advanced — for passing to runInInjectionContext later). */
+export declare function getInjector(): Injector;
+/** A standalone injector (parent defaults to the root) — for tests / manual hierarchies. */
+export declare function createInjector(providers: ReadonlyArray<Provider>, parent?: Injector | null): Injector;
+export {};
+//# sourceMappingURL=di.d.ts.map

package/dist/di.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"di.d.ts","sourceRoot":"","sources":["../src/di.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mGAAmG;IACnG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;CAC5B;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAEzF;AAED,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,GAAG,IACxB;IAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,GAClC;IAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAAC,QAAQ,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;CAAE,GAC5F;IAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAAC,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;CAAE,GAC1F;IAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AAIjD,UAAU,GAAG;IACX,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,QAAQ;;IAEP,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAD5C,QAAQ,CAAC,OAAO,mBAA0B;gBACrB,MAAM,GAAE,QAAQ,GAAG,IAAW;IAEnD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,IAAI;IAOlD,iGAAiG;IACjG,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;IA4C1B,4FAA4F;IAC5F,OAAO,IAAI,IAAI;CAahB;AAoDD,+DAA+D;AAC/D,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAE5C;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAapE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,IAAI,CAKpE;AAED,mGAAmG;AACnG,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAQ3E;AAED,kGAAkG;AAClG,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,QAAQ,CAErG"}

package/dist/di.js

@@ -0,0 +1,210 @@
+/**
+ * @fluixi/start/di — dependency injection, the Angular way, but SSR-correct and reactive.
+ *
+ * Three things make this distinct from Angular's DI:
+ *
+ *  1. **SSR request isolation, for free.** A "root" provider is a singleton on the CLIENT but
+ *     a fresh instance PER REQUEST on the server — because the root injector lives in the
+ *     per-request `RequestContext` (the same machinery that isolates resources/markers). So
+ *     a stateful root service (a per-user cache, a DB unit-of-work) never leaks across two
+ *     concurrent SSR requests. No zone, no `providedIn` ceremony, no manual request injectors.
+ *
+ *  2. **The reactive owner tree IS the injector hierarchy.** `provide()` in a component
+ *     attaches a child injector to that component's reactive owner; descendants `inject()`
+ *     by walking the owner chain — exactly how context resolves. Component-scoped services
+ *     are disposed with the component (their `onDestroy()` runs on owner cleanup).
+ *
+ *  3. **Function injection, tree-shakable tokens.** No decorators/reflect-metadata. A token
+ *     can carry a `factory` (Angular's `providedIn: 'root'`), so an unused service is dropped
+ *     by the bundler; a used one self-provides at the root with no registration.
+ *
+ *     const Logger = injectionToken<Logger>('Logger', { factory: () => new ConsoleLogger() });
+ *     class UserService { #log = inject(Logger); load() { this.#log.info('…'); } }
+ *     const Users = injectionToken('Users', { factory: () => new UserService() });
+ *     // in a component / route / server function:
+ *     const users = inject(Users);
+ *
+ * Client-safe: imports only `@fluixi/core` (owner) + `@fluixi/dom`'s pure `getRequestContext`.
+ */
+import { getOwner, onCleanup } from '@fluixi/core';
+import { getRequestContext } from '@fluixi/dom';
+/** Create a typed injection token. Give it a `factory` to be self-providing at the root. */
+export function injectionToken(name, options) {
+    return { id: Symbol(name), name, factory: options?.factory };
+}
+export class Injector {
+    parent;
+    records = new Map();
+    constructor(parent = null) {
+        this.parent = parent;
+    }
+    register(providers) {
+        for (const p of providers) {
+            this.records.set(p.provide.id, { provider: p, built: false, building: false, value: undefined });
+        }
+        return this;
+    }
+    /** Resolve a token from this injector, walking up the parent chain, then the token's factory. */
+    get(token) {
+        let inj = this;
+        while (inj) {
+            const rec = inj.records.get(token.id);
+            if (rec)
+                return inj.#build(token, rec);
+            inj = inj.parent;
+        }
+        // Unprovided but self-providing → instantiate at the ROOT of this chain (so it's a
+        // per-request singleton on the server, an app singleton on the client).
+        if (token.factory)
+            return rootOf(this).#fromFactory(token);
+        throw new Error(`[fluixi/di] No provider for "${token.name}". Register it with provide()/provideRoot(), ` +
+            `or give the token a { factory } to self-provide.`);
+    }
+    #build(token, rec) {
+        if (rec.built)
+            return rec.value;
+        if (rec.building)
+            throw new Error(`[fluixi/di] Circular dependency while resolving "${token.name}".`);
+        rec.building = true;
+        const p = rec.provider;
+        try {
+            if ('useValue' in p)
+                rec.value = p.useValue;
+            else if ('useExisting' in p)
+                rec.value = this.get(p.useExisting);
+            else {
+                const deps = (p.deps ?? []).map((d) => this.get(d)); // deps resolve from where the provider lives
+                rec.value = 'useClass' in p ? new p.useClass(...deps) : p.useFactory(...deps);
+            }
+        }
+        finally {
+            rec.building = false;
+        }
+        rec.built = true;
+        return rec.value;
+    }
+    #fromFactory(token) {
+        let rec = this.records.get(token.id);
+        if (!rec) {
+            rec = { provider: { provide: token, useFactory: token.factory }, built: false, building: false, value: undefined };
+            this.records.set(token.id, rec);
+        }
+        return this.#build(token, rec);
+    }
+    /** Run every built service's `onDestroy()`. Owner-scoped injectors call this on cleanup. */
+    dispose() {
+        for (const rec of this.records.values()) {
+            const v = rec.value;
+            if (rec.built && v && typeof v.onDestroy === 'function') {
+                try {
+                    v.onDestroy();
+                }
+                catch (e) {
+                    console.error('[fluixi/di] onDestroy threw —', e);
+                }
+            }
+        }
+        this.records.clear();
+    }
+}
+function rootOf(inj) {
+    let i = inj;
+    while (i.parent)
+        i = i.parent;
+    return i;
+}
+// ── Scoping: root (per-request on server / singleton on client) + owner tree ──
+const _rootProviders = [];
+const _reqInjectors = new WeakMap(); // per-request root (server)
+const _ownerInjectors = new WeakMap(); // per reactive owner (component scope)
+let _clientRoot = null;
+let _explicit = null;
+/** The root injector — per-request during SSR (isolated), a module singleton on the client. */
+function rootInjector() {
+    const ctx = getRequestContext();
+    if (ctx) {
+        let inj = _reqInjectors.get(ctx);
+        if (!inj)
+            _reqInjectors.set(ctx, (inj = new Injector(null).register(_rootProviders)));
+        return inj;
+    }
+    return (_clientRoot ??= new Injector(null).register(_rootProviders));
+}
+/** Nearest ancestor owner injector, else the root — the parent of a new component injector. */
+function parentInjectorOf(owner) {
+    let o = owner?.parent;
+    while (o) {
+        const inj = _ownerInjectors.get(o);
+        if (inj)
+            return inj;
+        o = o.parent;
+    }
+    return rootInjector();
+}
+/** The injector for the current scope: explicit context → nearest owner injector → root. */
+function currentInjector() {
+    if (_explicit)
+        return _explicit;
+    let o = getOwner();
+    while (o) {
+        const inj = _ownerInjectors.get(o);
+        if (inj)
+            return inj;
+        o = o.parent;
+    }
+    return rootInjector();
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+/** Resolve a dependency from the current injection context. */
+export function inject(token) {
+    return currentInjector().get(token);
+}
+/**
+ * Provide services for the CURRENT component/route and its descendants (owner-scoped). The
+ * injector is disposed — running each service's `onDestroy()` — when the component unmounts.
+ */
+export function provide(providers) {
+    const owner = getOwner();
+    if (!owner) {
+        throw new Error('[fluixi/di] provide() must run inside a component/owner scope. Use provideRoot() for app-wide services.');
+    }
+    let inj = _ownerInjectors.get(owner);
+    if (!inj) {
+        inj = new Injector(parentInjectorOf(owner));
+        _ownerInjectors.set(owner, inj);
+        onCleanup(() => inj.dispose());
+    }
+    inj.register(providers);
+    return inj;
+}
+/**
+ * Provide app-wide services. On the client these are singletons; during SSR each request gets
+ * its OWN instances (the root injector is per-request) — so a stateful root service can never
+ * leak between concurrent requests. Call at module load (e.g. in entry-client / entry-server).
+ */
+export function provideRoot(providers) {
+    _rootProviders.push(...providers);
+    _clientRoot?.register(providers); // apply to an already-created client root
+    const ctx = getRequestContext();
+    if (ctx)
+        _reqInjectors.get(ctx)?.register(providers); // and the active request root
+}
+/** Run `fn` with an explicit injector as the injection context (e.g. inside a server function). */
+export function runInInjectionContext(injector, fn) {
+    const prev = _explicit;
+    _explicit = injector;
+    try {
+        return fn();
+    }
+    finally {
+        _explicit = prev;
+    }
+}
+/** The injector for the current scope (advanced — for passing to runInInjectionContext later). */
+export function getInjector() {
+    return currentInjector();
+}
+/** A standalone injector (parent defaults to the root) — for tests / manual hierarchies. */
+export function createInjector(providers, parent) {
+    return new Injector(parent === undefined ? rootInjector() : parent).register(providers);
+}

package/dist/handler.d.ts

@@ -0,0 +1,42 @@
+import { type IncomingMessage, type ServerResponse, type Server } from 'node:http';
+/**
+ * The runtime-neutral request layer. Everything renders through a Web
+ * `Request → Response` handler, so the same core works in Node, Bun, Deno, and
+ * edge/worker runtimes — only the *bridge* (Node http here) is platform-specific.
+ * This is the seam deploy adapters plug into.
+ */
+/** Produce page HTML for a request URL (pathname + search). */
+export type RenderFn = (url: string, request: Request) => string | Promise<string>;
+/** Web-standard request handler. */
+export type FetchHandler = (request: Request) => Promise<Response>;
+/** Produce a web `ReadableStream` of the app body (no document shell) for a URL. */
+export type StreamRenderFn = (url: string, request: Request) => ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>;
+/**
+ * Compose a streamed HTML Response: flush `head` immediately (browser starts fetching
+ * assets while the server awaits data), then pipe the app `body` stream into the mount
+ * point, then `tail` (client script + closing tags). A render error after the head is
+ * flushed can only error the stream (status is already 200) — truncated HTML; callers
+ * should guard the pre-flush path for a real 500.
+ */
+export declare function streamDocument(head: string, body: ReadableStream<Uint8Array>, tail: string): Response;
+/** Wrap a render function as a fetch handler (Node/Bun/Deno/edge-portable). */
+export declare function createRequestHandler(render: RenderFn): FetchHandler;
+/** Build a Web `Request` from a Node `IncomingMessage`. */
+export declare function nodeToRequest(req: IncomingMessage): Request;
+/** Write a Web `Response` (string or streamed body) to a Node `ServerResponse`. */
+export declare function sendResponse(res: ServerResponse, response: Response): Promise<void>;
+/** Adapt a `FetchHandler` to a Node `(req, res)` handler. */
+export declare function toNodeHandler(handler: FetchHandler): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface ServeNodeOptions {
+    port?: number;
+    onListen?: (port: number) => void;
+}
+/** The reference **Node adapter**: serve a `FetchHandler` over `node:http`. */
+export declare function serveNode(handler: FetchHandler, opts?: ServeNodeOptions): Server;
+/**
+ * Wrap a handler to serve static files from `dir` first (for filesystem runtimes —
+ * Node/Bun/Deno). Edge runtimes serve assets via the platform, so they use the bare
+ * handler instead.
+ */
+export declare function withStaticFiles(handler: FetchHandler, dir: string): FetchHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAMrH;;;;;GAKG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEnF,oCAAoC;AACpC,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEnE,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,KACb,cAAc,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,IAAI,EAAE,MAAM,GACX,QAAQ,CAuBV;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,GAAG,YAAY,CAgBnE;AAID,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAe3D;AAED,mFAAmF;AACnF,wBAAsB,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBzF;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,IACnC,KAAK,eAAe,EAAE,KAAK,cAAc,KAAG,OAAO,CAAC,IAAI,CAAC,CAIxE;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAapF;AASD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAoBhF"}