@fluixi/start 0.1.0-alpha.73 → 0.1.0-alpha.75

package/dist/internal.cjs

@@ -0,0 +1,393 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/api.ts
+var api_exports = {};
+__export(api_exports, {
+  API_VIRTUAL_MODULE: () => API_VIRTUAL_MODULE,
+  apiRoutesVitePlugin: () => apiRoutesVitePlugin,
+  derivePattern: () => derivePattern,
+  handleApi: () => handleApi,
+  isApiPath: () => isApiPath,
+  matchApiRoutes: () => matchApiRoutes
+});
+function derivePattern(rel, prefix = "/api") {
+  const segs = rel.split("/").filter(Boolean);
+  if (segs[segs.length - 1] === "index") segs.pop();
+  const keys = [];
+  let rank = 0;
+  const parts = segs.map((seg) => {
+    const catchAll = seg.match(/^\[\.\.\.(.+)\]$/);
+    if (catchAll) {
+      keys.push(catchAll[1]);
+      return "(.+)";
+    }
+    const param = seg.match(/^\[(.+)\]$/);
+    if (param) {
+      keys.push(param[1]);
+      rank += 1;
+      return "([^/]+)";
+    }
+    rank += 10;
+    return seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  });
+  return { source: `^${prefix}${parts.length ? "/" + parts.join("/") : ""}/?$`, keys, rank };
+}
+function isApiPath(pathname, prefix = "/api") {
+  return pathname === prefix || pathname.startsWith(prefix + "/");
+}
+function matchApiRoutes(routes, pathname) {
+  for (const r of [...routes].sort((a, b) => b.rank - a.rank)) {
+    const m = new RegExp(r.source).exec(pathname);
+    if (!m) continue;
+    const params = {};
+    r.keys.forEach((k, i) => params[k] = decodeURIComponent(m[i + 1] ?? ""));
+    return { mod: r.mod, params };
+  }
+  return null;
+}
+async function handleApi(routes, request, prefix = "/api") {
+  const pathname = new URL(request.url).pathname;
+  const match = matchApiRoutes(routes, pathname);
+  if (!match) return new Response("Not Found", { status: 404 });
+  const fn = match.mod[request.method];
+  if (typeof fn !== "function") {
+    const allow = METHODS.filter((m) => typeof match.mod[m] === "function").join(", ");
+    return new Response("Method Not Allowed", { status: 405, headers: allow ? { allow } : void 0 });
+  }
+  const out = await fn(request, { params: match.params });
+  if (out instanceof Response) return out;
+  return new Response(JSON.stringify(out ?? null), { headers: { "content-type": "application/json; charset=utf-8" } });
+}
+function scanFiles(dir, base = dir) {
+  let out = [];
+  let entries = [];
+  try {
+    entries = (0, import_node_fs.readdirSync)(dir);
+  } catch {
+    return out;
+  }
+  for (const name of entries) {
+    const full = (0, import_node_path.join)(dir, name);
+    if ((0, import_node_fs.statSync)(full).isDirectory()) out = out.concat(scanFiles(full, base));
+    else if (/\.(ts|tsx|js|mjs)$/.test(name) && !/\.(spec|test)\./.test(name)) out.push(full);
+  }
+  return out;
+}
+function apiRoutesVitePlugin(opts) {
+  let root = process.cwd();
+  const prefix = opts.prefix ?? "/api";
+  const id = "\0" + API_VMOD;
+  return {
+    name: "fluixi-api",
+    // Must beat node resolution: '@fluixi/start/api-routes' is a real file in this package,
+    // so without `pre` Vite resolves the typed stub and the generated table never loads , 
+    // the app builds and every API route 404s.
+    enforce: "pre",
+    configResolved(config) {
+      root = config.root || root;
+    },
+    resolveId(source) {
+      return source === API_VMOD || source === "@fluixi/start/api-routes" ? id : null;
+    },
+    load(source) {
+      if (source !== id) return null;
+      const dir = (0, import_node_path.resolve)(root, opts.dir);
+      const files = scanFiles(dir);
+      const imports = [];
+      const entries = [];
+      files.forEach((file, i) => {
+        const rel = (0, import_node_path.relative)(dir, file).replace(/\.(ts|tsx|js|mjs)$/, "").split(/[\\/]/).join("/");
+        const { source: src, keys, rank } = derivePattern(rel, prefix);
+        imports.push(`import * as _${i} from ${JSON.stringify(file)};`);
+        entries.push(`{ source: ${JSON.stringify(src)}, keys: ${JSON.stringify(keys)}, rank: ${rank}, mod: _${i} }`);
+      });
+      return `import { isApiPath, handleApi } from '@fluixi/start/api';
+${imports.join("\n")}
+const routes = [${entries.join(",")}];
+export const isApiRequest = (request) => isApiPath(new URL(request.url).pathname, ${JSON.stringify(prefix)});
+export const handleApiRequest = (request) => handleApi(routes, request, ${JSON.stringify(prefix)});
+`;
+    }
+  };
+}
+var import_node_fs, import_node_path, API_VMOD, METHODS, API_VIRTUAL_MODULE;
+var init_api = __esm({
+  "src/api.ts"() {
+    "use strict";
+    import_node_fs = require("node:fs");
+    import_node_path = require("node:path");
+    API_VMOD = "virtual:fluixi-api";
+    METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
+    API_VIRTUAL_MODULE = API_VMOD;
+  }
+});
+
+// src/internal.ts
+var internal_exports = {};
+__export(internal_exports, {
+  I18N_VMOD: () => I18N_VMOD,
+  SERVER_FNS_VMOD: () => SERVER_FNS_VMOD,
+  fluixiPlugins: () => fluixiPlugins,
+  guardHandler: () => guardHandler,
+  i18nVitePlugin: () => i18nVitePlugin,
+  injectApp: () => injectApp,
+  injectAppAndHead: () => injectAppAndHead,
+  installCrashGuards: () => installCrashGuards,
+  loadServerEnv: () => loadServerEnv,
+  splitTemplate: () => splitTemplate,
+  startTypesPlugin: () => startTypesPlugin
+});
+module.exports = __toCommonJS(internal_exports);
+var import_node_fs2 = require("node:fs");
+var import_node_path2 = require("node:path");
+
+// src/document.ts
+var import_head = require("@fluixi/head");
+function injectApp(template, appHtml, mountId = "root") {
+  const mount = new RegExp(`<div id=["']${mountId}["']\\s*>\\s*</div>`);
+  if (mount.test(template)) {
+    return template.replace(mount, `<div id="${mountId}">${appHtml}</div>`);
+  }
+  if (template.includes("<!--ssr-outlet-->")) {
+    return template.replace("<!--ssr-outlet-->", appHtml);
+  }
+  return template.replace("</body>", `<div id="${mountId}">${appHtml}</div></body>`);
+}
+function splitTemplate(template, mountId = "root") {
+  const mount = new RegExp(`<div id=["']${mountId}["']\\s*>\\s*</div>`);
+  const m = template.match(mount);
+  if (m && m.index !== void 0) {
+    return {
+      head: template.slice(0, m.index) + `<div id="${mountId}">`,
+      tail: `</div>` + template.slice(m.index + m[0].length)
+    };
+  }
+  const outlet = template.indexOf("<!--ssr-outlet-->");
+  if (outlet !== -1) {
+    return {
+      head: template.slice(0, outlet),
+      tail: template.slice(outlet + "<!--ssr-outlet-->".length)
+    };
+  }
+  const body = template.indexOf("</body>");
+  if (body !== -1) {
+    return {
+      head: template.slice(0, body) + `<div id="${mountId}">`,
+      tail: `</div>` + template.slice(body)
+    };
+  }
+  return { head: template, tail: "" };
+}
+function setHtmlAttr(html, name, value) {
+  const existing = new RegExp(`(<html\\b[^>]*?)\\s${name}="[^"]*"`, "i");
+  if (existing.test(html)) return html.replace(existing, `$1 ${name}="${value}"`);
+  return html.replace(/<html\b/i, `<html ${name}="${value}"`);
+}
+function injectAppAndHead(template, rendered, mountId = "root") {
+  const { head, body } = (0, import_head.extractHeadMarker)(rendered);
+  let html = injectApp(template, body, mountId);
+  if (head) {
+    if (head.headHtml) {
+      if (/<title[\s>]/i.test(head.headHtml)) html = html.replace(/<title>[\s\S]*?<\/title>/i, "");
+      html = html.replace("</head>", `${head.headHtml}</head>`);
+    }
+    for (const [k, v] of Object.entries(head.htmlAttrs)) html = setHtmlAttr(html, k, v);
+  }
+  return html;
+}
+function guardHandler(handler, onError) {
+  return async (request) => {
+    try {
+      return await handler(request);
+    } catch (e) {
+      onError?.(e);
+      return new Response(String(e?.stack || e), {
+        status: 500,
+        headers: { "content-type": "text/plain; charset=utf-8" }
+      });
+    }
+  };
+}
+
+// src/internal.ts
+var SERVER_FNS_VMOD = "virtual:fluixi-server-fns";
+var I18N_VMOD = "virtual:fluixi-i18n";
+function i18nVitePlugin(opts) {
+  let root = process.cwd();
+  const id = "\0" + I18N_VMOD;
+  return {
+    name: "fluixi-i18n",
+    configResolved(config) {
+      root = config.root || root;
+    },
+    resolveId(source) {
+      return source === I18N_VMOD ? id : null;
+    },
+    load(source) {
+      if (source !== id) return null;
+      const dir = (0, import_node_path2.resolve)(root, opts.dir);
+      let files = [];
+      try {
+        files = (0, import_node_fs2.readdirSync)(dir).filter((f) => f.endsWith(".json"));
+      } catch {
+      }
+      const discovered = files.map((f) => f.replace(/\.json$/, "")).sort();
+      const locales = opts.locales?.length ? opts.locales : discovered;
+      const defaultLocale = opts.defaultLocale ?? locales[0] ?? "en";
+      const imports = locales.map((l, i) => `import _${i} from ${JSON.stringify((0, import_node_path2.resolve)(dir, l + ".json"))};`).join("\n");
+      const messages = `export const messages = {${locales.map((l, i) => `${JSON.stringify(l)}:_${i}`).join(",")}};`;
+      return `${imports}
+export const locales = ${JSON.stringify(locales)};
+export const defaultLocale = ${JSON.stringify(defaultLocale)};
+${messages}
+`;
+    }
+  };
+}
+async function loadServerEnv(root, mode) {
+  const { loadEnv } = await import("vite");
+  const env = loadEnv(mode, root, "");
+  for (const [k, v] of Object.entries(env)) {
+    if (process.env[k] === void 0) process.env[k] = v;
+  }
+}
+function i18nTypeBlock(root, i18n) {
+  const dir = (0, import_node_path2.resolve)(root, i18n.dir);
+  let discovered = [];
+  try {
+    discovered = (0, import_node_fs2.readdirSync)(dir).filter((f) => f.endsWith(".json")).map((f) => f.replace(/\.json$/, "")).sort();
+  } catch {
+  }
+  const locales = i18n.locales?.length ? i18n.locales : discovered;
+  const defaultLocale = i18n.defaultLocale ?? locales[0] ?? "en";
+  const typed = locales.length > 0 && locales.every((l) => discovered.includes(l));
+  if (!typed) {
+    return [
+      `declare module 'virtual:fluixi-i18n' {`,
+      `  export const messages: Record<string, Record<string, unknown>>;`,
+      `  export const locales: string[];`,
+      `  export const defaultLocale: string;`,
+      `}`
+    ];
+  }
+  const srcDir = (0, import_node_path2.resolve)(root, "src");
+  const toSpec = (l) => {
+    const rel = (0, import_node_path2.relative)(srcDir, (0, import_node_path2.resolve)(dir, l + ".json")).split(/[\\/]/).join("/");
+    return rel.startsWith(".") ? rel : "./" + rel;
+  };
+  const entries = locales.map((l) => `    ${JSON.stringify(l)}: (typeof import(${JSON.stringify(toSpec(l))}))['default'];`);
+  const tuple = locales.map((l) => JSON.stringify(l)).join(", ");
+  return [
+    `declare module 'virtual:fluixi-i18n' {`,
+    `  export const messages: {`,
+    ...entries,
+    `  };`,
+    `  export const locales: readonly [${tuple}];`,
+    `  export const defaultLocale: ${JSON.stringify(defaultLocale)};`,
+    `}`
+  ];
+}
+function startTypesPlugin(cfg) {
+  let root = process.cwd();
+  return {
+    name: "fluixi-start-types",
+    configResolved(config) {
+      root = config.root || root;
+    },
+    buildStart() {
+      const blocks = [];
+      if (cfg.i18n) blocks.push(...i18nTypeBlock(root, cfg.i18n));
+      if (blocks.length === 0) return;
+      const content = `// Auto-generated by @fluixi/start, do not edit.
+${blocks.join("\n")}
+`;
+      const file = (0, import_node_path2.resolve)(root, "src/fluixi-start-env.d.ts");
+      try {
+        if (!(0, import_node_fs2.existsSync)(file) || (0, import_node_fs2.readFileSync)(file, "utf8") !== content) (0, import_node_fs2.writeFileSync)(file, content);
+      } catch {
+      }
+    }
+  };
+}
+async function fluixiPlugins(cfg) {
+  const { fluixi, fluixiRoutesPlugin } = await import("@fluixi/core/plugins");
+  const { serverFunctionsVitePlugin } = await import("@fluixi/compiler/integrations");
+  const plugins = [
+    serverFunctionsVitePlugin(),
+    fluixiRoutesPlugin({ routesDir: cfg.routesDir, polyfills: false }),
+    // The app's component-resolution rules reach the compiler here; without this an SSR
+    // app has no way to say where an unimported tag comes from.
+    //
+    // `fluixi()` and not `createVitePlugin()`: the latter is the bare compiler integration,
+    // and the reactive graph: agent, source marks, /__fluixi/graph, is composed on top of
+    // it by the former. A start app got no graph at all until this changed.
+    // Everything the app declared for the compiler, with `resolve` still usable on its
+    // own because it is the one most apps set. A start app never writes
+    // `fluixi()` itself, so without this passthrough the plugin's other options
+    // (propsDestructure and the rest) had nowhere to be declared.
+    fluixi({ ...cfg.vitePlugin ?? {}, ...cfg.resolve ? { resolve: cfg.resolve } : {} })
+  ];
+  if (cfg.plugins?.length) plugins.push(...cfg.plugins);
+  if (cfg.i18n) plugins.push(i18nVitePlugin(cfg.i18n));
+  const { apiRoutesVitePlugin: apiRoutesVitePlugin2 } = await Promise.resolve().then(() => (init_api(), api_exports));
+  plugins.push(apiRoutesVitePlugin2({ dir: cfg.apiDir }));
+  plugins.push(startTypesPlugin(cfg));
+  return plugins;
+}
+var _guardsInstalled = false;
+function installCrashGuards() {
+  if (_guardsInstalled) return;
+  _guardsInstalled = true;
+  process.on(
+    "unhandledRejection",
+    (reason) => console.warn("[fluixi] unhandled rejection (backend likely down) —", reason?.message || reason)
+  );
+  process.on(
+    "uncaughtException",
+    (err) => console.warn("[fluixi] uncaught exception —", err?.message || err)
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  I18N_VMOD,
+  SERVER_FNS_VMOD,
+  fluixiPlugins,
+  guardHandler,
+  i18nVitePlugin,
+  injectApp,
+  injectAppAndHead,
+  installCrashGuards,
+  loadServerEnv,
+  splitTemplate,
+  startTypesPlugin
+});

package/dist/internal.d.ts

@@ -5,7 +5,7 @@ export declare const SERVER_FNS_VMOD = "virtual:fluixi-server-fns";
 export declare const I18N_VMOD = "virtual:fluixi-i18n";
 /**
  * Auto-discover translations. Scans `<dir>/<locale>.json` (e.g. `src/i18n/en.json`, `fr.json`)
- * and provides `virtual:fluixi-i18n` exporting `{ messages, locales, defaultLocale }` — wire it
+ * and provides `virtual:fluixi-i18n` exporting `{ messages, locales, defaultLocale }`, wire it
  * into the built-in i18n in one line:
  *
  *   import { createI18n } from '@fluixi/core/i18n';
@@ -20,12 +20,12 @@ export declare function i18nVitePlugin(opts: {
     locales?: string[];
 }): any;
 /**
- * Load env files into `process.env` for SERVER code — the framework's environment manager.
+ * Load env files into `process.env` for SERVER code, the framework's environment manager.
  *
  * SECURITY MODEL (Vite-aligned): only `VITE_`-prefixed vars are exposed to the client (via
  * `import.meta.env`, inlined into the browser bundle). Everything else is server-only. This
  * loads ALL vars (`.env`, `.env.local`, `.env.[mode]`, `.env.[mode].local`) into `process.env`
- * so loaders + `"use server"` functions can read secrets — WITHOUT ever exposing non-`VITE_`
+ * so loaders + `"use server"` functions can read secrets, WITHOUT ever exposing non-`VITE_`
  * vars to the browser. A real (OS) env var always wins, so deploys/secret managers override files.
  *
  * Result: `process.env.STRIPE_SECRET` works on the server and never ships to the web; only
@@ -36,14 +36,14 @@ export declare function loadServerEnv(root: string, mode: string): Promise<void>
  * Auto-generate ambient TypeScript declarations for @fluixi/start's virtual modules
  * (`virtual:fluixi-server-fns`, `virtual:fluixi-i18n`) into `src/fluixi-start-env.d.ts`, the
  * way the routes plugin writes `fluixi-env.d.ts`. So apps NEVER hand-write these `declare
- * module` blocks — the modules AND their types are both generated. Idempotent (only writes on
+ * module` blocks: the modules AND their types are both generated. Idempotent (only writes on
  * change), runs in dev + build.
  */
 export declare function startTypesPlugin(cfg: ResolvedConfig): any;
 /**
  * The fluixi build plugins @fluixi/start provides by default: file-based routing
  * (fluixiRoutesPlugin → virtual:fluixi-routes) + the JSX/SSR transform
- * (createVitePlugin). This is what makes start "sit on top of fluixi" — apps get
+ * (createVitePlugin). This is what makes start "sit on top of fluixi", apps get
  * zero-config routing + SSR. Apps using `fluixi dev|build` should therefore NOT add
  * these to their own vite.config (start owns them); keep vite.config for app-specific
  * bits only (optimizeDeps, ssr.noExternal via config, etc.).
@@ -52,7 +52,7 @@ export declare function fluixiPlugins(cfg: ResolvedConfig): Promise<any[]>;
 export { injectApp, splitTemplate, injectAppAndHead, guardHandler, } from './document.js';
 /**
  * A render fires the route's data fetches eagerly; if the backend is down those
- * promises can reject AFTER we've already responded, with nothing awaiting them —
+ * promises can reject AFTER we've already responded, with nothing awaiting them ,
  * a floating rejection would kill the dev server. Swallow + log instead.
  */
 export declare function installCrashGuards(): void;

package/dist/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,6FAA6F;AAC7F,eAAO,MAAM,eAAe,8BAA8B,CAAC;AAE3D,wGAAwG;AACxG,eAAO,MAAM,SAAS,wBAAwB,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,GAAG,CAoCrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM7E;AA6DD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,GAAG,CA0BzD;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CA0BvE;AAED,OAAO,EACL,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,YAAY,GACb,MAAM,eAAe,CAAC;AAIvB;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CASzC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,6FAA6F;AAC7F,eAAO,MAAM,eAAe,8BAA8B,CAAC;AAE3D,wGAAwG;AACxG,eAAO,MAAM,SAAS,wBAAwB,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,GAAG,CAoCrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM7E;AA6DD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,GAAG,CA0BzD;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAiCvE;AAED,OAAO,EACL,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,YAAY,GACb,MAAM,eAAe,CAAC;AAIvB;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CASzC"}

package/dist/internal.js

@@ -6,7 +6,7 @@ export const SERVER_FNS_VMOD = 'virtual:fluixi-server-fns';
 export const I18N_VMOD = 'virtual:fluixi-i18n';
 /**
  * Auto-discover translations. Scans `<dir>/<locale>.json` (e.g. `src/i18n/en.json`, `fr.json`)
- * and provides `virtual:fluixi-i18n` exporting `{ messages, locales, defaultLocale }` — wire it
+ * and provides `virtual:fluixi-i18n` exporting `{ messages, locales, defaultLocale }`, wire it
  * into the built-in i18n in one line:
  *
  *   import { createI18n } from '@fluixi/core/i18n';
@@ -53,12 +53,12 @@ export function i18nVitePlugin(opts) {
     };
 }
 /**
- * Load env files into `process.env` for SERVER code — the framework's environment manager.
+ * Load env files into `process.env` for SERVER code, the framework's environment manager.
  *
  * SECURITY MODEL (Vite-aligned): only `VITE_`-prefixed vars are exposed to the client (via
  * `import.meta.env`, inlined into the browser bundle). Everything else is server-only. This
  * loads ALL vars (`.env`, `.env.local`, `.env.[mode]`, `.env.[mode].local`) into `process.env`
- * so loaders + `"use server"` functions can read secrets — WITHOUT ever exposing non-`VITE_`
+ * so loaders + `"use server"` functions can read secrets, WITHOUT ever exposing non-`VITE_`
  * vars to the browser. A real (OS) env var always wins, so deploys/secret managers override files.
  *
  * Result: `process.env.STRIPE_SECRET` works on the server and never ships to the web; only
@@ -73,12 +73,12 @@ export async function loadServerEnv(root, mode) {
     }
 }
 /**
- * Build the `declare module 'virtual:fluixi-i18n'` block — TYPED off the actual JSON files
+ * Build the `declare module 'virtual:fluixi-i18n'` block, TYPED off the actual JSON files
  * so `createI18n({ messages })` infers translation keys end-to-end from auto-discovery.
  *
  * Instead of typing `messages` as `Record<string, unknown>` (which erases keys), we reference
  * each `<locale>.json` via `(typeof import('./i18n/en.json'))['default']`. TS reads the JSON's
- * real shape, so `t('…')` autocompletes keys discovered from `src/i18n/*.json` — no codegen of
+ * real shape, so `t('…')` autocompletes keys discovered from `src/i18n/*.json`, no codegen of
  * the key union, the compiler derives it. Falls back to the loose shape when no files exist yet
  * (or a configured locale has no file), keeping the module typed-but-open rather than broken.
  *
@@ -130,7 +130,7 @@ function i18nTypeBlock(root, i18n) {
  * Auto-generate ambient TypeScript declarations for @fluixi/start's virtual modules
  * (`virtual:fluixi-server-fns`, `virtual:fluixi-i18n`) into `src/fluixi-start-env.d.ts`, the
  * way the routes plugin writes `fluixi-env.d.ts`. So apps NEVER hand-write these `declare
- * module` blocks — the modules AND their types are both generated. Idempotent (only writes on
+ * module` blocks: the modules AND their types are both generated. Idempotent (only writes on
  * change), runs in dev + build.
  */
 export function startTypesPlugin(cfg) {
@@ -145,21 +145,21 @@ export function startTypesPlugin(cfg) {
             // have fixed signatures, so they moved to real package entries
             // (`@fluixi/start/server-fns`, `@fluixi/start/api-routes`) whose types ship with the
             // package. i18n cannot follow: its `messages` type is derived from the app's own JSON
-            // (`typeof import('./i18n/en.json')`) and its `locales` is a literal tuple — that is
+            // (`typeof import('./i18n/en.json')`) and its `locales` is a literal tuple, that is
             // what makes keys autocomplete, and no static entry can express it.
             const blocks = [];
             if (cfg.i18n)
                 blocks.push(...i18nTypeBlock(root, cfg.i18n));
             if (blocks.length === 0)
-                return; // no i18n configured — nothing left to declare
-            const content = `// Auto-generated by @fluixi/start — do not edit.\n${blocks.join('\n')}\n`;
+                return; // no i18n configured: nothing left to declare
+            const content = `// Auto-generated by @fluixi/start, do not edit.\n${blocks.join('\n')}\n`;
             const file = resolvePath(root, 'src/fluixi-start-env.d.ts');
             try {
                 if (!existsSync(file) || readFileSync(file, 'utf8') !== content)
                     writeFileSync(file, content);
             }
             catch {
-                /* read-only fs (some CI) — types are a dev convenience, build still works */
+                /* read-only fs (some CI), types are a dev convenience, build still works */
             }
         },
     };
@@ -167,7 +167,7 @@ export function startTypesPlugin(cfg) {
 /**
  * The fluixi build plugins @fluixi/start provides by default: file-based routing
  * (fluixiRoutesPlugin → virtual:fluixi-routes) + the JSX/SSR transform
- * (createVitePlugin). This is what makes start "sit on top of fluixi" — apps get
+ * (createVitePlugin). This is what makes start "sit on top of fluixi", apps get
  * zero-config routing + SSR. Apps using `fluixi dev|build` should therefore NOT add
  * these to their own vite.config (start owns them); keep vite.config for app-specific
  * bits only (optimizeDeps, ssr.noExternal via config, etc.).
@@ -175,7 +175,7 @@ export function startTypesPlugin(cfg) {
 export async function fluixiPlugins(cfg) {
     const { fluixi, fluixiRoutesPlugin } = await import('@fluixi/core/plugins');
     const { serverFunctionsVitePlugin } = await import('@fluixi/compiler/integrations');
-    // polyfills:false — the meta-framework is SSR-first; the browser node-polyfill shims
+    // polyfills:false: the meta-framework is SSR-first; the browser node-polyfill shims
     // break server rendering. Apps that need Buffer/process in the browser opt in later.
     // serverFunctionsVitePlugin applies the "use server" transform (client RPC stub /
     // server registration) per-build via the ssr flag.
@@ -186,10 +186,18 @@ export async function fluixiPlugins(cfg) {
         // app has no way to say where an unimported tag comes from.
         //
         // `fluixi()` and not `createVitePlugin()`: the latter is the bare compiler integration,
-        // and the reactive graph — agent, source marks, /__fluixi/graph — is composed on top of
+        // and the reactive graph: agent, source marks, /__fluixi/graph, is composed on top of
         // it by the former. A start app got no graph at all until this changed.
-        fluixi({ resolve: cfg.resolve }),
+        // Everything the app declared for the compiler, with `resolve` still usable on its
+        // own because it is the one most apps set. A start app never writes
+        // `fluixi()` itself, so without this passthrough the plugin's other options
+        // (propsDestructure and the rest) had nowhere to be declared.
+        fluixi({ ...(cfg.vitePlugin ?? {}), ...(cfg.resolve ? { resolve: cfg.resolve } : {}) }),
     ];
+    // The app's own, after the framework's: a plugin that transforms css or assets runs
+    // on what the framework produced rather than racing it.
+    if (cfg.plugins?.length)
+        plugins.push(...cfg.plugins);
     // Auto-discover translations (src/i18n/<locale>.json → virtual:fluixi-i18n) unless disabled.
     if (cfg.i18n)
         plugins.push(i18nVitePlugin(cfg.i18n));
@@ -204,7 +212,7 @@ export { injectApp, splitTemplate, injectAppAndHead, guardHandler, } from './doc
 let _guardsInstalled = false;
 /**
  * A render fires the route's data fetches eagerly; if the backend is down those
- * promises can reject AFTER we've already responded, with nothing awaiting them —
+ * promises can reject AFTER we've already responded, with nothing awaiting them ,
  * a floating rejection would kill the dev server. Swallow + log instead.
  */
 export function installCrashGuards() {