fimo 2.4.0-staging.2 → 2.4.0-staging.4

package/dist/runtime/seo/head.d.ts

@@ -0,0 +1,31 @@
+import type { FimoSEO } from '../shared/fimo-config.types.js';
+export type FimoHeadMeta = {
+    name: string;
+    content: string;
+} | {
+    property: string;
+    content: string;
+};
+export interface FimoHeadLink {
+    rel: string;
+    href: string;
+}
+/** Document head for one page: spread each entry onto a `<meta>` or `<link>`. */
+export interface FimoHead {
+    title?: string;
+    meta: FimoHeadMeta[];
+    links: FimoHeadLink[];
+}
+export interface SeoHeadOptions {
+    /** Final canonical URL chosen by the app, also used for og:url. Omit to emit neither tag. */
+    canonicalUrl?: string;
+}
+/**
+ * Convert final SEO values to native tag attributes without I/O, route resolution
+ * or merging. The app resolves content and policy first. Absent/empty fields emit
+ * no tags; omitted SEO emits an empty head unless a canonical URL is supplied.
+ * `seo.url` is a site base, not a page canonical: only options.canonicalUrl emits
+ * canonical/og:url. Render attributes through the framework, never as raw HTML.
+ */
+export declare function toSeoHead(seo?: FimoSEO, options?: SeoHeadOptions): FimoHead;
+//# sourceMappingURL=head.d.ts.map

package/dist/runtime/seo/head.js

@@ -0,0 +1,47 @@
+/**
+ * Convert final SEO values to native tag attributes without I/O, route resolution
+ * or merging. The app resolves content and policy first. Absent/empty fields emit
+ * no tags; omitted SEO emits an empty head unless a canonical URL is supplied.
+ * `seo.url` is a site base, not a page canonical: only options.canonicalUrl emits
+ * canonical/og:url. Render attributes through the framework, never as raw HTML.
+ */
+export function toSeoHead(seo = {}, options = {}) {
+    const canonical = options.canonicalUrl;
+    if (!Object.values(seo).some(Boolean) && !canonical) {
+        return { meta: [], links: [] };
+    }
+    const meta = [];
+    const named = (name, content) => {
+        if (content) {
+            meta.push({ name, content });
+        }
+    };
+    const property = (name, content) => {
+        if (content) {
+            meta.push({ property: name, content });
+        }
+    };
+    named('description', seo.description);
+    named('robots', seo.robots);
+    named('theme-color', seo.themeColor);
+    property('og:type', 'website');
+    property('og:site_name', seo.siteName);
+    property('og:title', seo.title);
+    property('og:description', seo.description);
+    property('og:url', canonical);
+    property('og:image', seo.image);
+    property('og:locale', seo.locale);
+    named('twitter:card', 'summary_large_image');
+    named('twitter:site', seo.twitterSite);
+    named('twitter:title', seo.title);
+    named('twitter:description', seo.description);
+    named('twitter:image', seo.image);
+    const links = [];
+    if (canonical) {
+        links.push({ rel: 'canonical', href: canonical });
+    }
+    if (seo.favicon) {
+        links.push({ rel: 'icon', href: seo.favicon }, { rel: 'apple-touch-icon', href: seo.favicon });
+    }
+    return { ...(seo.title ? { title: seo.title } : {}), meta, links };
+}

package/dist/runtime/seo/index.d.ts

@@ -1,3 +1,4 @@
 export * from './resolver.js';
+export * from './head.js';
 export type { FimoSEO } from '../shared/fimo-config.types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/seo/index.js

@@ -1 +1,2 @@
 export * from './resolver.js';
+export * from './head.js';

package/dist/runtime/seo/resolver.d.ts

@@ -1,4 +1,4 @@
-import type { FimoConfig, FimoRouteConfig, FimoSEO } from '../shared/fimo-config.types.js';
+import type { FimoRouteConfig, FimoSEO, RouteSEO } from '../shared/fimo-config.types.js';
 /**
  * Shared SEO resolver for the generated app.
  *
@@ -40,5 +40,19 @@ export declare function matchRoutePath(pathname: string, pathPattern: string): {
 export declare function resolveRouteConfig(pathname: string, routes: Record<string, FimoRouteConfig> | undefined): FimoRouteConfig | undefined;
 export declare function getNestedValue(input: unknown, path: string): unknown;
 export declare function resolveTemplate(template: string, context: Record<string, unknown>): string;
-export declare function resolveSeoForPath(pathname: string, config: FimoConfig, routeData?: unknown): FimoSEO | undefined;
+/** SEO slices of an imported JSON config; unrelated framework literal unions need not be preserved. */
+export interface FimoSeoConfig {
+    seo?: FimoSEO;
+    i18n?: {
+        defaultLocale?: string;
+        locales?: string[];
+    };
+    routes?: Record<string, {
+        path?: string;
+        label?: string;
+        seo?: RouteSEO;
+        params?: object;
+    }>;
+}
+export declare function resolveSeoForPath(pathname: string, config: FimoSeoConfig, routeData?: unknown): FimoSEO | undefined;
 //# sourceMappingURL=resolver.d.ts.map

package/dist/scripts/sync-schemas.js

@@ -144,6 +144,7 @@ function resolveProjectRuntime(cwd) {
         version,
         providesLegacyReactRuntime: packageExportsSubpath(packageJson, './ui'),
         providesReactRuntime: packageExportsSubpath(readProjectPackage(cwd, 'fimo-react'), '.'),
+        providesLegacyNextRuntime: packageExportsSubpath(packageJson, './next') && packageExportsSubpath(packageJson, './next/client'),
         providesNextRuntime: packageExportsSubpath(readProjectPackage(cwd, 'fimo-next'), '.') &&
             packageExportsSubpath(readProjectPackage(cwd, 'fimo-next'), './client'),
         providesAstroRuntime: packageExportsSubpath(packageJson, './astro'),
@@ -154,7 +155,7 @@ function resolveProjectRuntime(cwd) {
 }
 function contentRuntimeImportFor(framework, runtime) {
     if (framework === 'nextjs') {
-        return 'fimo-next';
+        return isVersionAtLeast(runtime.version, MINIMUM_FRAMEWORK_COMPANION_RUNTIME_VERSION) ? 'fimo-next' : 'fimo/next';
     }
     if (framework === 'astro') {
         return 'fimo/astro';
@@ -196,6 +197,12 @@ function resolveSchemaGenerationTarget(runtimeImport, runtime) {
     if (runtimeImport === 'fimo-react') {
         return 'react';
     }
+    if (runtimeImport === 'fimo/next' && !runtime.providesLegacyNextRuntime) {
+        throw new Error(`Cannot generate schema clients because project-local fimo@${runtime.version} does not provide the ` +
+            'legacy fimo/next and fimo/next/client exports required by this Next.js project. ' +
+            `Run \`${CONTENT_CLIENT_RUNTIME_UPGRADE_COMMAND}\` in the project, then run \`npx fimo@latest validate\` again. ` +
+            'No generated files were changed.');
+    }
     if (runtimeImport === 'fimo-next' && !runtime.providesNextRuntime) {
         throw new Error(`Cannot generate schema clients because the project does not provide the ` +
             'fimo-next and fimo-next/client exports required by this Next.js project. ' +
@@ -213,7 +220,7 @@ function resolveSchemaGenerationTarget(runtimeImport, runtime) {
             `Run \`npm install fimo-sveltekit@${runtime.version}\` in the project, then run \`npx fimo@latest validate\` again. ` +
             'No generated files were changed.');
     }
-    if (runtimeImport === 'fimo-next') {
+    if (runtimeImport === 'fimo/next' || runtimeImport === 'fimo-next') {
         return 'next';
     }
     return runtimeImport === 'fimo/astro' ? 'astro' : 'sveltekit';
@@ -224,17 +231,17 @@ function templatesForTarget(target, runtime, runtimeImport) {
             {
                 suffix: '.types.ts',
                 path: templatePath(runtime, 'types'),
-                runtimeImport: 'fimo-next',
+                runtimeImport,
             },
             {
                 suffix: '.ts',
                 path: templatePath(runtime, 'nextServer'),
-                runtimeImport: 'fimo-next',
+                runtimeImport,
             },
             {
                 suffix: '.client.ts',
                 path: templatePath(runtime, 'nextClient'),
-                runtimeImport: 'fimo-next/client',
+                runtimeImport: `${runtimeImport}/client`,
             },
         ];
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "2.4.0-staging.2",
+  "version": "2.4.0-staging.4",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "keywords": [
     "astro-component"
@@ -193,13 +193,13 @@
   "devDependencies": {
     "@clack/core": "^1.2.0",
     "@clack/prompts": "^1.2.0",
-    "@fimo/agents-bundle": "2.4.0-staging.2",
-    "@fimo/api-contracts": "2.4.0-staging.2",
-    "@fimo/cli-kit": "2.4.0-staging.2",
-    "@fimo/framework-detect": "2.4.0-staging.2",
-    "@fimo/routes": "2.4.0-staging.2",
-    "@fimo/sdk": "2.4.0-staging.2",
-    "@fimo/tsconfig": "2.4.0-staging.2",
+    "@fimo/agents-bundle": "2.4.0-staging.4",
+    "@fimo/api-contracts": "2.4.0-staging.4",
+    "@fimo/cli-kit": "2.4.0-staging.4",
+    "@fimo/framework-detect": "2.4.0-staging.4",
+    "@fimo/routes": "2.4.0-staging.4",
+    "@fimo/sdk": "2.4.0-staging.4",
+    "@fimo/tsconfig": "2.4.0-staging.4",
     "@types/node": "22.18.6",
     "agent-install": "^0.0.5",
     "astro": "^7.1.6",

package/templates/astro/.fimo/config.json

@@ -18,6 +18,7 @@
     "project": {
       "label": "Project",
       "path": "/:locale/projects/:slug",
+      "seo": { "title": "{{project.title}}", "description": "{{project.summary}}" },
       "params": {
         "locale": { "type": "locale", "optional": true },
         "slug": { "schema": "Project", "queryField": "slug", "displayField": "title" }

package/templates/astro/AGENTS.md

@@ -31,7 +31,7 @@ a code-only task, or use `npx fimo@latest` for project-local code generation and
 - Treat the user's language request as part of setup. The first explicitly requested locale is the primary locale. Load `fimo skills get fimo-cli --ref locales` and use `fimo locales` to configure the exact locale set and default. Never edit `i18n.defaultLocale` or `i18n.locales` directly. If no language is requested, keep `en` and state that choice. Astro reads the synchronized config, keeps the default locale unprefixed, and prefixes the others.
 - Preserve both the unprefixed default pages and the `[locale]` page tree. Astro has no optional single-segment file route, so the paired native pages keep one-locale URLs clean and allow another locale without changing the route shape. Use `Astro.currentLocale` for Fimo content reads, `getLabels`, and document language.
 - Keep `.fimo/config.json#routes` as Studio metadata aligned with Astro's page files. It does not configure Astro routing.
-- Astro owns routes, locale resolution, links, HTML language/direction, and SEO. Fimo connects to those decisions.
+- Astro owns routes, locale resolution, links and SEO. Base.astro resolves the actual path with `resolveSeoForPath` and renders `toSeoHead` from `fimo/seo`. Content pages pass already-resolved `seo` with their route data. Keep title/social tags in agreement and preserve the app's canonical policy.
 - Use generated schema clients, `getLabels({ locale })`, and native components from `fimo/astro/components` for editable values.
 - Do not add React or a second deployment platform.
 - Never edit `.fimo/project.json`; it links this directory to the remote project.

package/templates/astro/astro.config.mjs

@@ -4,6 +4,7 @@ import { fimo } from 'fimo-astro/config';
 import fimoConfig from './.fimo/config.json' with { type: 'json' };
 
 export default defineConfig({
+  devToolbar: { enabled: false },
   integrations: [fimo()],
   i18n: {
     defaultLocale: fimoConfig.i18n.defaultLocale,

package/templates/astro/package.json

@@ -9,8 +9,8 @@
     "check": "astro sync && astro check"
   },
   "dependencies": {
-    "fimo": "2.4.0-staging.2",
-    "fimo-astro": "2.4.0-staging.2"
+    "fimo": "2.4.0-staging.4",
+    "fimo-astro": "2.4.0-staging.4"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",

package/templates/astro/src/layouts/Base.astro

@@ -1,10 +1,25 @@
 ---
+import { resolveSeoForPath, toSeoHead, type FimoSEO } from 'fimo/seo';
+
+import fimoConfig from '../../.fimo/config.json';
+
 interface Props {
   lang: string;
-  title: string;
+  title?: string;
+  description?: string;
+  seo?: FimoSEO;
+  canonicalUrl?: string | null;
 }
 
-const { lang, title } = Astro.props;
+const { lang, title, description, seo = resolveSeoForPath(Astro.url.pathname, fimoConfig) } = Astro.props;
+const canonicalUrl = Astro.props.canonicalUrl === undefined
+  ? (seo?.url ? new URL(Astro.url.pathname, seo.url).href : undefined)
+  : Astro.props.canonicalUrl ?? undefined;
+const head = toSeoHead({
+  ...seo,
+  ...(title !== undefined ? { title } : {}),
+  ...(description !== undefined ? { description } : {}),
+}, { canonicalUrl });
 ---
 
 <!doctype html>
@@ -12,10 +27,11 @@ const { lang, title } = Astro.props;
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width" />
-    <meta name="description" content="A new Fimo project built with Astro." />
+    <title>{head.title ?? 'Fimo + Astro'}</title>
+    {head.meta.map((attributes) => <meta {...attributes} />)}
+    {head.links.map((attributes) => <link {...attributes} />)}
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet" />
-    <title>{title}</title>
   </head>
   <body>
     <slot />

package/templates/astro/src/pages/[locale]/index.astro

@@ -14,6 +14,6 @@ if (!routeLocale || !prefixedLocales.has(routeLocale)) {
 const locale = Astro.currentLocale ?? routeLocale;
 ---
 
-<Base lang={locale} title="Fimo + Astro">
+<Base lang={locale}>
   <StarterHome />
 </Base>

package/templates/astro/src/pages/[locale]/projects/[slug].astro

@@ -1,7 +1,9 @@
 ---
 import { getLabels } from 'fimo/astro';
 import { Text } from 'fimo/astro/components';
+import { resolveSeoForPath } from 'fimo/seo';
 
+import config from '../../../../.fimo/config.json';
 import Base from '../../../layouts/Base.astro';
 import { prefixedLocales } from '../../../locales';
 import * as Project from '../../../schemas/Project';
@@ -22,9 +24,10 @@ const [project, labels] = await Promise.all([Project.getBySlug(slug, { locale })
 if (!project) {
   return Astro.redirect('/404');
 }
+const seo = resolveSeoForPath(Astro.url.pathname, config, { project });
 ---
 
-<Base lang={locale} title={String(project.title)}>
+<Base lang={locale} seo={seo} title={seo?.title ?? String(project.title)}>
   <main data-framework="astro" data-rendering="server" data-project-slug={slug}>
     <a href={`/${locale}/projects`}><Text as="span" value={labels.t('navigation.projects')} /></a>
     <article>

package/templates/astro/src/pages/index.astro

@@ -8,6 +8,6 @@ export const prerender = true;
 const locale = Astro.currentLocale ?? defaultLocale;
 ---
 
-<Base lang={locale} title="Fimo + Astro">
+<Base lang={locale}>
   <StarterHome />
 </Base>

package/templates/astro/src/pages/projects/[slug].astro

@@ -1,7 +1,9 @@
 ---
 import { getLabels } from 'fimo/astro';
 import { Text } from 'fimo/astro/components';
+import { resolveSeoForPath } from 'fimo/seo';
 
+import config from '../../../.fimo/config.json';
 import Base from '../../layouts/Base.astro';
 import { defaultLocale } from '../../locales';
 import * as Project from '../../schemas/Project';
@@ -15,9 +17,10 @@ const [project, labels] = await Promise.all([Project.getBySlug(slug, { locale })
 if (!project) {
   return Astro.redirect('/404');
 }
+const seo = resolveSeoForPath(Astro.url.pathname, config, { project });
 ---
 
-<Base lang={locale} title={String(project.title)}>
+<Base lang={locale} seo={seo} title={seo?.title ?? String(project.title)}>
   <main data-framework="astro" data-rendering="server" data-project-slug={slug}>
     <a href="/projects"><Text as="span" value={labels.t('navigation.projects')} /></a>
     <article>

package/templates/nextjs/package.json

@@ -12,9 +12,9 @@
   },
   "dependencies": {
     "@tanstack/react-query": "^5.80.6",
-    "fimo": "2.4.0-staging.2",
-    "fimo-next": "2.4.0-staging.2",
-    "fimo-react": "2.4.0-staging.2",
+    "fimo": "2.4.0-staging.4",
+    "fimo-next": "2.4.0-staging.4",
+    "fimo-react": "2.4.0-staging.4",
     "next": "^16.3.3",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"

package/templates/react-router/package.json

@@ -21,10 +21,10 @@
     "cn": "0.2.4",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "2.4.0-staging.2",
-    "fimo-react": "2.4.0-staging.2",
-    "fimo-react-router": "2.4.0-staging.2",
-    "fimo-vite": "2.4.0-staging.2",
+    "fimo": "2.4.0-staging.4",
+    "fimo-react": "2.4.0-staging.4",
+    "fimo-react-router": "2.4.0-staging.4",
+    "fimo-vite": "2.4.0-staging.4",
     "input-otp": "^1.4.2",
     "isbot": "^5",
     "lucide-react": "^0.577.0",

package/templates/sveltekit/AGENTS.md

@@ -32,7 +32,7 @@ a code-only task, or use `npx fimo@latest` for project-local code generation and
 - 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.
+- The application owns routes, locale resolution, links and SEO. Return final `seoHead` from route loads using `resolveSeoForPath` and `toSeoHead` from `fimo/seo`. The root renders `page.data.seoHead` once. Content pages supply route data; do not add competing page head tags. Check client navigation for stale tags.
 - Do not add a second deployment platform.
 - Never edit `.fimo/project.json`; it links this directory 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/sveltekit/package.json

@@ -11,8 +11,8 @@
     "prepare": "svelte-kit sync"
   },
   "dependencies": {
-    "fimo": "2.4.0-staging.2",
-    "fimo-sveltekit": "2.4.0-staging.2"
+    "fimo": "2.4.0-staging.4",
+    "fimo-sveltekit": "2.4.0-staging.4"
   },
   "devDependencies": {
     "@sveltejs/kit": "^2.70.2",

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

@@ -1,12 +1,16 @@
 import { getLabels } from 'fimo-sveltekit';
+import { resolveSeoForPath, toSeoHead } from 'fimo/seo';
 
+import fimoConfig from '../../.fimo/config.json';
 import { resolveLocale } from '../locales';
 
 export async function load(event) {
   const locale = resolveLocale(event.params);
+  const seo = resolveSeoForPath(event.url.pathname, fimoConfig);
 
   return {
     locale,
+    seoHead: toSeoHead(seo, { canonicalUrl: seo?.url ? new URL(event.url.pathname, seo.url).href : undefined }),
     labels: await getLabels({ event, locale }),
   };
 }

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

@@ -1,17 +1,29 @@
 <script lang="ts">
   import { afterNavigate } from '$app/navigation';
+  import { page } from '$app/state';
   import { FimoProvider } from 'fimo-sveltekit/components';
   import type { Snippet } from 'svelte';
 
   import type { LayoutData } from './$types';
 
   let { data, children }: { data: LayoutData; children: Snippet } = $props();
+  const head = $derived(page.data.seoHead ?? { meta: [], links: [] });
 
   afterNavigate(() => {
     document.documentElement.lang = data.locale;
   });
 </script>
 
+<svelte:head>
+  <title>{head.title ?? 'Fimo + SvelteKit'}</title>
+  {#each head.meta as attributes}
+    <meta {...attributes} />
+  {/each}
+  {#each head.links as attributes}
+    <link {...attributes} />
+  {/each}
+</svelte:head>
+
 <FimoProvider labels={data.labels}>
   {@render children()}
 </FimoProvider>

package/templates/sveltekit/src/routes/[[locale=locale]]/+page.svelte

@@ -1,8 +1,3 @@
-<svelte:head>
-  <title>Fimo + SvelteKit</title>
-  <meta name="description" content="A new Fimo project." />
-</svelte:head>
-
 <div class="starter">
   <main class="starter-main">
     <div class="starter-panel">

package/templates/vite/package.json

@@ -11,10 +11,10 @@
   },
   "dependencies": {
     "@tanstack/react-query": "^5.80.6",
-    "fimo": "2.4.0-staging.2",
-    "fimo-react": "2.4.0-staging.2",
-    "fimo-react-router": "2.4.0-staging.2",
-    "fimo-vite": "2.4.0-staging.2",
+    "fimo": "2.4.0-staging.4",
+    "fimo-react": "2.4.0-staging.4",
+    "fimo-react-router": "2.4.0-staging.4",
+    "fimo-vite": "2.4.0-staging.4",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-router": "^8.3.0"