@fraza/start 0.0.0-stage → 0.3.4

package/templates/app/(public)/[...slug]/page.js

@@ -0,0 +1,29 @@
+// Catch-all CMS : toute route non interceptée par un fichier statique
+// (admin, auth, /api/*, _next/*, et toute page écrite manuellement dans
+// (public)/) est dispatchée au registre `@fraza/core/public-content`.
+// Chaque module CMS s'enregistre avec une priorité : `module-posts` réserve
+// les URLs `/<postType>/<slug>` (priorité 10), `module-pages` sert le reste
+// (priorité 0, fallback hiérarchique).
+//
+// Pour ajouter un nouveau module CMS, il suffit qu'il appelle
+// `registerPublicContentResolver` à son boot, sans toucher au starter.
+// Pour fournir un template custom (avec ton branding), dépose un fichier
+// dans `components/fraza/templates/` puis lance `npx fraza-modules sync`.
+
+import { notFound } from 'next/navigation';
+import { resolvePublicContent, resolvePublicMetadata } from '@fraza/core/public-content';
+
+// `[...slug]` n'est pas optionnel : `/` est servi par `(public)/page.js`, et
+// `slug` arrive donc toujours sous forme d'un tableau non vide.
+export default async function PublicCatchAll({ params }) {
+  const { slug } = await params;
+  const match = await resolvePublicContent(slug);
+  if (!match) notFound();
+  const { Component, props } = match;
+  return <Component {...props} />;
+}
+
+export async function generateMetadata({ params }) {
+  const { slug } = await params;
+  return (await resolvePublicMetadata(slug)) || {};
+}

package/templates/app/(public)/error.js

@@ -0,0 +1,6 @@
+'use client';
+
+// Erreur au rendu d'une page du site public. Comme la page 404, c'est un
+// gabarit : remplacer le réexport par un composant du projet pour lui donner
+// l'allure du site.
+export { default } from '@fraza/core/shared/public/error';

package/templates/app/(public)/layout.js

@@ -0,0 +1,17 @@
+import { getPublicBrand } from "@fraza/core/shared/config";
+
+// Titre par défaut des pages publiques : le nom du site, `FRAZA_NAME`. Une page
+// qui déclare son propre titre le remplace. Sans `FRAZA_NAME`, aucun titre
+// n'est inventé : un nom par défaut signerait le site de quelqu'un d'autre.
+export function generateMetadata() {
+	const { name } = getPublicBrand();
+	return name ? { title: name } : {};
+}
+
+export default function layout({ children }) {
+	return (
+		<>
+			{children}
+		</>
+	);
+}

package/templates/app/(public)/not-found.js

@@ -0,0 +1,20 @@
+import Button from "@fraza/core/shared/components/Button";
+
+// Page 404 du site public. Comme la page d'accueil, c'est un gabarit : elle se
+// remplace dès que le site a sa propre allure.
+export default function NotFound() {
+	return (
+		<main className="flex min-h-screen items-center justify-center bg-canvas px-4 font-ui text-fg">
+			<div className="flex max-w-sm flex-col items-center gap-1 text-center">
+				<p className="font-code text-[12.5px] text-fg-subtle">404</p>
+				<h1 className="text-2xl font-bold tracking-[-0.03em]">Page introuvable</h1>
+				<p className="text-[13px] leading-relaxed text-fg-muted">
+					Cette page n'existe pas ou n'est plus en ligne.
+				</p>
+				<Button href="/" variant="link" className="mt-3">
+					Retour à l'accueil →
+				</Button>
+			</div>
+		</main>
+	);
+}

package/templates/app/(public)/page.js

@@ -0,0 +1,248 @@
+import { connection } from "next/server";
+import Button from "@fraza/core/shared/components/Button";
+import FrazaLogo from "@fraza/core/shared/components/FrazaLogo";
+import { tableExists } from "@fraza/core/database";
+import { countUsers } from "@fraza/core/users";
+
+// Point de départ du site public. Cette page est un gabarit : elle se remplace
+// entièrement dès que le site prend forme. Elle ne déclare pas de métadonnées :
+// son titre est celui du layout public, le nom du site (`FRAZA_NAME`).
+//
+// Elle suit la mise en route du projet : chaque étape est lue à chaque
+// chargement (variables, tables, premier compte), et seule la première étape
+// non faite est détaillée.
+
+const files = [
+	"app/(public)/page.js",
+	"app/(public)/layout.js",
+	"components/fraza/templates/",
+	"components/fraza/blocks/",
+];
+
+// Code en ligne : ce qui se copie (commande, fichier, chemin) passe en mono.
+const chip = "rounded-item bg-surface-muted px-2 py-0.5 font-code text-xs text-fg-secondary";
+
+/**
+ * État de la mise en route, lu à chaque requête. La base n'est interrogée que
+ * si ses variables sont posées : sans elles, le pool lèverait une erreur.
+ */
+async function readSetup() {
+	const env = {
+		database: Boolean(process.env.FRAZA_DATABASE_URL),
+		encryptionKey: Boolean(process.env.FRAZA_ENCRYPTION_KEY),
+	};
+	const state = { env, envReady: env.database && env.encryptionKey, tables: false, users: 0, unreachable: false };
+	if (!state.envReady) return state;
+
+	try {
+		state.tables = await tableExists("fraza_auth_users");
+		if (state.tables) state.users = await countUsers();
+	} catch {
+		state.unreachable = true;
+	}
+	return state;
+}
+
+function StepMarker({ status, number }) {
+	if (status === "done") {
+		return (
+			<span className="flex size-5 shrink-0 items-center justify-center rounded-full bg-success-soft text-success">
+				<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.4" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+					<path d="M5 12.5l4.5 4.5L19 7.5" />
+				</svg>
+			</span>
+		);
+	}
+	if (status === "current") {
+		return (
+			<span className="flex size-5 shrink-0 items-center justify-center rounded-full border-2 border-accent text-[11px] font-semibold text-accent">
+				{number}
+			</span>
+		);
+	}
+	return (
+		<span className="flex size-5 shrink-0 items-center justify-center rounded-full border border-line-strong text-[11px] font-medium text-fg-muted">
+			{number}
+		</span>
+	);
+}
+
+function EnvRow({ name, filled }) {
+	return (
+		<div className="flex items-center justify-between gap-3 border-b border-line-soft px-3 py-2 last:border-b-0">
+			<span className="font-code text-[12.5px] text-fg">{name}</span>
+			<span className={`text-xs font-medium ${filled ? "text-success" : "text-fg-muted"}`}>
+				{filled ? "Renseignée" : "Vide"}
+			</span>
+		</div>
+	);
+}
+
+export default async function Page() {
+	// Lue à chaque requête : l'état change pendant que le développeur avance.
+	await connection();
+	const setup = await readSetup();
+
+	const steps = [
+		{ title: "Créer le projet", done: true },
+		{
+			title: "Remplir le .env.local",
+			done: setup.envReady,
+			detail: (
+				<>
+					<p className="text-[12.5px] leading-relaxed text-fg-secondary">
+						Les valeurs restent sur cette machine : git ignore le fichier.
+					</p>
+					<div className="rounded-control border border-line bg-surface">
+						<EnvRow name="FRAZA_DATABASE_URL" filled={setup.env.database} />
+						<EnvRow name="FRAZA_ENCRYPTION_KEY" filled={setup.env.encryptionKey} />
+					</div>
+				</>
+			),
+		},
+		{
+			title: "Initialiser la base",
+			done: setup.tables,
+			hint: <code className="font-code text-[12.5px]">npx fraza-db init</code>,
+			detail: setup.unreachable ? (
+				<p className="text-[12.5px] leading-relaxed text-fg-secondary">
+					La base ne répond pas. Vérifiez <code className={chip}>FRAZA_DATABASE_URL</code>, puis
+					lancez <code className={chip}>npx fraza-db init</code>.
+				</p>
+			) : (
+				<p className="text-[12.5px] leading-relaxed text-fg-secondary">
+					Crée les tables du core et des modules installés :{" "}
+					<code className={chip}>npx fraza-db init</code>
+				</p>
+			),
+		},
+		{
+			title: "Créer le premier compte",
+			done: setup.users > 0,
+			hint: "Sur /auth. Le premier compte reçoit le rôle admin.",
+			detail: (
+				<p className="text-[12.5px] leading-relaxed text-fg-secondary">
+					Sur /auth. Le premier compte reçoit le rôle admin et ouvre l'administration.
+				</p>
+			),
+		},
+	];
+
+	const currentIndex = steps.findIndex((step) => !step.done);
+	const doneCount = steps.filter((step) => step.done).length;
+	const remaining = steps.length - doneCount;
+	const ready = currentIndex === -1;
+
+	return (
+		<main className="flex min-h-screen items-center justify-center bg-canvas px-6 py-18 font-ui text-fg">
+			<div className="flex w-full max-w-[1040px] flex-wrap items-center gap-x-18 gap-y-12">
+
+				<section className="flex flex-[1_1_360px] flex-col gap-6">
+					<FrazaLogo className="h-5 w-auto self-start text-fg" />
+
+					<div className="flex flex-col gap-2.5">
+						{/* Titre d'écran de la charte, comme les pages publiques des modules. */}
+						<h1 className="text-[32px] leading-tight font-bold tracking-[-0.035em]">
+							Votre projet est prêt.
+						</h1>
+						<p className="text-sm leading-relaxed text-fg-muted">
+							{ready
+								? "Tout est en place. Le site public part de cette page : remplacez-la quand il prend forme."
+								: `Encore ${remaining} ${remaining > 1 ? "étapes" : "étape"} avant d'ouvrir l'administration. Cette page se met à jour à mesure que vous avancez.`}
+						</p>
+					</div>
+
+					<div className="flex flex-col gap-2.5 border-t border-line pt-5">
+						<h2 className="text-[12.5px] font-semibold">Ensuite, le site public</h2>
+						<p className="text-[12.5px] leading-relaxed text-fg-muted">
+							Cette page est un gabarit. Remplacez-la quand le site prend forme.
+						</p>
+						<ul className="flex flex-wrap gap-1.5">
+							{files.map((file) => (
+								<li key={file}>
+									<code className={chip}>{file}</code>
+								</li>
+							))}
+						</ul>
+					</div>
+
+					<p className="text-xs text-fg-muted">
+						Livrée par @fraza/start ·{" "}
+						<Button href="https://docs.fraza.ca" target="_blank" variant="link" size="sm">
+							docs.fraza.ca
+						</Button>
+					</p>
+				</section>
+
+				<section className="min-w-0 flex-[1_1_460px] overflow-hidden rounded-card border border-line bg-surface">
+					<div className="flex items-center gap-3 px-6 py-4">
+						<h2 className="text-[15px] font-semibold">Mise en route</h2>
+						<div className="h-1 flex-1 overflow-hidden rounded-full bg-surface-muted">
+							<div
+								className="h-full rounded-full bg-accent"
+								style={{ width: `${(doneCount / steps.length) * 100}%` }}
+							/>
+						</div>
+						<span className="text-xs text-fg-muted tabular-nums">
+							{doneCount} sur {steps.length}
+						</span>
+					</div>
+
+					<ol>
+						{steps.map((step, index) => {
+							const status = step.done ? "done" : index === currentIndex ? "current" : "todo";
+							return (
+								<li
+									key={step.title}
+									aria-current={status === "current" ? "step" : undefined}
+									className={`flex gap-3.5 border-t border-line-soft px-6 ${status === "current" ? "bg-accent-soft py-4" : "py-3.5"}`}
+								>
+									<StepMarker status={status} number={index + 1} />
+									<div className="flex min-w-0 flex-1 flex-col gap-2.5">
+										<div className="flex flex-col gap-0.5">
+											<span
+												className={`text-[13.5px] ${status === "current" ? "font-semibold" : "font-medium"} ${status === "done" ? "text-fg-muted" : "text-fg"}`}
+											>
+												{step.title}
+											</span>
+											{status === "todo" && step.hint && (
+												<span className="text-[12.5px] text-fg-muted">{step.hint}</span>
+											)}
+										</div>
+										{status === "current" && step.detail}
+									</div>
+								</li>
+							);
+						})}
+					</ol>
+
+					<div className="flex flex-wrap items-center justify-between gap-3 border-t border-line px-6 py-3.5">
+						<Button
+							href="https://docs.fraza.ca/docs/demarrage/installation"
+							target="_blank"
+							variant="link"
+							size="sm"
+						>
+							Guide d'installation ↗
+						</Button>
+						<div className="flex gap-2">
+							{!ready && (
+								<Button href="/" variant="secondary">
+									Revérifier
+								</Button>
+							)}
+							{ready ? (
+								<Button href="/admin">Ouvrir l'administration</Button>
+							) : currentIndex === steps.length - 1 ? (
+								<Button href="/auth">Créer le premier compte</Button>
+							) : (
+								<Button disabled>Ouvrir l'administration</Button>
+							)}
+						</div>
+					</div>
+				</section>
+
+			</div>
+		</main>
+	);
+}

package/templates/app/.fraza/blocks.client.js

@@ -0,0 +1,8 @@
+// AUTO-GÉNÉRÉ par `npx fraza-modules sync` — ne pas modifier à la main.
+'use client';
+
+// Aucun block custom détecté dans `components/fraza/blocks/`.
+
+export default function FrazaBlocksClient() {
+  return null;
+}

package/templates/app/.fraza/blocks.server.js

@@ -0,0 +1,4 @@
+// AUTO-GÉNÉRÉ par `npx fraza-modules sync` — ne pas modifier à la main.
+
+// Aucun block custom détecté dans `components/fraza/blocks/`.
+export {};

package/templates/app/.fraza/modules.client.js

@@ -0,0 +1,6 @@
+// AUTO-GÉNÉRÉ par `npx fraza-modules sync` — ne pas modifier à la main.
+'use client';
+
+export default function FrazaModulesClient() {
+  return null;
+}

package/templates/app/.fraza/modules.generated.js

@@ -0,0 +1,3 @@
+// AUTO-GÉNÉRÉ par `npx fraza-modules sync` — ne pas modifier à la main.
+
+export const modules = [];

package/templates/app/.fraza/public-pages.server.js

@@ -0,0 +1,4 @@
+// AUTO-GÉNÉRÉ par `npx fraza-modules sync` — ne pas modifier à la main.
+
+// Aucun module installé n'expose de sous-entrée `./public-page`.
+export const publicPages = [];

package/templates/app/.fraza/sources.css

@@ -0,0 +1,2 @@
+/* AUTO-GÉNÉRÉ par `npx fraza-modules sync` — ne pas modifier à la main. */
+/* Fichiers compilés des modules activés, scannés par le Tailwind du projet. */

package/templates/app/.fraza/templates.server.js

@@ -0,0 +1,5 @@
+// AUTO-GÉNÉRÉ par `npx fraza-modules sync` — ne pas modifier à la main.
+
+// Aucun template détecté dans `components/fraza/templates/`.
+
+export {};

package/templates/app/global-error.js

@@ -0,0 +1,5 @@
+'use client';
+
+// Dernier recours, quand le layout racine lui-même échoue. Le composant du core
+// rend la page entière, `<html>` et `<body>` compris, comme Next l'exige ici.
+export { default } from '@fraza/core/shared/global-error';

package/templates/app/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48"><rect width="48" height="48" rx="11" fill="#0a0a0a"/><g transform="translate(9 9) scale(0.625)" fill="#fafafa"><path d="M17 9H40Q46 9 43.5 14.4L40 22H11Z"/><path d="M8 26H37L31 39H8Q2 39 4.5 33.6Z"/></g></svg>

package/templates/app/layout.js

@@ -0,0 +1,31 @@
+import "@styles/globals.css";
+// Side-effect : enregistre les blocs personnalisés dans le registre RSC serveur
+// (composants `render.js`). Importé ici, et pas seulement via
+// instrumentation.js, pour que les `render.js` marqués `'use client'`
+// traversent le compilateur RSC et soient référencés dans le React Client
+// Manifest. Sans cet import, un bloc au render client échoue avec
+// « Could not find the module … in the React Client Manifest » au rendu.
+import './.fraza/blocks.server.js';
+// Side-effect : enregistre les templates publics dans le registre RSC.
+// Importé ici (et non uniquement via instrumentation.js) pour que les
+// fichiers `components/fraza/templates/*.js` traversent le compilateur RSC
+// et que leurs `next/link` / `next/image` soient correctement référencés
+// dans le React Client Manifest.
+import './.fraza/templates.server.js';
+import { FrazaProvider } from '@fraza/core/features/provider';
+import { ThemeStyle } from '@fraza/core/themes/server';
+
+export default function RootLayout({ children }) {
+	return (
+		<html lang="fr" suppressHydrationWarning>
+			<head>
+				<ThemeStyle />
+			</head>
+			<body className="antialiased">
+				<FrazaProvider>
+					{children}
+				</FrazaProvider>
+			</body>
+		</html>
+	);
+}

package/templates/app/za/[...path]/not-found.js

@@ -0,0 +1,6 @@
+// 404 des pages publiques des modules (lien de facture expiré, formulaire
+// inactif, réservation fermée). Cette route vit hors du groupe `(public)`,
+// dont la page 404 ne s'applique donc pas ici : sans ce fichier, Next.js
+// afficherait sa page par défaut, en anglais et sans le thème. On reprend la
+// 404 du site public pour qu'il n'y en ait qu'une à personnaliser.
+export { default } from '../../(public)/not-found.js';

package/templates/app/za/[...path]/page.js

@@ -0,0 +1,8 @@
+// Side-effect : fait entrer les pages publiques des modules dans le graphe
+// RSC de cette route, pour que leurs composants `'use client'` soient
+// référencés dans le React Client Manifest. Sans cet import, une page publique
+// de module échoue avec « Could not find the module … in the React Client
+// Manifest ».
+import '../../.fraza/public-pages.server.js';
+
+export { default, generateMetadata } from '@fraza/core/public-pages/server';

package/templates/app/za/api/[...path]/route.js

@@ -0,0 +1 @@
+export { GET, POST, PUT, DELETE, PATCH } from '@fraza/core/api/handler';

package/templates/app/za/media/[filename]/route.js

@@ -0,0 +1 @@
+export { GET } from '@fraza/core/media-registry/file-route';

package/templates/components/fraza/blocks/README.md

@@ -0,0 +1,207 @@
+# Blocs personnalisés : `components/fraza/blocks/`
+
+Ce dossier contient les **blocs personnalisés** que tu ajoutes au
+`BlockEditor` du CMS. Un sous-dossier = un bloc. `npx fraza-modules sync` les
+trouve et les rend disponibles dans le menu `/` de tous les éditeurs (pages
+CMS, posts, etc.).
+
+## Anatomie d'un bloc
+
+Un bloc est un dossier avec **3 fichiers** :
+
+```
+components/fraza/blocks/<id>/
+├── fields.js      # métadonnées statiques (lues sans React)
+├── template.js    # composant d'édition, affiché dans l'administration
+└── render.js      # composant public, affiché sur le site
+```
+
+### `fields.js` : métadonnées
+
+Exporte deux objets : `meta` (description du bloc pour le menu `/`) et
+`defaults` (valeurs initiales d'une nouvelle instance).
+
+```js
+export const meta = {
+  id: 'mon-bloc',                    // unique dans le projet, [a-z0-9-] uniquement
+  label: 'Mon bloc',                  // libellé affiché dans le menu /
+  icon: 'LayersIcon',                 // nom d'une icône de @fraza/icons
+  keywords: ['custom', 'demo'],       // termes de recherche
+  category: 'Contenu',                // facultatif, regroupement
+};
+
+export const defaults = {
+  title: '',
+  // toutes les valeurs initiales du bloc...
+};
+```
+
+> **Pas d'import React ni de JSX dans `fields.js`** : ce fichier est lu côté
+> serveur et côté client au démarrage, pour valider et configurer le
+> registre. Les imports lourds y sont inutiles et ralentissent le démarrage.
+
+### `template.js` : éditeur de l'administration
+
+Composant React qui rend le bloc **dans l'éditeur**. Il doit porter
+`'use client'`. Il reçoit `{ block, onChange, disabled }` :
+
+- `block` : l'instance courante (fusionnée avec `defaults`) ;
+- `onChange(patch)` : applique une modification partielle. Passe **seulement
+  les champs modifiés**, pas le bloc complet ;
+- `disabled` : `true` en lecture seule (aperçu).
+
+`@fraza/core/blocks-registry/fields-ui` fournit des champs prêts à l'emploi,
+pour garder le même aspect que le reste de l'administration :
+
+| Composant | Usage |
+|---|---|
+| `<TextField>` | champ texte |
+| `<TextareaField>` | texte sur plusieurs lignes |
+| `<NumberField>` | champ numérique |
+| `<SelectField>` | menu déroulant |
+| `<BooleanField>` | case à cocher |
+| `<ColorField>` | sélecteur de couleur Fraza |
+| `<IconField>` | sélecteur d'icône parmi la liste passée par `icons` (fenêtre avec recherche ; enregistre le nom de l'icône) |
+| `<ImageField>` | sélecteur d'image (avec `MediaPicker` si module-medias est installé) |
+| `<FrazaBlockShell>` | conteneur recommandé (cadre pointillé neutre) |
+
+Tu peux aussi tout écrire à la main si ces champs ne suffisent pas : le seul
+contrat est `default export = composant React`.
+
+> **Style** : volontairement **neutre** (gris, noir, blanc, aucune classe
+> propre au site). L'administration reste ainsi homogène, quel que soit le
+> style du site public.
+
+### `render.js` : rendu public
+
+Composant React qui rend le bloc **sur le site public**, à la visite. Il
+reçoit `{ block }`.
+
+- Il utilise les classes et les styles **du site** (Tailwind, jetons du
+  thème…).
+- Il n'a pas de `onChange` : ce composant est en lecture seule.
+
+#### Ancre de bloc (`#slug`)
+
+Comme les blocs internes, un bloc personnalisé peut recevoir une **ancre**
+depuis l'éditeur (menu d'actions du bloc ▸ **Ancre**). C'est un identifiant
+stable, enregistré dans `block.anchor`, cible d'un lien interne `#slug`. À toi
+de la **rendre** : pose `id={block.anchor || undefined}` sur l'élément racine
+de ton `render.js`.
+
+```jsx
+export default function CalloutRender({ block }) {
+  return <div id={block.anchor || undefined} className="…">{block.text}</div>;
+}
+```
+
+> On l'écrit **directement** plutôt qu'avec `anchorProps` du core :
+> `@fraza/core/blocks-registry/render` est réservé au serveur, et ne
+> s'importe donc pas dans un `render.js` marqué `'use client'`. L'écriture
+> directe marche côté serveur comme côté client. Les quatre exemples fournis
+> la suivent.
+
+**Server component par défaut** (recommandé) : pas de directive en tête de
+fichier. Le composant peut lire des données et profite du rendu serveur
+complet, référencement compris.
+
+#### Liens saisis dans un bloc
+
+Un lien saisi dans un bloc (`href`) passe par `sanitizeUrl` de
+`@fraza/core/blocks-registry/url`, sous-entrée neutre, utilisable côté serveur
+comme côté client. Elle rend `''` pour une adresse au schéma refusé
+(`javascript:`, `data:`…) : n'écris alors aucun lien. La liste d'icônes
+fournie le fait.
+
+#### Lire des données dans un rendu serveur
+
+Un bloc qui affiche du contenu (posts, pages…) lit la donnée **directement
+côté serveur**, par les fonctions `./public` du module concerné. **Jamais** par
+un `fetch` HTTP vers `/za/api/...`. Le bloc tourne déjà dans le même
+processus que l'API. Un appel HTTP vers soi-même repasse par Next, refait le
+routage, interroge de nouveau la base et sérialise du JSON pour rien. En
+production, il ressort en plus par le proxy inverse ou le pare-feu
+applicatif, qui bloque souvent les requêtes de serveur à serveur : la section
+reste vide, sans erreur.
+
+```js
+// render.js (serveur) : lecture directe, sans fetch HTTP
+import { getPublicPosts } from '@fraza/module-posts/public';
+
+export default async function MonRender({ block }) {
+  const { posts } = await getPublicPosts(block.postType || 'blogue', { limit: 6 });
+  return (
+    <ul id={block.anchor || undefined}>
+      {posts.map((p) => <li key={p.id}>{p.title}</li>)}
+    </ul>
+  );
+}
+```
+
+Fonctions disponibles : `getPublicPosts` / `getPublicPostBySlug` /
+`getPublicTaxonomyTerms` (`@fraza/module-posts/public`), `listPublicChildPages` /
+`getPublishedPageBySegments` (`@fraza/module-pages/public`). Les routes HTTP
+`/za/api/...` sont réservées au **navigateur** (fetch côté client, même
+origine) et à l'administration.
+
+**Rendu interactif** (bascule, accordéon, carrousel…) : deux options.
+
+1. **Rendu entièrement client** : mettre `'use client'` en tête de
+   `render.js` et utiliser `useState` / `useEffect`. Le manifeste serveur
+   importe alors le bloc comme référence client, et React franchit la
+   frontière automatiquement. Voir l'exemple `accordion/`.
+
+   > **Branchement requis** : `app/layout.js` doit importer
+   > `./.fraza/blocks.server.js` (à côté de `templates.server.js`) pour que les
+   > `render.js` clients passent par le compilateur RSC et soient référencés
+   > dans le React Client Manifest. Les nouveaux projets l'ont **déjà**. Sur un
+   > projet plus ancien, ajoute la ligne à la main, sinon l'erreur « Could not
+   > find the module … in the React Client Manifest » apparaît.
+2. **Îlot client dans un rendu serveur** : garder `render.js` en server
+   component (rendu serveur du contenu statique) et isoler la partie
+   interactive dans un fichier enfant `*.client.js`, importé par `render.js`.
+   La découverte ignore les fichiers autres que `fields.js`, `template.js` et
+   `render.js`, mais ils sont inclus normalement par l'import.
+
+   ```js
+   // render.js (serveur)
+   import Interactif from './Interactif.client.js';
+   export default function MonRender({ block }) {
+     return <div><h2>{block.title}</h2><Interactif data={block} /></div>;
+   }
+   ```
+
+## Cycle de vie
+
+1. Tu crées un dossier `components/fraza/blocks/mon-bloc/` avec les 3 fichiers.
+2. Tu lances `npx fraza-modules sync`, qui génère :
+   - `app/.fraza/blocks.client.js`, qui appelle `registerBlock({ type: 'custom:mon-bloc', Template: ..., ... })` ;
+   - `app/.fraza/blocks.server.js`, qui appelle `registerCustomBlock({ type: 'custom:mon-bloc', RenderComponent: ... })`.
+3. `app/(admin)/admin/layout.js` rend `<FrazaBlocksClient />` côté client, et `instrumentation.js` importe `blocks.server.js` côté serveur. Le registre de l'éditeur est rempli dans l'administration, celui du rendu au démarrage.
+4. Le bloc apparaît dans le menu `/` de chaque `BlockEditor`.
+5. Sur le site public, les blocs de type `custom:*` sont rendus par le `RenderComponent` correspondant.
+
+## Espace de noms
+
+Tous les blocs personnalisés reçoivent le préfixe `custom:` (`mon-bloc` →
+`custom:mon-bloc`). Il évite toute collision avec les blocs internes
+(`paragraph`, `heading_1`, `image`, etc.), qui n'utilisent jamais `:`.
+
+## Dépannage
+
+Un bloc manque dans le menu `/` ? Vérifier dans l'ordre :
+
+1. `npx fraza-modules sync` a-t-il été lancé ? La commande affiche `◦ block:<id>` pour chaque bloc trouvé.
+2. Le dossier contient-il bien `fields.js` ? Sans lui, le dossier est ignoré sans message.
+3. Le `meta.id` est-il valide ? Seulement `[a-z0-9-]`, et différent d'un bloc interne. Deux dossiers sous le même `meta.id` font échouer le démarrage, avec les deux dossiers nommés dans l'erreur.
+4. Y a-t-il une erreur d'import dans `app/.fraza/blocks.client.js` ? Regarder la console du navigateur.
+5. `app/(admin)/admin/layout.js` rend-il bien `<FrazaBlocksClient />` ? Sans lui, le manifeste n'est pas exécuté dans le navigateur.
+
+## Exemples fournis
+
+- **`callout/`** : encadré avec un message et 4 variantes de couleur. Montre `<TextareaField>` et `<SelectField>`. Rendu **serveur** statique.
+- **`three-cards/`** : rangée de 3 cartes avec image, titre et texte. Montre `<ImageField>` (avec `MediaPicker`) et une structure imbriquée modifiée par `patchCard()`. Rendu **serveur** statique.
+- **`accordion/`** : en-tête cliquable qui révèle un contenu. Montre un **rendu public interactif** (`render.js` marqué `'use client'`, avec `useState`).
+- **`icon-list/`** : liste verticale d'éléments (icône, texte, lien facultatif) avec un titre et une couleur d'icône commune. Montre `<IconField>` et une **liste dynamique** (ajout et retrait d'éléments). L'éditeur propose toutes les icônes de `@fraza/icons` ; le rendu **serveur** affiche l'icône choisie avec `<Icon name>` de `@fraza/core/shared/components/Icon`, qui ne charge qu'elle.
+
+Tu peux les supprimer ou t'en inspirer librement.