fimo 0.15.0-staging.2 → 0.15.0-staging.3

package/README.md

@@ -28,6 +28,7 @@ Run the CLI with `npx` — no global install, always the latest:
 ```bash
 npx fimo@latest login
 npx fimo@latest init my-site                 # default React Router scaffold
+# or: npx fimo@latest init my-astro-site --framework astro
 # or: npx fimo@latest init my-next-site --framework nextjs
 # or: npx fimo@latest init my-svelte-site --framework sveltekit
 cd my-site

package/assets/content-templates/forms/framework.eta

@@ -0,0 +1,90 @@
+<%
+const quote = (value) => JSON.stringify(value);
+const localName = (key, index) => `field_${index}_${key.replace(/[^a-zA-Z0-9_$]/g, '_')}`;
+
+function zodForField(field) {
+  if (field.type === 'hidden') {
+    return 'z.string().optional()';
+  }
+
+  if (field.type === 'file') {
+    let schema = `z.custom<File>((value) => typeof File !== "undefined" && value instanceof File, ${quote('Expected a file')})`;
+    if (!field.required) schema += '.optional()';
+    return schema;
+  }
+
+  if (field.type === 'checkbox') {
+    let schema = `z.boolean({ message: ${quote('Must be true or false')} })`;
+    if (field.required) schema += `.refine((value) => value, ${quote(`${field.label} is required`)})`;
+    return schema;
+  }
+
+  if (field.type === 'number') {
+    let schema = 'z.coerce.number()';
+    if (field.validation?.min !== undefined) schema += `.min(${field.validation.min})`;
+    if (field.validation?.max !== undefined) schema += `.max(${field.validation.max})`;
+    if (!field.required) schema += '.optional()';
+    return schema;
+  }
+
+  if (field.type === 'select' && field.options?.length) {
+    let schema = `z.enum(${JSON.stringify(field.options)} as [string, ...string[]])`;
+    if (!field.required) schema += '.optional()';
+    return schema;
+  }
+
+  let schema = 'z.string()';
+  if (field.required) schema += `.min(1, ${quote(`${field.label} is required`)})`;
+  if (field.type === 'email') schema += `.email(${quote('Invalid email address')})`;
+  if (field.type === 'url') schema += `.url(${quote('Invalid URL')})`;
+  if (field.validation?.minLength !== undefined) schema += `.min(${field.validation.minLength})`;
+  if (field.validation?.maxLength !== undefined) schema += `.max(${field.validation.maxLength})`;
+  if (field.validation?.pattern) schema += `.regex(new RegExp(${quote(field.validation.pattern)}))`;
+  if (!field.required) schema += '.optional()';
+  return schema;
+}
+-%>
+<% if (form.clientDirective) { %><%= form.clientDirective %>
+<% } %>// AUTO-GENERATED by `fimo` from src/forms/<%= form.name %>.json - DO NOT EDIT.
+
+import { z } from "zod";
+import { formClient as defaultFormClient } from "<%= form.runtimeImport %>";
+import type { FormClient } from "fimo/forms";
+
+export const FORM_ID = <%= quote(form.id ?? 'undefined') %>;
+
+export const <%= form.pascal %>Schema = z.object({
+<% Object.entries(form.fields).forEach(([key, field]) => { -%>
+  <%= JSON.stringify(key) %>: <%= zodForField(field) %>,
+<% }); -%>
+});
+
+export type <%= form.pascal %>Data = z.infer<typeof <%= form.pascal %>Schema>;
+
+/** Convert a browser form submission into the typed shape expected by Fimo. */
+export function parse<%= form.pascal %>FormData(formData: FormData): <%= form.pascal %>Data {
+  const data: Record<string, unknown> = {};
+<% Object.entries(form.fields).forEach(([key, field], index) => { -%>
+<% if (field.type === 'checkbox') { -%>
+  data[<%= JSON.stringify(key) %>] = ['on', 'true', '1'].includes(formData.get(<%= JSON.stringify(key) %>) as string);
+<% } else if (field.type === 'number') { -%>
+  const <%= localName(key, index) %> = formData.get(<%= JSON.stringify(key) %>);
+  if (<%= localName(key, index) %> !== null && <%= localName(key, index) %> !== '') {
+    data[<%= JSON.stringify(key) %>] = Number(<%= localName(key, index) %>);
+  }
+<% } else { -%>
+  const <%= localName(key, index) %> = formData.get(<%= JSON.stringify(key) %>);
+  if (<%= localName(key, index) %> !== null) {
+    data[<%= JSON.stringify(key) %>] = <%= localName(key, index) %>;
+  }
+<% } -%>
+<% }); -%>
+  return <%= form.pascal %>Schema.parse(data);
+}
+
+export function submit<%= form.pascal %>(
+  data: <%= form.pascal %>Data,
+  client: FormClient = defaultFormClient
+) {
+  return client.submit(FORM_ID, data);
+}

package/assets/content-templates/forms/react.eta

@@ -10,24 +10,24 @@
  */
 
 const hasFileFields = Object.values(form.fields).some(f => f.type === 'file');
+const quote = (value) => JSON.stringify(value);
+const localName = (key, index) => `field_${index}_${key.replace(/[^a-zA-Z0-9_$]/g, '_')}`;
 
-function zodForField(key, field) {
-  const lines = [];
-
+function zodForField(field) {
   if (field.type === 'hidden') {
     return 'z.string().optional()';
   }
 
   if (field.type === 'file') {
-    let s = 'z.instanceof(File)';
-    if (!field.required) s = 'z.instanceof(File).optional()';
+    let s = `z.custom<File>((value) => typeof File !== "undefined" && value instanceof File, ${quote('Expected a file')})`;
+    if (!field.required) s += '.optional()';
     return s;
   }
 
   if (field.type === 'checkbox') {
-    let s = 'z.boolean()';
+    let s = `z.boolean({ message: ${quote('Must be true or false')} })`;
     if (field.required) {
-      s += `.refine(v => v, "${field.label} is required")`;
+      s += `.refine(v => v, ${quote(`${field.label} is required`)})`;
     }
     return s;
   }
@@ -41,8 +41,7 @@ function zodForField(key, field) {
   }
 
   if (field.type === 'select' && field.options?.length) {
-    const opts = field.options.map(o => `"${o}"`).join(', ');
-    let s = `z.enum([${opts}])`;
+    let s = `z.enum(${JSON.stringify(field.options)} as [string, ...string[]])`;
     if (!field.required) s += '.optional()';
     return s;
   }
@@ -51,7 +50,7 @@ function zodForField(key, field) {
   let s = 'z.string()';
 
   if (field.required) {
-    s += `.min(1, "${field.label} is required")`;
+    s += `.min(1, ${quote(`${field.label} is required`)})`;
   }
 
   if (field.type === 'email') {
@@ -62,7 +61,7 @@ function zodForField(key, field) {
 
   if (field.validation?.minLength) s += `.min(${field.validation.minLength})`;
   if (field.validation?.maxLength) s += `.max(${field.validation.maxLength})`;
-  if (field.validation?.pattern) s += `.regex(new RegExp("${field.validation.pattern}"))`;
+  if (field.validation?.pattern) s += `.regex(new RegExp(${quote(field.validation.pattern)}))`;
 
   if (!field.required) s += '.optional()';
 
@@ -79,16 +78,33 @@ const fileFieldKeys = Object.entries(form.fields)
 
 import { z } from "zod";
 
-export const FORM_ID = "<%= form.id %>";
+export const FORM_ID = <%= quote(form.id ?? 'undefined') %>;
 
 export const <%= form.pascal %>Schema = z.object({
 <% Object.entries(form.fields).forEach(([key, field]) => { -%>
-  <%= key %>: <%= zodForField(key, field) %>,
+  <%= JSON.stringify(key) %>: <%= zodForField(field) %>,
 <% }); -%>
 });
 
 export type <%= form.pascal %>Data = z.infer<typeof <%= form.pascal %>Schema>;
 
+/** Convert a browser form submission into the typed shape expected by Fimo. */
+export function parse<%= form.pascal %>FormData(formData: FormData): <%= form.pascal %>Data {
+  const data: Record<string, unknown> = {};
+<% Object.entries(form.fields).forEach(([key, field], index) => { -%>
+<% if (field.type === 'checkbox') { -%>
+  data[<%= JSON.stringify(key) %>] = ['on', 'true', '1'].includes(formData.get(<%= JSON.stringify(key) %>) as string);
+<% } else if (field.type === 'number') { -%>
+  const <%= localName(key, index) %> = formData.get(<%= JSON.stringify(key) %>);
+  if (<%= localName(key, index) %> !== null && <%= localName(key, index) %> !== '') data[<%= JSON.stringify(key) %>] = Number(<%= localName(key, index) %>);
+<% } else { -%>
+  const <%= localName(key, index) %> = formData.get(<%= JSON.stringify(key) %>);
+  if (<%= localName(key, index) %> !== null) data[<%= JSON.stringify(key) %>] = <%= localName(key, index) %>;
+<% } -%>
+<% }); -%>
+  return <%= form.pascal %>Schema.parse(data);
+}
+
 // @ts-ignore - meta.env is a vite feature
 const base = import.meta.env.VITE_API_URL;
 <% if (hasFileFields) { %>
@@ -135,8 +151,13 @@ async function uploadFile(file: File): Promise<string> {
 <% } %>
 export async function submit<%= form.pascal %>(data: <%= form.pascal %>Data): Promise<{
   success: boolean;
+  status: number;
   errors?: Record<string, string>;
 }> {
+  if (!FORM_ID || FORM_ID === "undefined") {
+    throw new Error(`Form "${FORM_ID || "unknown"}" has not been pushed. Run fimo forms push first.`);
+  }
+
 <% if (hasFileFields) { -%>
   const payload: Record<string, unknown> = { ...data };
 
@@ -144,9 +165,9 @@ export async function submit<%= form.pascal %>(data: <%= form.pascal %>Data): Pr
   await Promise.all([
 <% fileFieldKeys.forEach((key) => { -%>
     (async () => {
-      const file = data.<%= key %>;
-      if (file instanceof File) {
-        payload.<%= key %> = await uploadFile(file);
+      const file = data[<%= JSON.stringify(key) %>];
+      if (typeof File !== "undefined" && file instanceof File) {
+        payload[<%= JSON.stringify(key) %>] = await uploadFile(file);
       }
     })(),
 <% }); -%>
@@ -160,7 +181,7 @@ export async function submit<%= form.pascal %>(data: <%= form.pascal %>Data): Pr
       body: JSON.stringify(payload),
     });
   } catch {
-    return { success: false };
+    return { success: false, status: 0 };
   }
 <% } else { -%>
   let res: Response;
@@ -171,18 +192,18 @@ export async function submit<%= form.pascal %>(data: <%= form.pascal %>Data): Pr
       body: JSON.stringify(data),
     });
   } catch {
-    return { success: false };
+    return { success: false, status: 0 };
   }
 <% } -%>
 
   if (res.ok) {
-    return { success: true };
+    return { success: true, status: res.status };
   }
 
   if (res.status === 422) {
     const json = await res.json();
-    return { success: false, errors: json.errors };
+    return { success: false, status: res.status, errors: json.errors };
   }
 
-  return { success: false };
+  return { success: false, status: res.status };
 }

package/assets/skills/fimo-cli/references/forms.md

@@ -8,7 +8,7 @@ This file covers the **CLI workflow** for forms. Use it when the user wants to a
 
 1. Write `src/forms/{name}.json` — kebab-case filename (e.g. `contact-us.json`). For the JSON spec and field types, run `fimo skills get fimo-code --ref forms`.
 2. Register with `fimo forms push {name}` — creates the form, obtains its `id`, patches it back into the JSON file.
-3. Pre-build generates `src/forms/{name}.ts` (Zod schema + `submitX` helper). Use the same `fimo-code` reference for the generated API.
+3. Validation/build generates `src/forms/{name}.ts` (Zod schema, `parseXFormData`, and `submitX` helper). Next.js also gets `{name}.client.ts`; other adapters keep one module. Use the same `fimo-code` reference for the generated API.
 4. Write the application form using the generated `@/forms/{name}` module and the existing framework conventions.
 
 Steps 1, 3, and 4 reference the `fimo-code` skill (`fimo skills get fimo-code`). Step 2 is the CLI command.
@@ -54,7 +54,7 @@ Use this when the user asks "who filled out the contact form?", "how many signup
 
 ## When to run sync manually
 
-The `fimo/vite` plugin regenerates `src/forms/*.ts` after form JSON changes during development. Before a production build, regenerate explicitly with:
+The `fimo/vite` plugin regenerates legacy Vite `src/forms/*.ts` after form JSON changes during development. Framework-aware generation runs during validation. Before a production build, regenerate explicitly with:
 
 ```bash
 fimo validate                  # runs all phases: codegen, lint, route validation, label checks

package/assets/skills/fimo-cli/references/init.md

@@ -11,7 +11,7 @@ fimo init [dir] [options]
 `fimo init` runs the full onboarding in one shot:
 
 1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED` (run `fimo login` first).
-2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use React Router by default; `--framework nextjs` and `--framework sveltekit` select minimal framework-native shells. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project without `--project-id`.
+2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use React Router by default; `--framework astro`, `--framework nextjs`, and `--framework sveltekit` select minimal framework-native shells. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project without `--project-id`.
 3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
 4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
 
@@ -21,7 +21,7 @@ fimo init [dir] [options]
 | `--project-id <id>`          | no                            | Set up the named Fimo project: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                                     |
 | `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.             |
 | `--env <name>`               | no                            | Env to check out when linking an existing project (defaults to `main`).                                                                                        |
-| `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default), `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved.                                    |
+| `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default), `astro`, `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved.                           |
 | `--starter <id>`             | no                            | Opt-in project starter for create-new (currently `fimo-site@1`). It seeds CMS content, labels, a contact form, and manual-only agents. Rejects `--project-id`. |
 | `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                            |
 | `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                                      |
@@ -65,15 +65,17 @@ Omit `--framework` for the existing React Router scaffold, or select a
 minimal framework-native shell explicitly:
 
 ```bash
+fimo init my-astro-site --framework astro --org <organizationId>
 fimo init my-next-site --framework nextjs --org <organizationId>
 fimo init my-svelte-site --framework sveltekit --org <organizationId>
 ```
 
-Both shells include their framework adapter, hosted-preview connector, and
-`.fimo/config.json#runtime.framework`. They intentionally contain no schema,
-labels, or designed website. After init, load the project rules and `fimo-code`
-to build the requested site. The current `fimo-site@1` content starter supports
-React Router only.
+Each shell includes its framework adapter, hosted-preview connector, and
+`.fimo/config.json#runtime.framework`. The Astro shell also includes a minimal
+content-backed example with static, on-demand, and dynamic routes plus an English default locale;
+the other shells intentionally contain no schema, labels, or designed website.
+After init, load the project rules and `fimo-code` to build the requested site.
+The current `fimo-site@1` content starter supports React Router only.
 
 For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for Claude Code, `--agents=cursor` for Cursor, `--agents=codex` for Codex, etc. When the flag is omitted, env-var detection of the invoking harness (e.g. `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT` → claude-code) auto-targets that agent; other agents must be selected explicitly via `--agents`/`-a` or the interactive picker.
 
@@ -85,7 +87,7 @@ Pass `--project-id <id>` to set up a known Fimo project. If the project has no c
 
 `fimo init` (create-new path) scaffolds:
 
-- The selected project shell: React Router by default, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
+- The selected project shell: React Router by default, Astro with `--framework astro`, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
 - `.fimo/project.json` — links this directory to the remote project (read-only after creation)
 - `.fimo/config.json` — project, route, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles

package/assets/skills/fimo-cli/references/projects.md

@@ -6,7 +6,7 @@ Commands for listing projects across an org, cloning a remote project locally, a
 
 ```bash
 fimo projects list [--org <id>]                 # list projects in an org (defaults to active org)
-fimo projects create [dir] [--org <id>] [--framework react-router|nextjs] [--install|--no-install]
+fimo projects create [dir] [--org <id>] [--framework react-router|astro|nextjs|sveltekit] [--install|--no-install]
 fimo projects clone [projectId] [dir] [--env <name>] # clone an existing project locally
 fimo projects delete [projectId] [-C <dir>] [-y] # delete (defaults to current project)
 fimo projects publish [projectId] [-C <dir>]     # make the project live (publish from main)

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

@@ -2,7 +2,7 @@
 
 > For the CLI workflow (`fimo forms push`, "Add a contact form" recipe), see **`fimo-cli/references/forms.md`**.
 
-This file covers the **package surface**: the JSON spec you write, the generated Zod schema + `submitX` helper you import, the React patterns. Version-locked to the project's `fimo` package.
+This file covers the **package surface**: the JSON spec, generated Zod schema, `parseXFormData`, and `submitX` helper. Version-locked to the project's `fimo` package. The application owns form markup, actions, routing, locale, and UX.
 
 ## Form JSON spec
 
@@ -43,7 +43,7 @@ This file covers the **package surface**: the JSON spec you write, the generated
 
 ## Generated TS client
 
-After pre-build (or `fimo deploy`), `src/forms/{name}.ts` exists with:
+After `fimo forms push` and the next validation/build, `src/forms/{name}.ts` exists with:
 
 ```ts
 export const FORM_ID = '<uuid>';
@@ -51,20 +51,28 @@ export const ContactUsSchema = z.object({
   /* fields */
 });
 export type ContactUsData = z.infer<typeof ContactUsSchema>;
-export async function submitContactUs(data): Promise<{ success: boolean; errors?: Record<string, string> }>;
+export function parseContactUsFormData(formData: FormData): ContactUsData;
+export function submitContactUs(
+  data: ContactUsData,
+  client?
+): Promise<{
+  success: boolean;
+  status: number;
+  errors?: Record<string, string>;
+}>;
 ```
 
-Re-exported by `src/forms/index.ts`.
+The schema, parser, submitter, and form id are re-exported by `src/forms/index.ts`.
 
-The `submitX` helper handles fetch + file uploads (presigned URLs) automatically. Never hand-roll fetch or validation.
+The `submitX` helper uses the framework adapter's shared Fimo transport and handles presigned file uploads automatically. Never hand-roll the Fimo API fetch or validation.
 
-## React code pattern
+## Common code pattern
 
-Always import from `@/forms/{name}` — never hand-roll fetch, never hand-roll validation.
+Always import the generated module. Keep the native form and pending/error state in the framework's normal pattern:
 
 ```tsx
 import { useState } from 'react';
-import { ContactUsSchema, submitContactUs } from '@/forms/contact-us';
+import { ContactUsSchema, parseContactUsFormData, submitContactUs } from '@/forms/contact-us';
 import type { ContactUsData } from '@/forms/contact-us';
 
 export function ContactForm() {
@@ -76,8 +84,7 @@ export function ContactForm() {
     setErrors({});
     setLoading(true);
 
-    const raw = Object.fromEntries(new FormData(e.currentTarget));
-    const parsed = ContactUsSchema.safeParse(raw);
+    const parsed = ContactUsSchema.safeParse(parseContactUsFormData(new FormData(e.currentTarget)));
     if (!parsed.success) {
       const fieldErrors: Record<string, string> = {};
       for (const issue of parsed.error.issues) fieldErrors[issue.path[0] as string] = issue.message;
@@ -97,6 +104,13 @@ export function ContactForm() {
 
 **File fields**: pass the raw `File` from `<input type="file">` to `submitX` — it handles the presigned upload automatically. **Never base64-encode.**
 
+## Framework bindings
+
+- **Vite/React:** `submitX(data)` keeps using the existing `fimo/ui` runtime and preserves the current generated API.
+- **Next.js:** server modules import `@/forms/name`; client components import `@/forms/name.client`. Both expose the same `submitX(data)` shape.
+- **Astro:** import the generated server module and call `submitX(data)` in an Astro action or endpoint. Astro keeps the HTML form and redirect.
+- **SvelteKit:** use `createFimoFormClient({ event })` in a server action and pass it as the second argument: `submitX(data, client)`.
+
 ## Labels and copy
 
 Wrap every visible string in `t('key')` and create the DB value with `fimo labels set` — see `references/labels.md`. This includes form labels, placeholders, button text, success/error messages.

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

@@ -75,6 +75,15 @@ const [settings, stories, labels] = await Promise.all([
 
 The native surface is `Text`, `RichText`, `Image`, `StaticImage`, `Video`, `Date`, `Boolean`, and `Json` (component table: `references/ui.md`). Pass tracked values whole so Studio can resolve their source; use `String(value)` only for attributes and URLs.
 
+## Forms
+
+Generated forms use the native Astro server adapter. Keep the form element,
+action, redirect, and error UI in Astro; call `submitX(data)` from an Astro
+action or endpoint. Use `parseXFormData(new FormData(request))` to normalize
+browser values before submitting. Do not import the server form module into a
+client island; add a project endpoint if the form is intentionally browser-
+submitted.
+
 ## Static and on-demand rendering
 
 Keep the application's per-route rendering choice:

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

@@ -82,6 +82,31 @@ Never write the registry by hand and never create alternate `*.schema.json` file
 
 ## Server and client boundaries
 
+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
+transport; do not call the tenant API directly.
+
+```tsx
+'use client';
+
+import { parseContactUsFormData, submitContactUs } from '@/forms/contact-us.client';
+
+export function ContactForm() {
+  return (
+    <form
+      action={async (formData) => {
+        await submitContactUs(parseContactUsFormData(formData));
+      }}
+    >
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
 Server Components, route handlers, `getStaticProps`, and `getServerSideProps` import from `fimo/next` and generated server modules:
 
 ```ts

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

@@ -59,17 +59,28 @@ export async function load(event) {
 }
 ```
 
-Resolve the locale with the application's existing policy, then fetch labels in
-the root server layout and publish the snapshot to descendants:
+Pass `createFimo` the locale the application resolved. Omit it and Fimo sends
+`.fimo/config.json#i18n.defaultLocale`, or no locale at all when none is
+configured, so the API answers with the project default. Never hardcode a locale
+to satisfy the signature.
+
+`getLabels` follows the same rule: pass the locale the application resolved, or
+omit it and the API answers with the project default, whose locale the returned
+snapshot reports. Fetch labels in the root server layout and publish the
+snapshot to descendants. Fimo resolves its injected content API URL internally;
+do not import a Fimo environment variable or hardcode a tenant URL:
 
 ```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 }) };
+  // 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 }) };
+
+  // Otherwise, omit it and use the Fimo project default.
+  return { labels: await getLabels({ event }) };
 }
 ```
 
@@ -94,6 +105,23 @@ component that renders them. Use `Text`, `RichText`, `Image`, `Video`, `Date`,
 formats plain numeric values for display; numeric fields currently have no
 source metadata, so it is not a Studio-editable primitive.
 
+## Forms
+
+Use a `+page.server` action so SvelteKit owns the request and redirect. Pass its
+event to `createFimoFormClient` and use the generated parser/helper:
+
+```ts
+import { createFimoFormClient } from 'fimo/sveltekit';
+import { parseContactUsFormData, submitContactUs } from '$lib/forms/contact-us';
+
+export const actions = {
+  default: async (event) => {
+    const data = parseContactUsFormData(await event.request.formData());
+    return submitContactUs(data, createFimoFormClient({ event }));
+  },
+};
+```
+
 ## Live preview
 
 `FimoProvider` owns the Studio browser bridge. On mount it reads

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

@@ -41,7 +41,7 @@ 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: `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.
+- SvelteKit: pass the application's resolved locale to `getLabels({ apiUrl, event, locale })`, or omit it to let the API choose the project default. 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`. Apply the same explicit-or-omitted rule to `createFimo({ content, event, locale? })` in content loads.
 - Astro server page: `getLabels({ locale? })` from `fimo/astro`; no provider.
 
 Load the matching framework reference before choosing a provider or server reader.

package/dist/build/sveltekit/config.d.ts

@@ -1,6 +1,7 @@
+import type { Adapter } from '@sveltejs/kit';
 /**
  * Configure a SvelteKit project for Fimo hosting without exposing the hosting
  * provider in the generated application.
  */
-export declare function fimo(): import("@sveltejs/kit").Adapter;
+export declare function fimo(): Adapter;
 //# sourceMappingURL=config.d.ts.map

package/dist/build/sveltekit/config.js

@@ -1,8 +1,18 @@
-import adapter from '@sveltejs/adapter-vercel';
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import fs from"node:fs";import path from"node:path";import process2 from"node:process";import{fileURLToPath}from"node:url";import{nodeFileTrace}from"@vercel/nft";import esbuild from"esbuild";import process from"node:process";function get_pathname(route){let i=1,pathname=route.segments.map(segment=>{if(!segment.dynamic)return"/"+segment.content;let parts=segment.content.split(/\[(.+?)\](?!\])/);return parts.length===3&&!parts[0]&&!parts[2]&&(parts[1].startsWith("...")||parts[1][0]==="[")?`$${i++}`:"/"+parts.map((content,j)=>j%2?`$${i++}`:content).join("")}).join("");return pathname[0]==="/"?pathname.slice(1):pathname}__name(get_pathname,"get_pathname");function pattern_to_src(pattern){let src=pattern.slice(1,-2).replace(/\\\//g,"/");return src==="^/"&&(src="^/?"),src=src.replace(/\(\?:\/\((.+?)\)\)/g,"(/$1)"),src}__name(pattern_to_src,"pattern_to_src");var integer=/^\d+$/;function parse_isr_expiration(value,route_id){if(value===!1||value==="false")return!1;let err=__name(desc=>{throw new Error(`Invalid isr.expiration value: ${JSON.stringify(value)} (${desc}, in ${route_id})`)},"err"),parsed;return typeof value=="string"?(integer.test(value)||err("value was a string but could not be parsed as an integer"),parsed=Number.parseInt(value,10)):(Number.isInteger(value)||err("should be an integer"),parsed=value),Number.isNaN(parsed)&&err("should be a number"),parsed<0&&err("should be non-negative"),parsed}__name(parse_isr_expiration,"parse_isr_expiration");function resolve_runtime(default_key,override_key){let key=(override_key??default_key??get_default_runtime()).replace("experimental_","");return assert_is_valid_runtime(key),key}__name(resolve_runtime,"resolve_runtime");var valid_node_versions=[20,22,24],formatter=new Intl.ListFormat("en",{type:"disjunction"});function get_default_runtime(){let major=Number(process.version.slice(1).split(".")[0]);if(!valid_node_versions.includes(major))throw new Error(`Unsupported Node.js version: ${process.version}. Please use Node ${formatter.format(valid_node_versions.map(v=>`${v}`))} to build your project, or explicitly specify a runtime in your adapter configuration.`);return`nodejs${major}.x`}__name(get_default_runtime,"get_default_runtime");var valid_runtimes=["nodejs20.x","nodejs22.x","nodejs24.x","bun1.x","edge"];function assert_is_valid_runtime(key){if(!valid_runtimes.includes(key))throw new Error(`Unsupported runtime: ${key}. Supported runtimes are: ${valid_runtimes.join(", ")}. See the Node.js Version section in your Vercel project settings for info on the currently supported versions.`)}__name(assert_is_valid_runtime,"assert_is_valid_runtime");import{VERSION}from"@sveltejs/kit";var name="@sveltejs/adapter-vercel",INTERNAL="![-]",[kit_major,kit_minor]=VERSION.split("."),compatible_node_modules=["async_hooks","events","buffer","assert","util"],plugin=__name(function(defaults={}){if("edge"in defaults)throw new Error("{ edge: true } has been removed in favour of { runtime: 'edge' }");return{name,async adapt(builder){if(!builder.routes)throw new Error("@sveltejs/adapter-vercel >=2.x (possibly installed through @sveltejs/adapter-auto) requires @sveltejs/kit version 1.5 or higher. Either downgrade the adapter or upgrade @sveltejs/kit");let dir=".vercel/output",tmp=builder.getBuildDirectory("vercel-tmp");if(builder.rimraf(dir),builder.rimraf(tmp),fs.existsSync("vercel.json")){let vercel_file=fs.readFileSync("vercel.json","utf-8"),vercel_config=JSON.parse(vercel_file);validate_vercel_json(builder,vercel_config)}let files=fileURLToPath(new URL("./files",import.meta.url).href),dirs={static:`${dir}/static${builder.config.kit.paths.base}`,functions:`${dir}/functions`};builder.log.minor("Copying assets..."),builder.writeClient(dirs.static),builder.writePrerendered(dirs.static);let static_config=static_vercel_config(builder,defaults,dirs.static);builder.log.minor("Generating serverless function...");async function generate_serverless_function(name2,config,routes){let dir2=`${dirs.functions}/${name2}.func`,relativePath=path.posix.relative(tmp,builder.getServerDirectory());builder.copy(`${files}/serverless.js`,`${tmp}/index.js`,{replace:{SERVER:`${relativePath}/index.js`,MANIFEST:"./manifest.js"}}),builder.hasServerInstrumentationFile?.()&&builder.instrument?.({entrypoint:`${tmp}/index.js`,instrumentation:`${builder.getServerDirectory()}/instrumentation.server.js`}),write(`${tmp}/manifest.js`,`export const manifest = ${builder.generateManifest({relativePath,routes})};
+`),await create_function_bundle(builder,`${tmp}/index.js`,dir2,config);for(let asset of builder.findServerAssets(routes))builder.copy(`${builder.getServerDirectory()}/${asset}`,`${dir2}/${asset}`)}__name(generate_serverless_function,"generate_serverless_function");let warned=!1;async function generate_edge_function(name2,config,routes){warned||(warned=!0,builder.log.warn("The `runtime: 'edge'` option is deprecated, and will be removed in a future version of adapter-vercel"));let tmp2=builder.getBuildDirectory(`vercel-tmp/${name2}`),relativePath=path.posix.relative(tmp2,builder.getServerDirectory());builder.copy(`${files}/edge.js`,`${tmp2}/edge.js`,{replace:{SERVER:`${relativePath}/index.js`,MANIFEST:"./manifest.js"}}),write(`${tmp2}/manifest.js`,`export const manifest = ${builder.generateManifest({relativePath,routes})};
+`);try{let outdir=`${dirs.functions}/${name2}.func`,esbuild_config={target:"es2020",bundle:!0,platform:"browser",conditions:["edge-light","module"],format:"esm",external:[...compatible_node_modules,...compatible_node_modules.map(id=>`node:${id}`),...config.external||[]],sourcemap:"linked",banner:{js:"globalThis.global = globalThis;"},loader:{".wasm":"copy",".woff":"copy",".woff2":"copy",".ttf":"copy",".eot":"copy",".otf":"copy"}},result=await esbuild.build({entryPoints:[`${tmp2}/edge.js`],outfile:`${outdir}/index.js`,...esbuild_config}),instrumentation_result;builder.hasServerInstrumentationFile?.()&&(instrumentation_result=await esbuild.build({entryPoints:[`${builder.getServerDirectory()}/instrumentation.server.js`],outfile:`${outdir}/instrumentation.server.js`,...esbuild_config}),builder.instrument?.({entrypoint:`${outdir}/index.js`,instrumentation:`${outdir}/instrumentation.server.js`,module:{generateText:generate_traced_edge_module}}));let warnings=instrumentation_result?[...result.warnings,...instrumentation_result.warnings]:result.warnings;if(warnings.length>0){let formatted=await esbuild.formatMessages(warnings,{kind:"warning",color:!0});console.error(formatted.join(`
+`))}}catch(err){let error=err;for(let e of error.errors)for(let node of e.notes){let match=/The package "(.+)" wasn't found on the file system but is built into node/.exec(node.text);match&&(node.text=`Cannot use "${match[1]}" when deploying to Vercel Edge Functions.`)}let formatted=await esbuild.formatMessages(error.errors,{kind:"error",color:!0});throw console.error(formatted.join(`
+`)),new Error(`Bundling with esbuild failed with ${error.errors.length} ${error.errors.length===1?"error":"errors"}`,{cause:err})}write(`${dirs.functions}/${name2}.func/.vc-config.json`,JSON.stringify({runtime:config.runtime,regions:config.regions,entrypoint:"index.js",framework:{slug:"sveltekit",version:VERSION}},null,"	"))}__name(generate_edge_function,"generate_edge_function");let groups=new Map,conflicts=new Map,functions=new Map,isr_config=new Map,ignored_isr=new Set;for(let route of builder.routes){let runtime=resolve_runtime(defaults.runtime,route.config.runtime),config={...defaults,...route.config,runtime};if(is_prerendered(route)){config.isr&&ignored_isr.add(route.id);continue}if(config.isr){let directory=path.relative(".",builder.config.kit.files.routes+route.id);if(runtime==="edge")throw new Error(`${directory}: Routes using \`isr\` must use a Node.js or Bun runtime (for example 'nodejs24.x' or 'experimental_bun1.x')`);if(config.isr.allowQuery?.includes("__pathname"))throw new Error(`${directory}: \`__pathname\` is a reserved query parameter for \`isr.allowQuery\``);isr_config.set(route,{expiration:config.isr.expiration,bypassToken:config.isr.bypassToken,allowQuery:["__pathname",...config.isr.allowQuery??[]],group:isr_config.size+1,passQuery:!0})}let hash=hash_config(config),pattern=route.pattern.toString(),existing=conflicts.get(pattern);if(existing){if(existing.hash!==hash)throw new Error(`The ${route.id} and ${existing.route_id} routes must be merged into a single function that matches the ${route.pattern} regex, but they have incompatible configs. You must either rename one of the routes, or make their configs match.`)}else conflicts.set(pattern,{hash,route_id:route.id});let id=config.split?`${hash}-${groups.size}`:hash,group=groups.get(id);group||(group={i:groups.size,config,routes:[]},groups.set(id,group)),group.routes.push(route)}if(ignored_isr.size){builder.log.warn(`
+Warning: The following routes have an ISR config which is ignored because the route is prerendered:`);for(let ignored of ignored_isr)console.log(`    - ${ignored}`);console.log(`Either remove the "prerender" option from these routes to use ISR, or remove the ISR config.
+`)}let singular=groups.size===1;for(let group of groups.values()){let generate_function=group.config.runtime==="edge"?generate_edge_function:generate_serverless_function,name2=singular?`${INTERNAL}/catchall`:`${INTERNAL}/${group.i}`;await generate_function(name2,group.config,group.routes);for(let route of group.routes)functions.set(route.pattern.toString(),name2)}if(!singular){let runtime=resolve_runtime(defaults.runtime);await(runtime==="edge"?generate_edge_function:generate_serverless_function)(`${INTERNAL}/catchall`,{...defaults,runtime},[])}if(builder.config.kit.experimental.remoteFunctions){let app_path=builder.getAppPath(),remote_symlink_path=`${path.join(dirs.functions,app_path,"remote")}.func`,target=path.join(dirs.functions,INTERNAL,"catchall.func");builder.mkdirp(path.join(dirs.functions,app_path));let relative=path.relative(path.dirname(remote_symlink_path),target);fs.symlinkSync(relative,remote_symlink_path),static_config.routes.push({src:`/${app_path}/remote/.+`,dest:`/${app_path}/remote`})}for(let route of builder.routes){if(is_prerendered(route))continue;let pattern=route.pattern.toString(),src=pattern_to_src(pattern),name2=functions.get(pattern),isr=isr_config.get(route);if(isr){let isr_name=route.id.slice(1)||"__root__",base=`${dirs.functions}/${isr_name}`;builder.mkdirp(base);let target=`${dirs.functions}/${name2}.func`,relative=path.relative(path.dirname(base),target);fs.symlinkSync(relative,`${base}.func`),fs.symlinkSync(`../${relative}`,`${base}/__data.json.func`);let pathname=get_pathname(route),json=JSON.stringify({...isr,expiration:parse_isr_expiration(isr.expiration,route.id)},null,"	");write(`${base}.prerender-config.json`,json),write(`${base}/__data.json.prerender-config.json`,json);let q=`?__pathname=/${pathname}`;static_config.routes.push({src:src+"$",dest:`/${isr_name}${q}`}),static_config.routes.push({src:src+"/__data.json$",dest:`/${isr_name}/__data.json${q}`})}else{let is_root=route.id==="/",route_fs_name=is_root?"index":route.id.slice(1),route_dest_name=is_root?"":route.id.slice(1),base_dir=path.join(dirs.functions,route_fs_name),main_symlink_path=`${base_dir}.func`,data_symlink_path=path.join(base_dir,"__data.json.func"),target=path.join(dirs.functions,`${name2}.func`);builder.mkdirp(base_dir);let relative_for_main=path.relative(path.dirname(main_symlink_path),target),relative_for_data=path.relative(path.dirname(data_symlink_path),target);fs.symlinkSync(relative_for_main,main_symlink_path),fs.symlinkSync(relative_for_data,data_symlink_path),static_config.routes.push({src:src+"(?:/__data.json)?$",dest:`/${route_dest_name}`})}}builder.config.kit.router?.resolution==="server"&&(await generate_edge_function(`${builder.config.kit.appDir}/route`,{external:"external"in defaults?defaults.external:void 0,runtime:"edge"},[]),static_config.routes.push({src:`${builder.config.kit.paths.base}/(|.+/)__route\\.js`,dest:`${builder.config.kit.paths.base}/${builder.config.kit.appDir}/route`})),static_config.routes.push({src:"/.*",dest:`/${INTERNAL}/catchall`}),builder.log.minor("Writing routes..."),write(`${dir}/config.json`,JSON.stringify(static_config,null,"	"))},supports:{read:__name(({config,route})=>{if((config.runtime??defaults.runtime)==="edge"&&kit_major==="2"&&kit_minor<"25")throw new Error(`${name}: Cannot use \`read\` from \`$app/server\` in route \`${route.id}\` configured with \`runtime: 'edge'\` and SvelteKit < 2.25.0`);return!0},"read"),instrumentation:__name(()=>!0,"instrumentation")}}},"plugin");function hash_config(config){return[config.runtime??"",config.external??"",config.regions??"",config.memory??"",config.maxDuration??"",!!config.isr].join("/")}__name(hash_config,"hash_config");function write(file,data){try{fs.mkdirSync(path.dirname(file),{recursive:!0})}catch{}fs.writeFileSync(file,data)}__name(write,"write");function static_vercel_config(builder,config,dir){let prerendered_redirects=[],overrides={},images=config.images;for(let[src,redirect]of builder.prerendered.redirects)src.replace(/\/$/,"")===redirect.location.replace(/\/$/,"")||(src=src.replace(/\/?$/,"/?")),prerendered_redirects.push({src,headers:{Location:redirect.location},status:redirect.status});for(let[path2,page]of builder.prerendered.pages){let overrides_path=path2.slice(1);if(path2!=="/"){let counterpart_route=path2+"/";path2.endsWith("/")&&(counterpart_route=path2.slice(0,-1),overrides_path=path2.slice(1,-1)),prerendered_redirects.push({src:path2,dest:counterpart_route},{src:counterpart_route,status:308,headers:{Location:path2}})}overrides[page.file]={path:overrides_path}}let routes=[{src:".*",continue:!0,transforms:[{type:"request.query",op:"delete",target:{key:"__pathname"}}]},...prerendered_redirects,{src:`/${builder.getAppPath()}/immutable/.+`,headers:{"cache-control":"public, immutable, max-age=31536000"}}];if(process2.env.VERCEL_SKEW_PROTECTION_ENABLED){routes.push({src:"/.*",has:[{type:"header",key:"Sec-Fetch-Dest",value:"document"}],headers:{"Set-Cookie":`__vdpl=${process2.env.VERCEL_DEPLOYMENT_ID}; Path=${builder.config.kit.paths.base}/; SameSite=Strict; Secure; HttpOnly`},continue:!0});let base=`${dir}/${builder.config.kit.appDir}/immutable/entry`,entry=fs.readdirSync(base).find(file=>file.startsWith("start."));if(!entry)throw new Error("Could not find entry point");routes.splice(-2,0,{src:`/${builder.getAppPath()}/immutable/entry/${entry}`,headers:{"Set-Cookie":`__vdpl=; Path=/${builder.getAppPath()}/version.json; SameSite=Strict; Secure; HttpOnly`},continue:!0})}return routes.push({handle:"filesystem"}),routes.push({src:`/${builder.getAppPath()}/immutable/.+`,status:404,headers:{"cache-control":"no-store"},continue:!1}),{version:3,routes,overrides,images}}__name(static_vercel_config,"static_vercel_config");async function create_function_bundle(builder,entry,dir,config){fs.rmSync(dir,{force:!0,recursive:!0});let base=entry;for(;base!==(base=path.dirname(base)););let traced=await nodeFileTrace([entry],{base}),resolution_failures=new Map;if(traced.warnings.forEach(error=>{if(!error.message.startsWith("Failed to resolve dependency node:")&&!error.message.startsWith("Failed to parse"))if(error.message.startsWith("Failed to resolve dependency")){let match=/Cannot find module '(.+?)' loaded from (.+)/,[,module,importer]=match.exec(error.message)??[,error.message,"(unknown)"];resolution_failures.has(importer)||resolution_failures.set(importer,[]),resolution_failures.get(importer).push(module)}else throw error}),resolution_failures.size>0){let cwd=process2.cwd();builder.log.warn("Warning: The following modules failed to locate dependencies that may (or may not) be required for your app to work:");for(let[importer,modules]of resolution_failures){console.error(`  ${path.relative(cwd,importer)}`);for(let module of modules)console.error(`    - \x1B[1m\x1B[36m${module}\x1B[39m\x1B[22m`)}}let files=Array.from(traced.fileList),common_parts=files[0]?.split(path.sep)??[];for(let i=1;i<files.length;i+=1){let parts=files[i].split(path.sep);for(let j=0;j<common_parts.length;j+=1)if(parts[j]!==common_parts[j]){common_parts=common_parts.slice(0,j);break}}let ancestor=base+common_parts.join(path.sep);for(let file of traced.fileList){let source=base+file,dest=path.join(dir,path.relative(ancestor,source)),is_dir=fs.statSync(source).isDirectory(),realpath=fs.realpathSync(source);try{fs.mkdirSync(path.dirname(dest),{recursive:!0})}catch{}if(source!==realpath){let realdest=path.join(dir,path.relative(ancestor,realpath));fs.symlinkSync(path.relative(path.dirname(dest),realdest),dest,is_dir?"dir":"file")}else is_dir||fs.copyFileSync(source,dest)}write(`${dir}/.vc-config.json`,JSON.stringify({runtime:config.runtime,regions:config.regions,memory:config.memory,maxDuration:config.maxDuration,handler:path.relative(base+ancestor,entry),launcherType:"Nodejs",experimentalResponseStreaming:!config.isr,framework:{slug:"sveltekit",version:VERSION}},null,"	")),write(`${dir}/package.json`,JSON.stringify({type:"module"}))}__name(create_function_bundle,"create_function_bundle");function validate_vercel_json(builder,vercel_config){if(builder.routes.length>0&&!builder.routes[0].api)return;let crons=Array.isArray(vercel_config?.crons)?vercel_config.crons:[],valid_routes=builder.routes.filter(route=>route.api.methods.includes("GET")),unmatched_paths=[];for(let cron of crons){if(typeof cron!="object"||cron===null||!("path"in cron))continue;let{path:path2}=cron;typeof path2=="string"&&(valid_routes.some(route=>route.pattern.test(path2))||unmatched_paths.push(path2))}if(unmatched_paths.length){builder.log.warn("\nWarning: vercel.json defines cron tasks that use paths that do not correspond to an API route with a GET handler (ignore this if the request is handled in your `handle` hook):");for(let path2 of unmatched_paths)console.log(`    - ${path2}`);console.log("")}}__name(validate_vercel_json,"validate_vercel_json");function is_prerendered(route){return route.prerender===!0||route.prerender==="auto"&&route.segments.every(segment=>!segment.dynamic)}__name(is_prerendered,"is_prerendered");function generate_traced_edge_module({instrumentation,start}){return`import './${instrumentation}';
+const promise = import('./${start}');
+
 /**
- * Configure a SvelteKit project for Fimo hosting without exposing the hosting
- * provider in the generated application.
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
  */
-export function fimo() {
-    return adapter({ runtime: 'nodejs24.x' });
+export default async (req, res) => {
+	const { default: handler } = await promise;
+	return handler(req, res);
 }
+`}__name(generate_traced_edge_module,"generate_traced_edge_module");var adapter_vercel_default=plugin;function fimo(){return adapter_vercel_default({runtime:"nodejs24.x"})}__name(fimo,"fimo");export{fimo};