fimo 0.17.0 → 0.18.0

package/templates/nextjs/src/components/Document.tsx

@@ -0,0 +1,26 @@
+import { FimoProvider } from 'fimo/next/client';
+import type { ReactNode } from 'react';
+
+import FimoPreviewBridge from './FimoPreviewBridge';
+
+/**
+ * The HTML document for one locale tree. Only a root layout may render `<html>`
+ * in the App Router, so each locale tree has its own root layout and renders
+ * this with the locale that tree serves. That is what makes `<html lang>` and
+ * the Fimo locale context correct on both the unprefixed and prefixed routes.
+ */
+export default function Document({ children, locale }: Readonly<{ children: ReactNode; locale: string }>) {
+  const previewScriptUrl = process.env.NEXT_PUBLIC_FIMO_PREVIEW_SCRIPT_URL;
+
+  return (
+    <html lang={locale}>
+      <body>
+        <FimoProvider locale={locale}>
+          <FimoPreviewBridge />
+          {children}
+        </FimoProvider>
+        {previewScriptUrl ? <script src={previewScriptUrl} defer /> : null}
+      </body>
+    </html>
+  );
+}

package/templates/nextjs/src/components/FimoPreviewBridge.tsx

@@ -0,0 +1,13 @@
+'use client';
+
+import { FimoPreviewBridge as RuntimeFimoPreviewBridge } from 'fimo/next/client';
+import { usePathname, useRouter } from 'next/navigation';
+import { useCallback } from 'react';
+
+export default function FimoPreviewBridge() {
+  const pathname = usePathname();
+  const router = useRouter();
+  const navigate = useCallback((to: string) => router.push(to), [router]);
+
+  return <RuntimeFimoPreviewBridge pathname={pathname} navigate={navigate} />;
+}

package/templates/nextjs/src/locales.ts

@@ -0,0 +1,13 @@
+import fimoConfig from '../.fimo/config.json';
+
+/**
+ * Locale policy read from the same file Fimo and Studio read, so the site
+ * language cannot drift from the project configuration. Change the locales in
+ * `.fimo/config.json#i18n`; nothing here needs editing.
+ */
+export const defaultLocale: string = fimoConfig.i18n.defaultLocale;
+
+/** Only non-default locales carry a URL prefix; the default locale stays at the site root. */
+export const prefixedLocales: ReadonlySet<string> = new Set(
+  fimoConfig.i18n.locales.filter((locale) => locale !== defaultLocale)
+);

package/templates/react-router/.fimo/config.json

@@ -11,16 +11,13 @@
   },
   "i18n": {
     "defaultLocale": "en",
-    "locales": ["en"],
-    "routing": {
-      "strategy": "path-prefix",
-      "prefixDefaultLocale": false
-    }
+    "locales": ["en"]
   },
   "routes": {
     "home": {
       "label": "Home",
-      "path": "/",
+      "path": "/:locale",
+      "params": { "locale": { "type": "locale", "optional": true } },
       "seo": {
         "title": "Home",
         "description": "Welcome"

package/templates/react-router/AGENTS.md

@@ -40,6 +40,10 @@ breaks that. Load `fimo-code` for the exact primitives, but the rule is:
 ## Project rules
 
 - **Deploy is on-demand**, not a save step. Batch related edits into one deploy.
+- With pnpm, run `pnpm install --config.dangerouslyAllowAllBuilds=true`; a bare install can skip the build scripts required by Fimo and the framework toolchain.
+- Treat the user's language request as part of setup. The first explicitly requested locale is the primary locale; put it first and set it as `i18n.defaultLocale` in `.fimo/config.json`. If no language is requested, keep `en` and state that choice.
+- Preserve the application-owned `:locale?` route boundary in `src/routes.ts` and pass its route parameter to `FimoProviders` in `LocaleLayout.tsx`. The missing parameter uses the configured default, so a one-locale site stays at `/`. Add locales in `.fimo/config.json` without rebuilding the route tree; use `:locale` without `?` only when every locale must be prefixed.
+- Keep `.fimo/config.json#routes` aligned as Studio metadata, not as the React Router source of truth. Do not add a global locale-routing strategy, a Fimo route helper, or a Fimo-owned route tree.
 - Do not add a second deploy tool (Vercel, Netlify, etc.).
 - **Never edit `.fimo/project.json`** — it links this folder to the remote project.
 - **Keep `.fimo/config.json#runtime` true to the code** — framework, `dev`/`build`/`install` commands, output directory. Update it when you rename a package script, move the build output, or change framework; the reference is `fimo skills get fimo-code --ref frameworks/hosting`.

package/templates/react-router/package.json

@@ -21,7 +21,7 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "0.17.0",
+    "fimo": "0.18.0",
     "input-otp": "^1.4.2",
     "isbot": "^5",
     "lucide-react": "^0.577.0",

package/templates/react-router/pnpm-workspace.yaml

@@ -5,6 +5,4 @@
 # (ERR_PNPM_CONFIG_CONFLICT_BUILT_DEPENDENCIES), which makes sandbox installs
 # fail before the project's `fimo` dep is available.
 
-allowBuilds:
-  esbuild: true
-  fimo: true
+packages: []

package/templates/react-router/react-router.config.ts

@@ -5,16 +5,10 @@ export default {
   appDirectory: 'src',
   ssr: false,
   presets: [fimoPreset()],
-  // Static-site generation is opt-in. By default this template builds as an
-  // SPA (single index.html shell, client-side routing). To prerender routes at
-  // build time — required for crawler-visible per-route SEO — add this line:
-  //
-  //   import { getFimoPaths } from 'fimo/paths';
-  //   prerender: async () => (await getFimoPaths()).map((p) => p.path),
-  //
-  // `getFimoPaths()` expands dynamic routes (e.g. `/blog/:slug`) by fetching
-  // schema entries from the content API. See `references/frameworks/react-router.md`
-  // in the fimo skill for the full setup pattern.
+  // Pages metadata is optional Studio editing context; it does not configure
+  // the app router or build-time paths. Existing projects that still need the
+  // legacy sitemap/simple-SSG helper can import `fimo/paths` in their own build
+  // configuration.
   buildDirectory: 'dist',
   // Feed Vite's dependency scanner the client entry + every route module.
   // Without it React Router hands Vite an EMPTY entry list, nothing is

package/templates/react-router/src/pages/LocaleLayout.tsx

@@ -0,0 +1,12 @@
+import { FimoProviders } from 'fimo/react-router';
+import { Outlet, useParams } from 'react-router';
+
+export default function LocaleLayout() {
+  const { locale } = useParams();
+
+  return (
+    <FimoProviders locale={locale}>
+      <Outlet />
+    </FimoProviders>
+  );
+}

package/templates/react-router/src/root.tsx

@@ -1,5 +1,5 @@
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { FimoProviders, FimoScripts, loadFimoMetaData, buildFimoMeta, fimoHtmlProps } from 'fimo/react-router';
+import { FimoScripts, loadFimoMetaData, buildFimoMeta, fimoHtmlProps } from 'fimo/react-router';
 import React from 'react';
 import type { MetaFunction } from 'react-router';
 import { Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
@@ -45,9 +45,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
 export default function AppRoot() {
   return (
     <QueryClientProvider client={queryClient}>
-      <FimoProviders>
-        <Outlet />
-      </FimoProviders>
+      <Outlet />
     </QueryClientProvider>
   );
 }

package/templates/react-router/src/routes.ts

@@ -1,5 +1,5 @@
-import { index } from '@react-router/dev/routes';
-import { fimoRoutes } from 'fimo/react-router/routes';
+import type { RouteConfig } from '@react-router/dev/routes';
+import { layout, route } from '@react-router/dev/routes';
 
 // Examples of React Router route patterns:
 //   index('./pages/Index.tsx'),
@@ -12,4 +12,6 @@ import { fimoRoutes } from 'fimo/react-router/routes';
 //     route('settings', './pages/dashboard/Settings.tsx'),
 //   ]),
 
-export default fimoRoutes([index('./pages/Index.tsx', { id: 'home' })]);
+export default [
+  layout('./pages/LocaleLayout.tsx', [route(':locale?', './pages/Index.tsx', { id: 'home' })]),
+] satisfies RouteConfig;

package/templates/sveltekit/.fimo/config.json

@@ -7,7 +7,8 @@
   "routes": {
     "home": {
       "label": "Home",
-      "path": "/"
+      "path": "/:locale",
+      "params": { "locale": { "type": "locale", "optional": true } }
     }
   },
   "version": "4",

package/templates/sveltekit/AGENTS.md

@@ -27,6 +27,11 @@ a code-only task, or use `npx fimo@latest` for project-local code generation and
 ## Project rules
 
 - **Deploy is on-demand**, not a save step. Batch related edits into one deploy.
+- With pnpm, run `pnpm install --config.dangerouslyAllowAllBuilds=true`; a bare install can skip the build scripts required by Fimo and the framework toolchain.
+- Treat the user's language request as part of setup. The first explicitly requested locale is the primary locale; put it first and set it as `i18n.defaultLocale` in `.fimo/config.json`. If no language is requested, keep `en` and state that choice. `src/locales.ts` derives the default and prefixed locale set from that config.
+- Preserve the native `[[locale=locale]]` route boundary. The optional parameter keeps the default locale at `/`; the matcher prevents ordinary top-level routes from being mistaken for locales. The root server layout passes the tracked `event.params` through `resolveLocale`, then sends that locale to `getLabels` and `FimoProvider`. Remove the extra brackets only when every locale must be prefixed.
+- Keep the document language request-aware: `src/hooks.server.ts` renders the initial `<html lang>`, and the root layout updates it after client navigation.
+- Keep `.fimo/config.json#routes` as Studio metadata aligned with SvelteKit's route files. It does not configure SvelteKit routing.
 - The application owns routes, locale resolution, links, HTML language/direction, and SEO. Fimo connects to those decisions.
 - Do not add a second deployment platform.
 - Never edit `.fimo/project.json`; it links this directory to the remote project.

package/templates/sveltekit/src/app.html

@@ -1,5 +1,5 @@
 <!doctype html>
-<html lang="en">
+<html lang="%lang%">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width" />

package/templates/sveltekit/src/hooks.server.ts

@@ -0,0 +1,11 @@
+import type { Handle } from '@sveltejs/kit';
+
+import { resolveLocale } from './locales';
+
+export const handle: Handle = ({ event, resolve }) => {
+  const locale = resolveLocale(event.params);
+
+  return resolve(event, {
+    transformPageChunk: ({ html }) => html.replace('%lang%', locale),
+  });
+};

package/templates/sveltekit/src/locales.ts

@@ -0,0 +1,8 @@
+import fimoConfig from '../.fimo/config.json';
+
+export const defaultLocale: string = fimoConfig.i18n.defaultLocale;
+export const prefixedLocales = new Set(fimoConfig.i18n.locales.filter((locale) => locale !== defaultLocale));
+
+export function resolveLocale(params: { locale?: string }): string {
+  return params.locale ?? defaultLocale;
+}

package/templates/sveltekit/src/params/locale.ts

@@ -0,0 +1,5 @@
+import type { ParamMatcher } from '@sveltejs/kit';
+
+import { prefixedLocales } from '../locales';
+
+export const match = ((locale: string) => prefixedLocales.has(locale)) satisfies ParamMatcher;

package/templates/sveltekit/src/routes/+layout.server.ts

@@ -1,7 +1,12 @@
 import { getLabels } from 'fimo/sveltekit';
 
+import { resolveLocale } from '../locales';
+
 export async function load(event) {
+  const locale = resolveLocale(event.params);
+
   return {
-    labels: await getLabels({ event }),
+    locale,
+    labels: await getLabels({ event, locale }),
   };
 }

package/templates/sveltekit/src/routes/+layout.svelte

@@ -1,10 +1,15 @@
 <script lang="ts">
+  import { afterNavigate } from '$app/navigation';
   import { FimoProvider } from 'fimo/sveltekit/components';
   import type { Snippet } from 'svelte';
 
   import type { LayoutData } from './$types';
 
   let { data, children }: { data: LayoutData; children: Snippet } = $props();
+
+  afterNavigate(() => {
+    document.documentElement.lang = data.locale;
+  });
 </script>
 
 <FimoProvider labels={data.labels}>

package/assets/skills/fimo-migration/references/inventory/coordinator.md

@@ -1,40 +0,0 @@
-# Deterministic inventory coordination
-
-Prepare before running lanes:
-
-```bash
-fimo migrate inventory <project-root> --prepare
-```
-
-Read `inventory-plan.json`, then run each listed area in an independent worker
-that treats application source as read-only:
-
-```bash
-fimo migrate inventory <project-root> --area runtime-config
-fimo migrate inventory <project-root> --area locales
-```
-
-Run only areas present in the plan. The `locales` area is currently planned
-only when the source package manifest declares `next-intl`.
-
-Workers must return the written deterministic fragment, not a prose summary.
-They must read only the source root and write only their planned fragment and
-execution receipt. A worker may report structured unresolved claims in its
-fragment; process outcome and timing belong in the run receipt.
-
-If independent workers are unavailable, run the same areas sequentially:
-
-```bash
-fimo migrate inventory <project-root> --sequential
-```
-
-After every fan-out, run deterministic fan-in:
-
-```bash
-fimo migrate inventory <project-root> --reconcile
-```
-
-Use a separate validator worker that did not produce fragments to compare the
-plan, source evidence, fragments, and unresolved claims. If it finds a gap,
-reopen only the affected area and reconcile again. The CLI never starts an
-LLM or chooses a harness.

package/assets/skills/fimo-migration/references/inventory/locales/next-intl.md

@@ -1,39 +0,0 @@
-# next-intl locale inventory
-
-Use the shipped analyzer after `package.json` proves a next-intl dependency:
-
-```bash
-node <this-skill>/scripts/inventory/locales/next-intl.mjs <source-root>
-```
-
-It detects conventional JSON dictionaries, JSON imports with one dynamic locale
-segment, and static `defineRouting` locale/default-locale values. It emits
-deterministic facts and file/line evidence without changing the source.
-
-If request configuration does not reveal a custom JSON dictionary layout, let
-the agent select one relative pattern containing `{locale}` exactly once:
-
-```bash
-node <this-skill>/scripts/inventory/locales/next-intl.mjs <source-root> \
-  --messages-pattern 'src/translations/{locale}/common.json'
-```
-
-The script rejects absolute paths, paths outside the source root, non-JSON
-patterns, and ambiguous placeholders.
-
-## Support boundary
-
-The analyzer intentionally leaves a claim unresolved when its static source
-shape is unknown. Current gaps include:
-
-- locales/default locale declared only through legacy middleware or navigation
-  helpers;
-- dynamic or remote locale configuration;
-- non-JSON dictionaries such as extracted PO catalogs;
-- public route reachability.
-
-Treat package version as evidence that helps prioritize likely source shapes,
-not as the primary switch. If the analyzer cannot prove a claim, follow the
-temporary read-only strategy in `references/inventory/locales.md`. A zero exit
-code means the analyzer ran successfully; read `unresolved[]` as the exact
-claims still requiring evidence.

package/assets/skills/fimo-migration/references/inventory/locales.md

@@ -1,41 +0,0 @@
-# Locale inventory
-
-Inventory locale evidence without deciding that every dictionary is configured
-or publicly routable.
-
-## Evidence contract
-
-Keep these facts distinct:
-
-- **dictionary candidates**: locale-like values derived from message files or
-  records;
-- **configured locales**: values proven by static application configuration;
-- **default locale**: one statically proven fallback when present;
-- **public locales**: values proven reachable through the application's routes;
-- **unresolved claims**: individual facts that no strategy proved.
-
-A successful script run means evidence collection executed correctly. It does
-not mean every locale claim is known. Preserve proven facts when another claim
-remains unresolved.
-
-## Bounded fallback
-
-1. Run the shipped strategy for the detected locale system.
-2. If the dictionary layout is the only unknown, pass a supported bounded path
-   pattern to that strategy.
-3. If a claim remains unresolved, inspect only the files likely to own it.
-4. When repeated manual reads would be slower or less reliable, let the agent
-   create one disposable script in the harness or operating-system temporary
-   directory, outside the application source tree. The script must:
-   - read only the selected source root;
-   - perform no network calls or source writes;
-   - have explicit file, byte, or time bounds;
-   - print deterministic facts, evidence paths, and unresolved claims;
-   - avoid claiming route reachability from dictionary files alone.
-5. Validate the output, copy its evidence into the canonical ledger, and remove
-   the temporary script. Do not commit it to the migrated application.
-6. At fan-in, compare configured, default, dictionary, and public locales. Keep
-   every mismatch or unproven claim unresolved until evidence settles it.
-
-If the same temporary strategy is needed repeatedly across migrations, turn it
-into a tested shipped script in a separate Fimo change.