fimo 0.16.0 → 0.18.0

package/assets/skills/fimo-code/references/frameworks/next/locales.md

@@ -33,6 +33,16 @@ When labels are not needed at that boundary, use `<FimoProvider locale={locale}>
 - Pages Router i18n: reuse `context.locale` in data functions and `router.locale`/page props on the client.
 - Default-only app: omit locale arguments and let Fimo use `.fimo/config.json#i18n.defaultLocale` (fallback `en`).
 
+## New-project boundary
+
+Choose the primary locale from the user's request before building pages. Put the first explicitly requested locale in `.fimo/config.json#i18n.defaultLocale` and keep all requested locales in `i18n.locales`. That edit is the whole locale setup: `src/locales.ts` reads the file, so the default locale passed to `FimoProvider`, the `<html lang>` of each tree, and the set of prefixed URLs follow it. If the user gives no locale signal, keep `en` and state that choice. Never add `NEXT_PUBLIC_FIMO_DEFAULT_LOCALE` or `FIMO_DEFAULT_LOCALE`; the runtime ignores them by design.
+
+The starter keeps default routes in an unprefixed `app/(default)` route group and a native `app/[locale]` tree for the other locales. Only a root layout may render `<html>`, so each tree owns its root layout and renders the shared `src/components/Document.tsx` with its locale: the unprefixed tree with `defaultLocale`, the prefixed tree with `params.locale`. The prefixed layout 404s a locale that is not in `prefixedLocales`, which is why the default locale has exactly one URL. For `/:locale/pricing`, `params.locale.optional: true` means omit the configured default locale: with `i18n.defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French. With `optional: false`, both `/en/pricing` and `/fr/pricing` are prefixed. The default locale value chooses the fallback locale; `optional` independently controls URL prefixes. A route without `:locale` remains application-owned.
+
+Next.js has no optional single-segment route folder, so mirror localized routes in both existing groups as the site grows. Astro uses the same paired native filesystem-tree shape for this semantic. Do not replace the trees with middleware, rewrites, an optional catch-all that captures the application route tree, or a Fimo route helper. The config route catalog describes the URL shapes for Studio; Next's `app` directory remains authoritative.
+
+Keep the starter's client-only `src/components/FimoPreviewBridge.tsx` inside `Document`, so both trees mount it. It reads Next's native pathname/router, reports the settled locale to Studio, and lets Studio navigate through Next; do not move Next imports into Fimo's shared runtime.
+
 With `next-i18next`, keep its routing and translation provider for the strings it owns. Pass the same resolved locale to Fimo; do not replace the library or duplicate its route structure.
 
 Before creating non-default Fimo labels or content variants, confirm that those locales are enabled for the linked Fimo project. Load `fimo-cli` with its `locales` reference and run `fimo locales add <locale> --yes --json`; `.fimo/config.json` documents the application's locale policy, but `fimo validate` does not add project locales.
@@ -54,6 +64,6 @@ Fimo owns:
 - client content/label context after receiving the locale;
 - editable source metadata.
 
-Do not add `.fimo/config.json#routes` to a Next project yet. The current route-metadata validator expects React Router's `src/routes.ts`; a first-class Next Studio catalog and preview bridge are separate product work. Do not create a fake `src/routes.ts` to satisfy that check.
+The new-project shell includes a small `.fimo/config.json#routes` catalog for Studio. It describes the page URLs but does not configure the App Router. Keep the `app` directory authoritative, and do not create a fake `src/routes.ts` or a universal Fimo route helper.
 
-Do not introduce `[locale]` segments, cookie routing, or domain routing unless the product request requires that URL strategy. Do not add a second locale provider when the existing one can supply the resolved locale to Fimo.
+Do not introduce new locale middleware, cookie routing, or domain routing unless the product request requires that URL strategy. Do not add a second locale provider when the existing one can supply the resolved locale to Fimo.

package/assets/skills/fimo-code/references/frameworks/next.md

@@ -82,6 +82,13 @@ Never write the registry by hand and never create alternate `*.schema.json` file
 
 ## Server and client boundaries
 
+Next.js MUST receive generated serialized values across every Server-to-Client
+Component prop boundary. Fimo values may be class-backed even when they look
+JSON-shaped. Values that stay in Server Components may stay intact; values for
+Client Components use the generated server `serialize()` and client
+`hydrate()`. Plain-JSON outputs such as Markdown, RSS, and JSON-LD also use the
+generated serialization rather than `JSON.stringify` as a conversion strategy.
+
 Forms follow the same boundary. Server actions and route handlers import the
 generated server form module; a Client Component imports its generated
 `.client.ts` module. Both expose `submitX(data)` and use the shared Fimo form

package/assets/skills/fimo-code/references/frameworks/react-router.md

@@ -85,18 +85,24 @@ Keep the application's existing `Layout` details. Add only the Fimo provider and
 
 ## Routes and locales
 
-`fimoRoutes()` is an optional helper for Fimo's path-prefix locale convention:
+React Router owns locale paths. Declare the optional locale segment directly so the default locale stays unprefixed:
 
 ```ts
 import type { RouteConfig } from '@react-router/dev/routes';
-import { index } from '@react-router/dev/routes';
-import { fimoRoutes } from 'fimo/react-router/routes';
-
-const routes = [index('./pages/Index.tsx', { id: 'home' })] satisfies RouteConfig;
-export default fimoRoutes(routes) satisfies RouteConfig;
+import { layout, route } from '@react-router/dev/routes';
+
+export default [
+  layout('./pages/LocaleLayout.tsx', [
+    route(':locale?', './pages/Index.tsx'),
+    route(':locale?/pricing', './pages/Pricing.tsx'),
+    route(':locale?/blog/:slug', './pages/BlogPost.tsx'),
+  ]),
+] satisfies RouteConfig;
 ```
 
-Custom locale routers can skip it and pass their resolved locale to `<FimoProviders locale={locale}>`. Use `FimoLink` only when the application adopts Fimo's locale-aware link behavior; otherwise preserve its links. Copyable path-prefix locale examples live in `assets/react-router-locales/`.
+Read `locale` in an application layout and pass it to `<FimoProviders locale={locale}>`; omission resolves the configured default. Copy `assets/react-router-locales/routes.ts` and `LocaleLayout.tsx` for a complete boundary. For multilingual apps, move the root provider there instead of nesting providers. Preserve an existing locale library, and use `FimoLink` only when its locale-preserving behavior matches the app.
+
+If an existing project imports `fimo/react-router/routes`, load `references/migrations/react-router-route-ownership.md` before changing it.
 
 ## Content and labels
 
@@ -122,6 +128,8 @@ Declare the runtime in `.fimo/config.json`:
 
 The optional `routes` object is Studio's semantic page catalog. Keep it aligned with application routes when the project uses Studio navigation, but do not treat it as the production router.
 
+For new projects, apply `references/locales.md`, keep the starter's `:locale?` route, and describe it in Studio metadata as `/:locale` with `params.locale.optional: true`.
+
 ## Boundaries
 
 - Route modules and `meta` exports own routing and SEO.

package/assets/skills/fimo-code/references/frameworks/sveltekit.md

@@ -74,24 +74,27 @@ do not import a Fimo environment variable or hardcode a tenant URL:
 // src/routes/+layout.server.ts
 import { getLabels } from 'fimo/sveltekit';
 
-export async function load(event) {
-  // If the app resolves a locale from its URL or session, pass it:
-  // const locale = resolveLocale(event.url); // your app's resolver
-  // return { labels: await getLabels({ event, locale }) };
+import { resolveLocale } from '../locales';
 
-  // Otherwise, omit it and use the Fimo project default.
-  return { labels: await getLabels({ event }) };
+export async function load(event) {
+  const locale = resolveLocale(event.params);
+  return { locale, labels: await getLabels({ event, locale }) };
 }
 ```
 
 ```svelte
 <!-- src/routes/+layout.svelte -->
 <script lang="ts">
+  import { afterNavigate } from '$app/navigation';
   import { FimoProvider } from 'fimo/sveltekit/components';
   import type { LayoutData } from './$types';
   import type { Snippet } from 'svelte';
 
   let { data, children }: { data: LayoutData; children: Snippet } = $props();
+
+  afterNavigate(() => {
+    document.documentElement.lang = data.locale;
+  });
 </script>
 
 <FimoProvider labels={data.labels}>
@@ -101,7 +104,7 @@ export async function load(event) {
 
 Generated values are serialized at a `load` boundary and hydrated in the
 component that renders them. Use `Text`, `RichText`, `Image`, `Video`, `Date`,
-`Boolean`, `Json`, and `Number` from `fimo/sveltekit/components`. `Number`
+`DateTime`, `Boolean`, `Json`, and `Number` from `fimo/sveltekit/components`. `Number`
 formats plain numeric values for display; numeric fields currently have no
 source metadata, so it is not a Studio-editable primitive.
 
@@ -128,7 +131,7 @@ export const actions = {
 `PUBLIC_FIMO_PREVIEW_SCRIPT_URL` from SvelteKit's dynamic public environment,
 loads that script once, delegates navigation to SvelteKit's `goto`, and
 refreshes data with `invalidateAll()`. Without that environment value it does
-nothing. Do not add a Fimo server hook or a second preview component.
+nothing. Do not add a second preview component.
 
 ## Boundaries
 
@@ -136,3 +139,7 @@ nothing. Do not add a Fimo server hook or a second preview component.
 - `fimo/sveltekit/vite` owns dev source tagging only.
 - `FimoProvider` owns labels and the optional Studio preview bridge.
 - Do not add React, React Query, or a Vite SPA fallback to a SvelteKit project.
+
+The starter uses SvelteKit's native `[[locale=locale]]` boundary and a matcher limited to configured, non-default locales, so unrelated top-level paths are not locales. `src/locales.ts` derives the default and prefixed set from `.fimo/config.json` and owns the shared locale resolver. Keep passing the tracked `event.params` object into that resolver from the root server layout so locale-crossing client navigation reruns labels.
+
+For accessibility, SvelteKit's documented multilingual pattern renders `<html lang="%lang%">` through `src/hooks.server.ts#transformPageChunk`. The root layout updates the attribute after client navigation. Keep those seams aligned with the application's locale resolver. Keep `[[locale=locale]]` for an unprefixed default; use `[locale=locale]` only when every locale must be prefixed.

package/assets/skills/fimo-code/references/labels.md

@@ -32,7 +32,7 @@ const items = [
 
 Do not use variables or interpolated expressions as label keys. Namespace literal keys by page/section/component, such as `hero.title`, `nav.signIn`, or `contact.form.submit`.
 
-Missing keys render as an empty tracked value. Run `fimo validate`, then create values with `fimo labels set` or `set-many`; do not add fallback copy to code.
+Missing keys render as an empty tracked value. Run `fimo validate`, then create values with `fimo labels set` or `set-many`; do not add fallback copy to code (the one exception is a component that cannot mount under the provider — see "Provider mount" below).
 
 ## Framework adapters
 
@@ -46,6 +46,14 @@ The label contract is shared; acquisition differs by runtime:
 
 Load the matching framework reference before choosing a provider or server reader.
 
+## Provider mount
+
+Components that render `Label` or call `useLabels()` MUST be mounted below the framework's `FimoProvider` (or the framework integration that supplies label context). Globally mounted components — cookie banners, toasts, consent dialogs injected near the document root — are the common escapees: outside the provider they render blank labels with no error.
+
+If a component genuinely cannot be moved under the provider, use an explicit hardcoded, non-editable fallback and report that tradeoff to the user. Never ship silently blank copy.
+
+When a label renders empty, check in order: (1) the key exists (`fimo validate`, `fimo labels list`), (2) the active locale has a value, (3) the component is under the provider. Add fallback copy only after those checks, and only in the cannot-mount case above.
+
 ## Locale behavior
 
 `.fimo/config.json#i18n.defaultLocale` selects the default (fallback `en`). The application resolves the active locale and gives it to the framework adapter. Create explicit label values for each configured locale the product supports.

package/assets/skills/fimo-code/references/locales.md

@@ -13,7 +13,9 @@ The application owns locale resolution and routing. Fimo consumes the resolved l
 }
 ```
 
-Keep one locale unless the product asks for multilingual output. Locale tags should be structurally valid, such as `en`, `pt-BR`, or `zh-Hans`.
+For new projects, derive the primary locale from the request; when several are explicit, the first one named is the default. Update `i18n.defaultLocale`, `i18n.locales`, the framework-native route boundary and matcher, and the document language default. If the user gives no locale signal, retain the starter default and state that choice.
+
+Keep one locale unless the product asks for multilingual output. Keep it locale-ready without forcing `/en`, a language switcher, global path-prefix routing, or localized schemas. Locale tags should be structurally valid, such as `en`, `pt-BR`, or `zh-Hans`.
 
 For an already linked project, enable each locale in Fimo before writing non-default label or content variants. Load `fimo-cli` with its `locales` reference and run `fimo locales add <locale> --yes --json`; local config and `fimo validate` do not provision project locales. Do not change the application's route strategy to work around a missing locale.
 
@@ -22,6 +24,8 @@ For an already linked project, enable each locale in Fimo before writing non-def
 - Resolve locale from its router, route parameters, domain, request headers, middleware, cookie, existing i18n library, or user preference.
 - Keep its existing public URLs, redirects, links, `<html lang/dir>`, and SEO behavior.
 - Pass the resolved locale to Fimo's server reads and client provider.
+- Keep the default locale separate from the URL prefix policy. `optional: true` means omit the configured default locale from the URL: with `defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French. With `optional: false`, every locale is prefixed (`/en/pricing` and `/fr/pricing`).
+- Treat routes without a `:locale` segment as application-owned. Fimo does not add or interpret a locale prefix for them.
 - Treat any optional Studio route catalog as framework-adapter-specific; load the framework reference before creating or changing one.
 
 ## Fimo responsibilities
@@ -39,4 +43,6 @@ For an already linked project, enable each locale in Fimo before writing non-def
 - React Router standard locale routing → load `references/frameworks/react-router.md`.
 - Vite + React/custom React router → load `references/frameworks/vite-react.md` and pass locale through its existing provider seam.
 
-Do not replace an existing locale system merely to add Fimo. Do not duplicate localized routes in the Studio catalog. Do not assume Fimo's route helpers are universal framework APIs.
+Do not replace an existing locale system merely to add Fimo. Do not duplicate localized routes in the Studio catalog. Every framework resolves its active locale and passes it to Fimo through that framework's provider or server-read seam.
+
+Astro and Next implement an optional locale boundary with paired native filesystem route trees: one unprefixed tree for the default locale and one prefixed tree for the other locales. Neither framework has an optional single-segment filesystem folder.

package/assets/skills/fimo-code/references/migrations/react-router-route-ownership.md

@@ -0,0 +1,93 @@
+# React Router locale route ownership upgrade
+
+Use this guide to move an existing project from the deprecated
+`fimo/react-router/routes` compatibility adapter to application-owned React
+Router routes. Existing projects can upgrade before completing this migration,
+but new projects should not use the adapter and a future breaking release may
+remove it.
+
+## Identify the installed contract
+
+Run the project-local CLI with the package manager selected by the lockfile:
+
+```bash
+pnpm exec fimo --version
+```
+
+Then inspect `package.json`, the lockfile, `src/routes.ts`, the locale layout or
+provider, `.fimo/config.json` (or legacy `fimo-config.json`), the language
+selector, redirects, and SEO/static-generation setup. The installed package is
+authoritative. Do not use a newer globally installed CLI to rewrite the app.
+
+Choose the path by the installed and target contracts, not by a guessed
+version number:
+
+| Installed project                     | Target project  | Action                                                                    |
+| ------------------------------------- | --------------- | ------------------------------------------------------------------------- |
+| Uses `fimo/react-router/routes`       | Current release | Upgrade safely, then follow this guide to leave the deprecated adapter.   |
+| Already uses application-owned routes | Later release   | Keep the app-owned routes; no routing migration is needed.                |
+| Uses another router or framework      | Any release     | Keep that framework's locale system and pass its resolved locale to Fimo. |
+
+The package export and `pnpm exec fimo --version` are the reliable boundary
+until release notes assign concrete version numbers.
+
+## Replace the deprecated route wrapper
+
+Remove the `fimo/react-router/routes` import and declare each localized path
+directly. React Router uses `:locale?`; route metadata uses `/:locale` with an
+optional locale descriptor:
+
+```ts
+import type { RouteConfig } from '@react-router/dev/routes';
+import { layout, route } from '@react-router/dev/routes';
+
+export default [
+  layout('./pages/LocaleLayout.tsx', [
+    route(':locale?/pricing', './pages/Pricing.tsx'),
+    route(':locale?/blog/:slug', './pages/BlogPost.tsx'),
+  ]),
+] satisfies RouteConfig;
+```
+
+Keep the public URL matrix unchanged:
+
+| URL             | route     | active locale      |
+| --------------- | --------- | ------------------ |
+| `/pricing`      | pricing   | configured default |
+| `/es/pricing`   | pricing   | `es`               |
+| `/blog/hello`   | blog post | configured default |
+| `/es/blog/hola` | blog post | `es`               |
+
+Do not add a default-locale prefix. Read the optional route locale in an
+application-owned layout and pass it to `<FimoProviders locale={locale}>`.
+When it is omitted, FimoProviders resolves the configured default locale.
+Preserve existing redirects, link behavior, document language/direction, and
+locale validation.
+
+The copyable boundary is:
+
+```tsx
+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>
+  );
+}
+```
+
+## Verify before finishing
+
+Run the project-local `fimo validate`, then verify all four URL shapes in the
+preview. Switch languages in the application selector and in Studio, and check
+that both report the same locale. Confirm canonical URLs, `hreflang`, sitemap or
+prerender output, and locale-specific metadata/content remain correct.
+
+If the installed version has no exact matching reference, preserve every
+existing public URL and routing behavior. Report the installed version, the
+pattern found, the checks completed, and any uncertainty instead of guessing a
+new route shape.

package/assets/skills/fimo-code/references/ui.md

@@ -9,7 +9,8 @@ Use Fimo components for source-tracked schema and label values so Studio can ide
 | media as `FimoMedia`             | `Image`                        | schema media images                                                |
 | non-schema URL                   | `StaticImage`                  | decorative/static image URLs                                       |
 | media as `FimoMedia`             | `Video`                        | schema media videos                                                |
-| date as `FimoString`             | `Date`                         | schema dates                                                       |
+| date as `FimoString`             | `Date`                         | schema dates; `<time datetime>` is the calendar day                |
+| datetime as `FimoString`         | `DateTime`                     | schema instants; `<time datetime>` keeps the time                  |
 | boolean as `FimoBoolean`         | `Boolean`                      | schema booleans                                                    |
 | source-tagged plain JSON         | `Json`                         | schema JSON                                                        |
 | number                           | normal JSX; SvelteKit `Number` | numbers stay plain; SvelteKit `Number` formats display-only values |
@@ -21,6 +22,7 @@ Use Fimo components for source-tracked schema and label values so Studio can ide
 <RichText value={article.body} />
 <Image value={article.cover} width={1200} height={630} />
 <Date value={article.publishedAt} />
+<DateTime value={article.lastReviewedAt} />
 ```
 
 Pass the tracked value directly. Do not replace `<Text>` with `<h1>{article.title}</h1>`, unwrap media into raw `<img>`, or hand-roll richtext rendering.
@@ -44,7 +46,24 @@ Blocks do not change this rule. Every visible nested scalar is source-tracked to
 
 Do not render those values as `{program.title}` or `{highlight.label}`. That displays text but bypasses the primitive that Studio uses to resolve the exact nested edit target.
 
-Use `<StaticImage>` only when the image is deliberately not editor-managed. Use `String(value)` for attributes/third-party APIs that cannot accept a `FimoString`; keep editable visible text in `<Text>`.
+Use `<StaticImage>` only when the image is deliberately not editor-managed.
+
+## Wrapper values in JavaScript logic
+
+`FimoString`, `FimoBoolean`, and the other tracked values are objects, not primitives: a plain string or boolean cannot carry the source field, locale, and edit-target metadata Fimo editing needs. That gives one two-sided rule:
+
+- **MUST** pass the wrapper directly to Fimo rendering primitives (`Text`, `Boolean`, …). Unwrapping first removes the edit target.
+- **MUST** normalize the wrapper before any JavaScript comparison, condition, attribute, or third-party API: `String(value)` for strings, `value.value` (or `value.valueOf()`) for booleans.
+
+```ts
+fimoValue === 'build';         // false — an object never strict-equals a primitive
+String(fimoValue) === 'build'; // true
+
+if (fimoFlag) { … }            // always runs — an object is truthy even when the value is false
+if (fimoFlag.value) { … }      // correct
+```
+
+Keep editable visible text in `<Text>`; normalized primitives are for logic and APIs only, never a substitute for rendering through the primitive.
 
 Numeric fields stay plain JavaScript numbers, so they do not carry Studio source metadata. SvelteKit's `Number` component is an optional display/formatting helper; it is not source-editable. Other framework surfaces should render numeric fields normally until a shared tracked-number contract exists.