fimo 0.12.0 → 0.12.1

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

@@ -0,0 +1,225 @@
+# Setup Fimo on plain Vite + React
+
+Use this recipe for a Vite + React SPA without React Router framework mode.
+This is also the upgrade path for legacy Fimo v3 projects — v3 was plain Vite,
+so this layout is what those projects look like now.
+
+## When to use this vs. React Router
+
+- **Plain Vite (this recipe):** simplest setup; client-side routing via a
+  React Router library router (`BrowserRouter`, no framework-mode SSR/SSG);
+  SEO via build-time HTML rewrite. Per-route SEO that crawlers see requires
+  prerendering (SSG); without it, the SPA serves one `index.html` for every
+  URL and crawlers see only the home SEO.
+- **React Router (`references/frameworks/react-router.md`):** framework-mode SSR + per-route
+  SEO via `meta` export; recommended when you want real per-route crawler SEO.
+
+## Prerequisites
+
+- Node 20+
+- A Fimo project created via `fimo init`.
+
+## Install
+
+```
+pnpm add fimo react react-dom react-router @tanstack/react-query
+pnpm add -D vite @vitejs/plugin-react @types/react @types/react-dom typescript
+```
+
+## File: `package.json`
+
+```json
+{
+  "name": "__PROJECT_SLUG__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 0.0.0.0 --port 5173",
+    "build": "vite build",
+    "preview": "vite preview --host 0.0.0.0 --port 4173",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+## File: `vite.config.ts`
+
+```ts
+import { defineConfig } from 'vite';
+
+import { fimo } from 'fimo/vite';
+
+export default defineConfig(() => ({
+  plugins: fimo({ seo: true }),
+}));
+```
+
+Notes:
+
+- `fimo({ seo: true })` opts in to the build-time SEO plugin
+  (`transformIndexHtml`-based). This is the right tool for plain Vite — there's
+  no framework `meta` export to plug into.
+- Add `fimo({ seo: true, sitemap: true, robots: true })` to also emit
+  `sitemap.xml` and `robots.txt` at build.
+
+## File: `index.html`
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__PROJECT_SLUG__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+The `seo` plugin rewrites `<title>`, og, twitter, canonical tags from
+`.fimo/config.json#seo` at build time. You can leave a placeholder title in
+`index.html`; it'll be replaced.
+
+## File: `src/main.tsx`
+
+`FimoProviders` requires a React Router `<Router>` ancestor (it reads
+`useLocation`/`useNavigate`). It reuses a host app's
+`@tanstack/react-query` client when one exists and supplies a stable fallback
+for adopted SPAs. This recipe still mounts an explicit provider so the app owns
+the shared cache and its configuration:
+
+```tsx
+import { FimoProviders } from 'fimo/react-router';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router';
+
+import { App } from './App';
+
+const queryClient = new QueryClient();
+
+createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <FimoProviders>
+          <App />
+        </FimoProviders>
+      </BrowserRouter>
+    </QueryClientProvider>
+  </React.StrictMode>
+);
+```
+
+`react-router` and `@tanstack/react-query` are peer dependencies of `fimo`;
+both are in the install command above. `FimoProviders` is exported only from
+the `fimo/react-router` adapter barrel. Keep the explicit QueryClientProvider
+when the app needs custom query defaults or shared cache access; adopted SPAs
+can omit it.
+
+## File: `src/App.tsx`
+
+```tsx
+import { Text, useLabels } from 'fimo/ui';
+
+export function App() {
+  const { t } = useLabels();
+
+  return (
+    <main>
+      <Text value={t('home.hero.title')} as="h1" />
+    </main>
+  );
+}
+```
+
+## File: `.fimo/config.json`
+
+```json
+{
+  "version": "3",
+  "seo": {
+    "title": "__PROJECT_SLUG__",
+    "siteName": "__PROJECT_SLUG__"
+  },
+  "routes": {
+    "home": {
+      "label": "Home",
+      "path": "/"
+    }
+  }
+}
+```
+
+Note: `"version": "3"` marks the legacy plain-Vite (no-RR-framework-mode)
+shape. `fimo()` is version-agnostic — it composes a fixed set of build-time
+plugins from the `seo`/`sitemap`/`robots` options you pass and never reads
+this version field. It also never injects the React Router plugin: in a
+framework-mode project that `reactRouter()` plugin is added by your own
+`vite.config.ts`, not by `fimo/vite`.
+
+## File: `.fimo/project.json`
+
+```json
+{
+  "projectId": "__PROJECT_ID__",
+  "organizationId": "__ORG_ID__",
+  "apiUrl": "__API_URL__"
+}
+```
+
+## File: `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "*.config.ts"]
+}
+```
+
+## Verify and iterate
+
+Run the app with the project's package-manager `dev` script (`pnpm dev` /
+`npm run dev` / `yarn dev` / `bun dev` — match the lockfile). It serves the site
+on localhost with live reload — this is your iteration loop: edit, see the change,
+repeat with the developer. `fimo deploy` is on-demand (hosted preview / shareable
+link / go live), run only on the developer's signal; the dashboard's preview iframe
+shows the **deployed** app, not the localhost dev server.
+
+## Known limitations vs. React Router
+
+- **Per-route SEO that crawlers see** requires either (a) using React Router
+  framework mode with prerender, (b) a Vite SSG plugin like `vite-plugin-ssg`,
+  or (c) accepting that the crawler sees the home SEO for every URL.
+- **Dashboard "live edit SEO" preview** requires a reload on plain Vite —
+  there's no React-side head-mutation component yet. The static `seo` plugin
+  bakes SEO at build time.
+- **Routing**: `FimoProviders` requires a React Router context, so this recipe
+  wires `BrowserRouter` from `react-router`. You can swap it for another
+  React Router setup (e.g. a `createBrowserRouter` data router with
+  `<RouterProvider>`), but a `<Router>` ancestor is mandatory — the runtime's
+  preview bridge and pageview tracker call `useLocation`/`useNavigate`.
+
+## What to do next
+
+- Add a sitemap: pass `fimo({ seo: true, sitemap: true })` and set
+  `.fimo/config.json#seo.url` to your production base URL.
+- Look up exports: see `references/ui.md`.
+- Use schema content: see `references/content.md`.

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

@@ -1,102 +1,43 @@
-# Labels — package surface
+# Labels
 
-> For the CLI workflow (`fimo validate`, `fimo labels set`, bulk updates), see **`fimo-cli/references/labels.md`**.
-> For locale-aware routing and links (`fimoRoutes`, `FimoLink`, custom framework contract), see **`references/locales.md`**.
+Labels are project-wide, locale-scoped, editor-managed static copy. Use them for headings, navigation, CTAs, placeholders, empty states, alt text, and metadata. Structured editor content belongs in schemas instead.
 
-This file covers the **package surface**: the `t()` helper, the `useLabels()` hook, and the code-side rules for wrapping strings.
+For label CLI writes and missing-key validation, load `fimo-cli/references/labels.md`.
 
-## The rule
-
-Every piece of **user-facing static text** in the app (page titles, button labels, nav items, form placeholders, empty-state copy, alt text, meta tags) MUST be wrapped in `t('key')`.
-
-Raw string literals in JSX are a bug — they won't show up in the Fimo admin as editable content and won't be translatable. **Hard-coded JSX text (`<h1>Welcome</h1>`) skips the entire i18n + inline-editing pipeline and becomes invisible to the editor.**
-
-## Setup (already wired)
-
-Labels are wired automatically by the `fimo/vite` build plugin. `useLabels()` reads DB-backed label values for the active locale — there's no provider to add or remove. The app entry is `src/root.tsx`, which wraps the app in `<FimoProviders>` from `fimo/react-router`. Pages and components call `useLabels()`.
-
-`useTranslations()` is kept as a legacy alias for older projects. Use `useLabels()` in new code.
-
-In development, the generated app reloads when DB label values change. In production, the build embeds the DB-backed label bundle.
-
-## Locale behavior
-
-The default label locale is `i18n.defaultLocale` in `.fimo/config.json`, falling back to `en` when it is not set. `fimo validate`, the generated app runtime, and `fimo labels set` without `--locale` all use that default locale.
-
-For non-default locales, create explicit DB values with `fimo labels set --locale <locale>` or `fimo labels set-many --locale <locale>`. Keep the code shape the same for every locale: `t('hero.title')` declares the key, and the DB decides which locale value is shown.
-
-`.fimo/config.json` owns the locale list:
-
-```json
-{
-  "i18n": {
-    "defaultLocale": "en",
-    "locales": ["en"]
-  }
-}
-```
-
-- `locales` is the enabled locale list and must include `defaultLocale`. Do not add non-default locales unless the user asks for multiple languages, localized routes, translations, or a specific locale.
-- If multiple locales are configured, create or update label values for every configured locale.
-- Public locale routing is project/framework code. In React Router projects, prefer `fimoRoutes()` plus `FimoLink`; for custom frameworks, pass the active locale to `FimoProviders`. See `references/locales.md`.
-
-## Usage
+## Stable contract
 
 ```tsx
-import { useLabels, Text } from 'fimo/ui';
-
-export function Hero() {
-  const { t } = useLabels();
-  return (
-    <section>
-      <h1>
-        <Text value={t('hero.title')} />
-      </h1>
-      <p>
-        <Text value={t('hero.subtitle')} />
-      </p>
-      <input placeholder={String(t('hero.emailPlaceholder'))} />
-      <img alt={String(t('hero.imageAlt'))} src="..." />
-    </section>
-  );
-}
+const { t } = useLabels();
+return <Text value={t('hero.title')} as="h1" />;
 ```
 
-- `t(key)` returns a `FimoString` (wrapped for source tracking). Render it via `<Text value={...} />` inside JSX.
-- For HTML attributes (`placeholder`, `alt`, `title`, `aria-label`) cast with `String(t(...))` — the attribute can't accept a `FimoString` object directly.
-- If a key is missing from the DB, it renders empty. Run `fimo validate` and add missing values with `fimo labels set`.
+`t(key)` returns a source-tracked `FimoString`. Render it with `<Text>` when possible so Studio can select it. Convert with `String(t(...))` only for HTML attributes or framework APIs that require a primitive.
 
-## Hard rules (enforced by the pre-build linter)
-
-**The first argument to `t()` MUST be a string literal.** Dynamic keys break source tracking and fail the lint step.
+The first argument must be a string literal so extraction and source tracking remain deterministic:
 
 ```tsx
-// ❌ BAD — variable key
-t(item.key);
+const items = [
+  { href: '/', label: t('nav.home') },
+  { href: '/about', label: t('nav.about') },
+];
+```
 
-// ❌ BAD — template with expression
-t(`nav.${page}`);
+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`.
 
-// ✅ GOOD — put the t() call where the literal lives
-const items = [{ label: t('nav.home') }, { label: t('nav.about') }];
-items.map((item) => <li>{item.label}</li>);
-```
+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.
 
-## Key naming
+## Framework adapters
 
-- Dot-namespaced, lowercase, kebab or camelCase leaves: `hero.title`, `nav.signIn`, `footer.copyright`, `errors.required`.
-- Namespace by **page/section/component**, not by feature (`contact.form.submitLabel`, not `forms.contactSubmit`).
-- Values live in the DB. Do not put user-visible fallback copy in code.
+The label contract is shared; acquisition differs by runtime:
 
-## What NOT to translate
+- Next server: `getLabels({ locale? })` from `fimo/next`.
+- Next client: `useLabels()` from `fimo/next/client`, under `FimoProvider`.
+- React Router/Vite client: `useLabels()` from `fimo/ui`, under the existing framework integration.
 
-- Dynamic content from entries or forms — that's already stored in the DB (content via schemas, submissions via forms).
-- Content-type field values rendered via `fimo/ui` primitives (`<Text>`, `<RichText>`, …) — those carry their own admin-editing metadata.
-- Purely decorative / non-text (icons, logos).
-- Developer-only strings (`console.log`, error messages thrown for debugging).
+Load `references/frameworks/next.md`, `references/frameworks/react-router.md`, or `references/frameworks/vite-react.md` before adding a provider.
 
-## Rule of thumb
+## Locale behavior
 
-If a human reader sees the text AND the project owner might want to reword it in the admin, it goes through `t()`. When in doubt: wrap it.
+`.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.
 
-After adding or changing `t()` calls, run `fimo validate`, then fill missing values with `fimo labels set` or `fimo labels set-many`. See `fimo-cli/references/labels.md`.
+Do not translate schema content, dynamic form submissions, decorative icons, or developer-only logs through labels.

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

@@ -1,129 +1,40 @@
-# Locales: Routing And Navigation
+# Locale ownership
 
-Fimo provides locale utilities that follow the Fimo standard, but they are helpers, not a mandatory app architecture. A project may use a custom Next, Astro, domain, middleware, or hand-rolled routing strategy as long as it passes the active locale into Fimo and keeps Fimo route metadata canonical.
+The application owns locale resolution and routing. Fimo consumes the resolved locale for labels and localized content.
 
-## Configuration
+`.fimo/config.json` declares supported/default locales:
 
-`.fimo/config.json` owns the locale list and routing strategy. Keep one locale unless the user asks for multilingual or localized output.
-
-```jsonc
+```json
 {
   "i18n": {
     "defaultLocale": "en",
-    "locales": ["en"],
-    "routing": {
-      "strategy": "path-prefix", // only supported strategy: /es/about for Spanish; default locale can stay /about
-      "prefixDefaultLocale": false, // when false, omit /en for the default locale
-    },
-  },
-}
-```
-
-- `defaultLocale` is the source/default locale.
-- `locales` lists enabled locales and must include `defaultLocale`. Do not add non-default locales unless the user asks for multiple languages, localized routes, translations, or a specific locale.
-- `routing.strategy` currently supports `path-prefix`.
-- If multiple locales are configured, create or update labels and localized content for every configured locale. Create schemas with `i18n: { "enabled": false }` only once; those entries are shared across locales.
-
-Locale tags should be structurally valid, for example `en`, `es`, `pt-BR`, or `zh-Hans`.
-
-## Canonical Routes
-
-Keep `.fimo/config.json#routes` canonical and unlocalized:
-
-```json
-{
-  "routes": {
-    "pricing": {
-      "label": "Pricing",
-      "path": "/pricing"
-    }
+    "locales": ["en", "fr"]
   }
 }
 ```
 
-Do not add separate route metadata for `/es/pricing`. Locale prefixes such as `/es` are reserved when `path-prefix` is enabled, and `fimo validate` reports collisions.
-
-## React Router Standard Helper
-
-For React Router framework mode, write one canonical route list and wrap it:
-
-```ts
-import type { RouteConfig } from '@react-router/dev/routes';
-import { index, route } from '@react-router/dev/routes';
-import { fimoRoutes } from 'fimo/react-router/routes';
-
-const routes = [
-  index('./pages/Index.tsx', { id: 'home' }),
-  route('pricing', './pages/Pricing.tsx', { id: 'pricing' }),
-  route('blog/:slug', './pages/BlogPost.tsx', { id: 'blog-post' }),
-] satisfies RouteConfig;
-
-export default fimoRoutes(routes) satisfies RouteConfig;
-```
-
-`fimoRoutes()` expands concrete locale-prefixed aliases from the configured locale list while reusing the same page modules. For `locales: ["en", "es"]` and `prefixDefaultLocale: false`, it adds routes like `/es`, `/es/pricing`, and `/es/blog/:slug`.
-
-This helper exists so the Fimo UI route selector, preview navigation, labels, and content queries all agree on the same URL shape. It is not required if the project deliberately implements a custom routing strategy.
-
-Copyable examples live in `assets/react-router-locales/routes.ts` and `assets/react-router-locales/navigation.tsx`.
-
-## Existing Custom Locale Systems
-
-Before changing a multilingual app, inspect its locale provider, route table, language switcher, redirects, and current public URLs. Preserve that behavior while migrating.
-
-For React Router projects, prefer converging on one locale contract owned by `.fimo/config.json`, `fimoRoutes()`, and `FimoLink`. Move existing providers and language-switcher UI into the framework root instead of replacing them or adding a second locale context. Keep route metadata canonical and reuse page modules across locales.
-
-If adopting the standard helper would change established public URLs, do not silently rewrite them. Keep the custom router temporarily, pass its resolved locale to `<FimoProviders locale={locale}>`, and ask the user to choose the canonical URLs and redirects before normalizing the route table.
-
-## Links
-
-Use `FimoLink` for internal links that should preserve or switch locale:
-
-```tsx
-import { FimoLink } from 'fimo/react-router';
-
-<FimoLink to="/pricing">Pricing</FimoLink>
-<FimoLink to="/pricing" locale="es">Spanish pricing</FimoLink>
-```
-
-`FimoLink` localizes absolute internal paths according to `.fimo/config.json#i18n.routing`. It leaves relative, hash, query-only, and external URLs alone. Use React Router's raw `Link` only when you intentionally want to bypass Fimo's locale behavior.
-
-Read the active locale with `useLocale()` when component logic needs it:
+Keep one locale unless the product asks for multilingual output. Locale tags should be structurally valid, such as `en`, `pt-BR`, or `zh-Hans`.
 
-```tsx
-import { useLocale } from 'fimo/ui';
+For an already linked project, the same locales must also be enabled in Fimo before writing non-default label or content variants. Local config and `fimo validate` do not currently provision project locales. If the API says a locale is not configured, enable it in Fimo Studio; do not change the application's route strategy to work around it.
 
-const { locale, defaultLocale, locales, routePath, dir } = useLocale();
-```
+## Application responsibilities
 
-`locales` lists every configured locale, so a language switcher needs no API call and no extra component:
+- 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.
+- Treat any optional Studio route catalog as framework-adapter-specific; load the framework reference before creating or changing one.
 
-```tsx
-const { locale, locales, routePath } = useLocale();
-
-locales.map((code) => (
-  <FimoLink key={code} to={routePath} locale={code} aria-current={code === locale ? 'true' : undefined}>
-    {new Intl.DisplayNames([code], { type: 'language' }).of(code)}
-  </FimoLink>
-));
-```
+## Fimo responsibilities
 
-## Custom Frameworks
-
-For Next, Astro, plain Vite, or custom routers, the same contract applies:
-
-- The framework owns URL matching.
-- The app resolves the active locale from the request, path, domain, middleware, cookie, or user preference.
-- The app passes that locale to Fimo:
-
-```tsx
-<FimoProviders locale={locale}>{children}</FimoProviders>
-```
+- Fetch the correct localized content variant and label dictionary after receiving locale.
+- Use `defaultLocale` when no explicit locale is supplied.
+- Preserve one shared entry for schemas with `i18n.enabled: false`.
+- Preserve source metadata for editing.
 
-When using custom routing, also provide localized internal-link helpers in that framework's style. Fimo's DB labels and localized content will follow the locale passed to `FimoProviders`.
+## Framework handoff
 
-## What Not To Do
+- Next.js → load `references/frameworks/next/locales.md`.
+- 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 create `src/pages/__localized/*` copies just for locales.
-- Do not duplicate every route in `.fimo/config.json` per locale.
-- Do not use `/es` as a normal canonical route when `es` is an enabled locale.
+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.