fimo 0.14.0 → 0.15.0-staging.2

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

@@ -0,0 +1,110 @@
+# SvelteKit integration
+
+Use this reference when `fimo describe --json` reports
+`framework.slug: "sveltekit"`. SvelteKit keeps owning routes, load functions,
+locale resolution, links, document metadata, and SEO.
+
+## Compatibility
+
+The adapter targets SvelteKit 2 with Svelte 5. The acceptance baseline currently
+uses SvelteKit `2.70.2`, Svelte `5.56.8`, and Vite `8.2.0`; do not assume that
+SvelteKit 1 or Svelte 4 projects are compatible.
+
+## Connect the Vite plugin
+
+Add Fimo's source-tagging plugin alongside SvelteKit's own plugin:
+
+```ts
+import { sveltekit } from '@sveltejs/kit/vite';
+import { fimo } from 'fimo/sveltekit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [fimo(), sveltekit()] });
+```
+
+The plugin tags native Svelte elements during `vite dev` so Studio can map
+elements back to source. It does not change production output or own routing.
+
+## Hosted configuration
+
+For a new Fimo-hosted SvelteKit project, keep the hosting adapter behind Fimo's
+config seam:
+
+```js
+import { fimo } from 'fimo/sveltekit/config';
+
+export default {
+  kit: { adapter: fimo() },
+};
+```
+
+Do not import or install a provider-specific adapter in the generated project.
+If an adopted project already owns a different adapter, preserve it; Fimo does
+not replace application-owned hosting configuration.
+
+## Read content and labels
+
+Use SvelteKit's server `load` functions and pass the request event so Fimo uses
+SvelteKit's request-aware `fetch`:
+
+```ts
+// src/routes/articles/+page.server.ts
+import { createFimo } from 'fimo/sveltekit';
+import { content } from '../../../schemas';
+
+export async function load(event) {
+  const fimo = createFimo({ content, event });
+  const result = await fimo.articles.list({ limit: 12 });
+  return { articles: fimo.articles.serialize(result.items) };
+}
+```
+
+Resolve the locale with the application's existing policy, then fetch labels in
+the root server layout and publish the snapshot to descendants:
+
+```ts
+// src/routes/+layout.server.ts
+import { env } from '$env/dynamic/public';
+import { getLabels } from 'fimo/sveltekit';
+
+export async function load(event) {
+  const locale = 'en'; // replace with the application's resolved locale
+  return { labels: await getLabels({ apiUrl: env.PUBLIC_FIMO_API_URL, event, locale }) };
+}
+```
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script lang="ts">
+  import { FimoProvider } from 'fimo/sveltekit/components';
+  import type { LayoutData } from './$types';
+  import type { Snippet } from 'svelte';
+
+  let { data, children }: { data: LayoutData; children: Snippet } = $props();
+</script>
+
+<FimoProvider labels={data.labels}>
+  {@render children()}
+</FimoProvider>
+```
+
+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`
+formats plain numeric values for display; numeric fields currently have no
+source metadata, so it is not a Studio-editable primitive.
+
+## Live preview
+
+`FimoProvider` owns the Studio browser bridge. On mount it reads
+`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.
+
+## Boundaries
+
+- SvelteKit owns routing, history, 404s, locale URLs, and SEO.
+- `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.

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

@@ -1,100 +1,35 @@
-# Setup Fimo on plain Vite + React
+# Vite and 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.
+Use this reference for a Vite + React SPA without React Router framework mode. Preserve the application's browser router, provider tree, and build structure.
 
-## When to use this vs. React Router
+## Install and build
 
-- **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
-
-```
+```bash
 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"
-  }
-}
+pnpm add -D vite @vitejs/plugin-react
 ```
 
-## File: `vite.config.ts`
+Add Fimo's Vite plugins without replacing the application's existing plugins:
 
 ```ts
+import react from '@vitejs/plugin-react';
 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>
+export default defineConfig({
+  plugins: [react(), ...fimo({ seo: true })],
+});
 ```
 
-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.
+`fimo()` is synchronous and returns a `PluginOption[]`. `seo: true` updates the shared `index.html` at build time. Add `sitemap: true` or `robots: true` only when requested.
 
-## File: `src/main.tsx`
+## Application root
 
-`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:
+`FimoProviders` needs a React Router context for Studio navigation and pageview tracking. Keep the application's existing router type:
 
 ```tsx
-import { FimoProviders } from 'fimo/react-router';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { FimoProviders } from 'fimo/react-router';
 import React from 'react';
 import { createRoot } from 'react-dom/client';
 import { BrowserRouter } from 'react-router';
@@ -116,111 +51,45 @@ createRoot(document.getElementById('root')!).render(
 );
 ```
 
-`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.
+An adopted SPA can omit the explicit `QueryClientProvider` when it does not need custom defaults; Fimo supplies a stable fallback.
+
+## Content and labels
 
-## File: `src/App.tsx`
+Use `fimo/ui` for tracked values:
 
 ```tsx
-import { Text, useLabels } from 'fimo/ui';
+import { Label } from 'fimo/ui';
 
 export function App() {
-  const { t } = useLabels();
-
-  return (
-    <main>
-      <Text value={t('home.hero.title')} as="h1" />
-    </main>
-  );
+  return <Label value="home.hero.title" as="h1" />;
 }
 ```
 
-## File: `.fimo/config.json`
+Use `useLabels().t()` for attributes, metadata, or composed strings. `references/labels.md` owns the complete contract.
+
+## Project profile and browser routes
+
+Vite defaults to `dist`. Declare a different output only when the application intentionally emits elsewhere.
+
+A `BrowserRouter` SPA needs an application-shell rewrite for direct visits to client routes:
 
 ```json
 {
   "runtime": { "framework": "vite" },
   "hosting": {
     "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
-  },
-  "version": "4",
-  "seo": {
-    "title": "__PROJECT_SLUG__",
-    "siteName": "__PROJECT_SLUG__"
-  },
-  "routes": {
-    "home": {
-      "label": "Home",
-      "path": "/"
-    }
   }
 }
 ```
 
-The rewrite is required for direct visits to `BrowserRouter` routes on Fimo
-hosting. Omit it for `HashRouter` or real per-route static output. See
-`references/frameworks/hosting.md`.
-
-## File: `.fimo/project.json`
-
-```json
-{
-  "projectId": "__PROJECT_ID__",
-  "organizationId": "__ORG_ID__",
-  "apiUrl": "__API_URL__"
-}
-```
+Omit the rewrite for `HashRouter` or real per-route static output. The catch-all lets the browser router render its own not-found page, but the initial host response remains HTTP 200.
 
-## File: `tsconfig.json`
+The optional `routes` object is Studio's page catalog, not production routing.
 
-```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"]
-}
-```
+## Boundaries
 
-## 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`.
+- The application owns routes, links, locale resolution, and browser behavior.
+- Build-time SEO changes one HTML shell. Crawler-visible per-route SEO requires prerendering or a framework with native route output.
+- Do not add React Router framework-mode files to a plain Vite application.
+- Use `fimo deploy` only when the developer requests a hosted preview or publication.
+- Load `references/ui.md` for rendering and `references/frameworks/hosting.md` for hosting overrides.

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

@@ -4,16 +4,24 @@ Labels are project-wide, locale-scoped, editor-managed static copy. Use them for
 
 For label CLI writes and missing-key validation, load `fimo-cli/references/labels.md`.
 
-## Stable contract
+## Vite and React Router
+
+Standalone visible copy can use `Label` because these runtimes already provide label context:
+
+```tsx
+<Label value="hero.title" as="h1" />
+```
+
+Use `t()` for attributes, metadata, and composed strings:
 
 ```tsx
 const { t } = useLabels();
-return <Text value={t('hero.title')} as="h1" />;
+return <input placeholder={String(t('email.placeholder'))} />;
 ```
 
-`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.
+`t(key)` returns a source-tracked `FimoString`. Render visible values with `Text`; convert with `String(t(...))` only for HTML attributes or framework APIs that require a primitive.
 
-The first argument must be a string literal so extraction and source tracking remain deterministic:
+Label keys — the first argument to `t()` and the `value` of `Label` — must be string literals so extraction and source tracking remain deterministic:
 
 ```tsx
 const items = [
@@ -32,9 +40,11 @@ The label contract is shared; acquisition differs by runtime:
 
 - 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.
+- React Router/Vite client: `Label` and `useLabels()` from `fimo/ui`, under the existing framework integration.
+- SvelteKit: resolve the locale in the root server load and return `getLabels({ apiUrl, event, locale })`. Wrap the root layout with `FimoProvider` from `fimo/sveltekit/components`; the snapshot supplies its locale. Descendants use `Label` from that entrypoint or `useLabels().t()` from `fimo/sveltekit`. Pass the same resolved locale to `createFimo({ content, event, locale })` in content loads.
+- Astro server page: `getLabels({ locale? })` from `fimo/astro`; no provider.
 
-Load `references/frameworks/next.md`, `references/frameworks/react-router.md`, or `references/frameworks/vite-react.md` before adding a provider.
+Load the matching framework reference before choosing a provider or server reader.
 
 ## Locale behavior
 

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

@@ -27,13 +27,15 @@ For an already linked project, enable each locale in Fimo before writing non-def
 ## Fimo responsibilities
 
 - Fetch the correct localized content variant and label dictionary after receiving locale.
-- Use `defaultLocale` when no explicit locale is supplied.
+- Resolve an omitted locale to the project default; server reads let the tenant API choose it.
 - Preserve one shared entry for schemas with `i18n.enabled: false`.
 - Preserve source metadata for editing.
 
 ## Framework handoff
 
 - Next.js → load `references/frameworks/next/locales.md`.
+- Astro → load `references/frameworks/astro.md` and pass the locale resolved by the page.
+- SvelteKit → load `references/frameworks/sveltekit.md`; resolve locale in the app's load functions and pass it to Fimo reads.
 - 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.
 

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

@@ -1,20 +1,20 @@
-# React rendering primitives
+# Rendering primitives
 
 Use Fimo components for source-tracked schema and label values so Studio can identify the field being rendered. Generated reads wrap editable fields with source metadata; pass the whole value to the matching primitive because unwrapping it first removes Studio's edit target.
 
-| Schema/read value                | Component     | Use                                       |
-| -------------------------------- | ------------- | ----------------------------------------- |
-| string/text/date as `FimoString` | `Text`        | editable text and `t()` values            |
-| richtext as `FimoRichText`       | `RichText`    | Tiptap JSONContent                        |
-| 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                              |
-| boolean as `FimoBoolean`         | `Boolean`     | schema booleans                           |
-| source-tagged plain JSON         | `Json`        | schema JSON                               |
-| number                           | normal JSX    | numbers stay plain; no `Number` primitive |
-| reference                        | target fields | populate before rendering                 |
-| blocks                           | nested fields | render each value with its primitive      |
+| Schema/read value                | Component                      | Use                                                                |
+| -------------------------------- | ------------------------------ | ------------------------------------------------------------------ |
+| string/text/date as `FimoString` | `Text`                         | editable text and `t()` values                                     |
+| richtext as `FimoRichText`       | `RichText`                     | Tiptap JSONContent                                                 |
+| 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                                                       |
+| 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 |
+| reference                        | target fields                  | populate before rendering                                          |
+| blocks                           | nested fields                  | render each value with its primitive                               |
 
 ```tsx
 <Text value={article.title} as="h1" />
@@ -46,6 +46,8 @@ Do not render those values as `{program.title}` or `{highlight.label}`. That dis
 
 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>`.
 
+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.
+
 Never construct `FimoString`, `FimoRichText`, `FimoBoolean`, or `FimoMedia` manually. Generated clients and label readers attach the correct source path.
 
 ## Imports
@@ -55,8 +57,10 @@ Choose the framework surface:
 - Next Server Components and data functions → `fimo/next`
 - Next Client Components → `fimo/next/client`
 - React Router/Vite client → `fimo/ui`
+- Astro pages → `fimo/astro/components`
+- Svelte components → `fimo/sveltekit/components`
 
-Load the framework reference before copying an example. Next server and client imports are deliberately separate so React Query/client code does not leak into server bundles.
+Load the framework reference before copying an example. Next server and client imports are deliberately separate so React Query/client code does not leak into server bundles. Astro uses native `.astro` components and does not require React.
 
 ## Component ownership