# 06 — Feuille de route
**Statut : en cours · Phase : transverse · Mis à jour : 02/11/2026.**
Tailles : **S** = moins d'une journée, **M** = quelques jours, **L** = une semaine ou plus.
```
P0 Fondations ─► P1 Deck ─► P2 Sites www/docs/presentation ─► P3 Story ─► P4 Motion ─► P5 Alpha 0.1 ─► P6 Report ─► P7 Webtoon ─► P8 Book ─► P9 Roadmap ─► P10 Calendar ─► P11 Stories ─► P12 1.0
▲ ▲
emaki V2–V3 (dans le dossier emaki, avant la copie) ────────────────┘
Accepté le 24/10 (plans 10 à 14) : petits lots avancés en P6, P7, P9, P10, P11, puis après la 1.0
P12 ─► P13 Form ─► P14 Directory ─► P15 Atlas ─► P16 Scenario
```
Les neuf formats (deck, motion, docs, report, webtoon, book, roadmap, calendar, stories) font partie
de la vision dès maintenant. On les livre **un par un**, et chacun ouvre son sous-domaine (voir
`07-domaines.md`). Les specs de report, webtoon, book, roadmap, calendar et stories sont dans
`08-formats.md`. Le multilingue et le JSON typé (`09-langues-et-json.md`) arrivent dès P3, pour que
chaque format soit bilingue et disponible en JSON dès sa sortie.
Les idées de `sites/plans/pages/archive/BACKLOG_IDEA.md` sont détaillées dans les plans 10 à 14.
Elles ajouteraient, après la 1.0, jusqu'à quatre formats (`glossary`, `directory` et `atlas`,
retenus ; `form` multi-étapes en option), des blocs transverses et deux sites d'outil. Leur ordre et
leurs options ont été tranchés le 24/10/2026, sans l'utilisateur et à sa demande (décisions
réversibles) : voir la section « Backlog : plans 10 à 14 » après P12 et les « Questions ouvertes ».
L'export PDF de tous les formats qui s'impriment est détaillé dans `15-export-pdf.md` (accepté le
24/10 pour les questions 1 à 6, questions 7 à 9 ouvertes ; phases PDF0 à PDF5, logées dans P6, P7 et
P8, puis PDF4 en option après P8 et PDF5, les autres formats, dans leur propre phase).
**État** : `journal.md` §2 fait foi. Les cases de P0 à P4-V1 ont été cochées le 24/10 après
vérification dans le dépôt ; une case restée vide n'est pas faite ou n'a pas pu être vérifiée
(réservations, Vercel, DNS, commits de l'utilisateur).
## P0 — Fondations et nettoyage du fork (S/M)
Les règles viennent de `presentation-engine/FORK.md`. Elles sont fixées dans `NOTICE.md` et
`UPSTREAM.md` (racine, déjà rédigés).
### P0.1 Avant tout
- [x] Sauver les générateurs de logo du scratchpad dans `brand/tools/` (voir `01-assets.md`, section
2.3). **Ce dossier est temporaire.**
- [x] presentation-engine n'est pas modifié : on copie ses fichiers ici. Sa référence est le commit
`4b86797`, et les fichiers de marque non commités deviennent versionnés dans `brand/`. emaki
n'a plus de `.git` : sa référence est le commit `1b86ccd` (`0.1.0-beta.7`).
- [ ] Réserver :
- le domaine `recit.dev` ;
- l'organisation GitHub `recit-dev` ;
- sur npm : `recit`, `create-recit`, le scope `@recit` (`core`, `data`, `time`, `paged`, `report`,
`toon`, `book`, `roadmap`, `calendar`, `stories`, `docs`, puis `form`, `directory`, `geo`,
`atlas`, `scenario` et `pixel` des plans 10 à 14), la liste de `03-packaging.md` §6.
### P0.2 Attribution et upstream
- [x] `git remote add upstream (dépôt d'origine)`, `git config remote.upstream.tagOpt --no-tags`,
puis `git fetch upstream`. Les tags upstream vont dans `refs/upstream-tags/*` (`UPSTREAM.md`),
jamais dans `refs/tags`.
- [x] Supprimer les 3 version plans du framework de sites restés dans `.nx/version-plans/`. Sinon,
la première release Récit les consomme (fait le 24/10).
- [x] `LICENSE.md` : ajouter uniquement la ligne
`Modifications Copyright (c) 2026 vguerand (https://github.com/vguerand/recit)`.
- [x] Relire `NOTICE.md` et `UPSTREAM.md`, et compléter la ligne du journal de synchronisation.
- [ ] Commit `chore: add NOTICE and UPSTREAM`.
### P0.3 Nettoyage (un commit par ligne, chacun doit garder `pnpm check` et les tests du cœur au vert)
| Étape | Action | Vérification |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 1 | `packages/site/package.json` : `"private": true` (patch n° 1) | `pnpm -F recit-site build` |
| 2 | Supprimer `packages/{create-site,plugin-graphql,plugin-search-algolia}` et le plugin de monétisation | `pnpm install`, `nx run-many -t build` |
| 3 | Supprimer tous les `examples/*` sauf `with-config`, ainsi que `e2e/cosmo-cargo.spec.ts` | `pnpm -F site test` (le test `config.test.ts` utilise encore `with-config`) |
| 4 | `git mv docs sites/docs` : la doc du framework de sites devient la base de docs.recit.dev (config, `vercel.json`, `lychee.toml`, historique). Patch n° 2 (`copy:docs` retiré de `build.dependsOn`) | `nx run site:build`, `nx run docs:build` |
| 5 | Supprimer `.github/workflows/{main.yaml,preview-build.yaml,release-monetization.yaml,release.js}`. Réécrire `build.yaml` (check, build, test, sans canary) | CI verte sur une PR |
| 6 | `nx.json` : `release.projects` = liste explicite des packages publiés (audit ST-10, 25/10 ; P5 ne fait que publier). `package.json` racine : `name: "recit-monorepo"`, suppression de `release:pre` / `release:minor` | `pnpm check` |
| 7 | `pnpm-workspace.yaml` : globs de `03-packaging.md` §1 (retirer `scripts`, `website`, `docs`, `examples/**`) | `pnpm install` |
| 8 | `playwright.config.ts` : retirer le serveur `cosmo-cargo` (les e2e Récit arrivent en P1) | `pnpm test:e2e` (vide) |
| 9 | `scripts/check-admonitions.mjs` : globs `sites/**/pages/**` | `pnpm check:other` |
| 10 | `assets/github-hero.png`, `CHANGELOG.md` (Le framework de sites) et `.cursorrules` supprimés. Le `CHANGELOG.md` racine renaît à la première release Récit, écrit par `nx release` | — |
| 11 | `README.md` réécrit (Récit, section « Fork of the site framework » avec la mention obligatoire de `NOTICE.md`) | — |
Après le nettoyage, `git ls-files | cut -d/ -f1-2 | sort -u` ne doit plus montrer que des chemins
classés dans `03-packaging.md` §3 et dans `NOTICE.md`.
**Sortie :**
- le dépôt ne contient plus que le cœur `@recit/site`, sa fixture et l'outillage ;
- `pnpm install && pnpm check && nx run-many -t build test` passent ;
- `NOTICE.md` et `UPSTREAM.md` sont à jour, les noms sont réservés et les sources taguées.
## P1 — Import du format deck et découpage en groupes (M)
Détail dans `04-migration.md`. Renommage complet dans `03-packaging.md` §7.
- [x] Créer les groupes `packages/formats/`, `packages/integrations/`, `packages/tools/`, avec les
tags nx. Faits le 26/10 : la liste des neuf tags et le sens des arêtes sont dans
`03-packaging.md` §8, posés dans chaque `package.json` et vérifiés par
`scripts/check-package-boundaries.js` dans `pnpm check` (audit ST-6).
- [x] `packages/core`, `packages/theme`, `packages/components`, `packages/formats/deck`,
`packages/cli`, `packages/recit`, `packages/integrations/site-stories`. Un commit par package
: import, renommage, outillage.
- [ ] Squelette de **tous** les autres packages de `03-packaging.md` §6 (`package.json` privé tant
qu'il est vide, `src/index.ts`, tags nx). Le code arrive à la phase de chaque package.
- [x] Passage à nx, biome, tsdown et TS 6. Exclure `**/*.mdx` d'oxfmt.
- [x] Adapter `@recit/site-stories` au framework de sites 0.93.
- [x] `examples/deck-*`, `examples/site-embed`, `e2e/deck-*.spec.ts`, `playwright.config.ts` sur
`examples/deck-showcase`.
- [ ] `grep -rniE "presentation|emaki" packages examples` vide, hors alias documentés.
- [x] `AGENTS.md` : section « Récit » qui renvoie vers `context.md`, `sites/plans/pages/`,
`NOTICE.md` et `UPSTREAM.md`. Les conventions de code existantes restent.
**Sortie :** 88 tests unitaires et 7 e2e au vert. `recit dev`, `recit build` et
`recit export --to pdf` fonctionnent sur `examples/deck-showcase`. La règle de dépendances entre
groupes est vérifiée.
## P2 — Sites : recit.dev, docs.recit.dev, presentation.recit.dev (M)
Détail dans `07-domaines.md`.
- [x] `packages/tools/site-kit` : en-tête inter-sites, pied (mention `NOTICE.md`), logos Q07,
`createSiteConfig()`, table `SITES`.
- [x] `sites/docs` (ex-`docs/` du framework de sites) : remplacer les pages du framework de sites
par la documentation et le theme de `presentation-engine/docs`, plus l'onglet **Formats**.
Filtres dans la sidebar.
- [x] `sites/components` (components.recit.dev) : chaque composant de `@recit/components`, rendu
dans chaque format, avec ses props et sa syntaxe Markdown.
- [x] `sites/presentation` : hero en deck, galerie (`examples/deck-*`), démos de
`presentation-engine/docs/pages/demos`.
- [x] `sites/www` : promesse, même source côte à côte en deck et en doc (la vidéo arrive en P4),
cartes des neuf formats, avec leur statut (report P6, webtoon P7, book P8, roadmap P9,
calendar P10, stories P11).
- [ ] Logo et favicon depuis `brand/` (Q07, couleur à figer avant la mise en ligne).
- [ ] Projets Vercel, DNS, redirections `www`, `deck` et `slides`. Prévisualisations par PR via
`nx affected`.
- [ ] Open Graph par site (`og-card` décliné avec l'icône du format).
- [x] Corriger le défaut connu : `title` des blocs de code affiché « Code » (patch prévu dans
`UPSTREAM.md`).
**Sortie :**
- recit.dev, docs.recit.dev et presentation.recit.dev sont en ligne, les alias redirigent ;
- la recherche Pagefind renvoie les sous-résultats par slide ;
- tous les exemples sont jouables ;
- aucun lien inter-sites n'est écrit en dur.
## P3 — Généraliser en `Story`, JSON typé et langues (L)
Détail dans `02-architecture.md`.
- [x] Types `Story` et `Scene` (`id`, `source`, `attrs`, `mdast`). `compileStory`, avec
`compileDeck` en alias.
- [x] Attribut `format:` dans le frontmatter. `deck` par défaut.
- [x] Alias de directive de scène ``, fusionné avec les attributs du
séparateur.
- [x] `recit.config.ts` validé par zod 4. **Fichier unique** : options du framework de sites,
sections Récit et `i18n` optionnelle, injection automatique des plugins, patch n° 3 du
chargeur (`02-architecture.md` §5).
- [x] `StoryEmbed` et `StoryGallery`, anciens noms exportés en alias.
- [x] Tâches L1 à L5 de `09-langues-et-json.md` :
- schémas zod et JSON Schema (`@recit/core/schema`) ;
- `markdownToSource` et `sourceToMarkdown` ;
- compagnons `example.json` et `example.fr.json` ;
- variantes `example.fr.md` et chaîne de repli ;
- `@recit/core/i18n` (migration de `UI_STRINGS`) ;
- CLI `convert`, `validate` et `i18n` ;
- routes par langue, `hreflang` et sélecteur de langue sur les sites.
**Sortie :** aucun changement visible pour les decks existants (mêmes tests, même rendu).
`examples/deck-showcase` existe en `.md`, `.json` et `.fr.md`, avec une compilation identique en
`md` et en `json`, et `recit i18n check` passe. `Story` est documenté dans
`sites/docs/pages/documentation/reference/architecture.mdx`.
## P4 — Format vidéo et motion.recit.dev (L)
Détail dans `05-video.md` (phases V1 à V7) et dans `07-domaines.md` (§3 : un seul site `motion`,
`video` en simple redirection).
- [x] Groupe `packages/formats/motion*` et `packages/mcp`, copiés depuis emaki (V1).
- [ ] `sites/motion` et redirection `video.recit.dev` → `motion.recit.dev/video`.
- [ ] `sites/www` : ajouter la vidéo dans la démo « une source, trois rendus ».
**Sortie :** motion.recit.dev est en ligne. `recit render examples/motion-hello/story.md` produit un
MP4 identique aux goldens. Le même fichier se joue sur les sites via
``, et le MCP accepte le Markdown.
## P5 — Alpha publique (S/M)
- [ ] `0.1.0-alpha.0` pour tous les packages publiés de `03-packaging.md` §6 (`release.projects` de
`nx.json` les liste un par un depuis le 25/10 ; ajouter `create-recit` quand il devient
public).
- [x] Workflow `release.yaml` Récit (celui du framework de sites a été supprimé en P0) : manuel,
`build.yaml` rejoué, dry run, environnement `npm` à relecteur (audit lot 1, 25/10).
- [ ] `publint` et `size-limit` au vert.
- [ ] `packages/create-recit` (modèle : `create-site`, consulté dans l'historique git ou upstream
puisqu'il est supprimé en P0) : `npm create recit` avec les gabarits `deck`, `motion` et
`docs`.
- [ ] Un **changelog unique** (`CHANGELOG.md` racine), via les version plans de `nx release` : tous
les packages partagent une version.
- [ ] `@emaki/*` : `npm deprecate` vers `@recit/motion`, par l'auteur d'emaki.
- [ ] **Aucune publication npm sans validation explicite.**
- [ ] `@recit/app` et `recit app build` : un site Récit en application desktop, en `prerelease`
(`18-mobile-desktop.md`, lots APP0 à APP6) ; le mobile (APP7, APP8) après la 1.0 sauf demande.
## P6 — Report : report.recit.dev (L)
Spec et tâches R1 à R6 dans `08-formats.md` §1. Nouveaux packages : `@recit/data`, `@recit/paged`,
`@recit/report` ; lot : `@recit/geo`.
- Question 10 tranchée (24/10) : graphiques sur d3 sans DOM (`d3-scale`, `d3-shape`), base partagée
avec les cartes (`13-cartes.md` D9). `03-packaging.md` §6 et `08-formats.md` §0 et R1 sont mis à
jour.
- [ ] Accepté (plan 13, 24/10) : lot avancé « bloc `::map` statique » (GE1 à GE8), sans source
`data=` (le tableau accessible est le `DataTable` de `@recit/data`).
- [ ] Accepté (plan 15, 24/10) : PDF0 au début de P6 (options du deck typées dans `@recit/core`,
`ExportManifestSchema` et `exports.json`, goldens du PDF actuel lus avec `pdfjs-dist`), puis
PDF1 (déplacement du stub `packages/formats/paged` vers `packages/tools/paged` avec une
description « Node print chain used by the CLI », PDF1.0 ; chaîne dans `@recit/paged/runner`,
contrat `@recit/core/print`, PDF du report par Chromium avec une table des matières en liens,
sans numéros).
**Sortie :**
- `recit build` et `recit export --to pdf` fonctionnent sur `examples/report-quarterly` ;
- chaque chiffre du rapport est calculé (`:value`), et un champ inconnu produit une erreur avec
numéro de ligne ;
- l'export PDF du deck passe par `@recit/paged` sans régression ;
- accepté (plan 15) : le PDF du deck et celui de `examples/report-quarterly` sont balisés, ont des
signets, sont vérifiés en e2e et listés dans `exports.json` ;
- report.recit.dev est en ligne, et la version `0.2.0-alpha` est publiée.
## P7 — Webtoon : webtoon.recit.dev (L)
Spec et tâches W1 à W5 dans `08-formats.md` §2. Nouveau package : `@recit/toon`.
- [ ] Accepté (plan 14, 24/10) : lot avancé IA0 (guide MCP du scénariste, pages docs.recit.dev/ai,
`examples/scenario-lorem` en Markdown simple), sans package nouveau.
- [ ] Accepté (plan 15, 24/10) : PDF2, PDF du webtoon en pages de hauteur fixe coupées entre les
cases (une case trop haute sur sa propre page, avec un avertissement), `ToonPdfOptionsSchema`,
spike mesuré de `pagination: continuous`.
**Sortie :**
- `examples/toon-episode` se lit au scroll, en deux langues ;
- l'export en tranches respecte les préréglages des plateformes ;
- `recit render --as motion` produit une vidéo `9:16` ;
- accepté (plan 15) : `examples/toon-episode` produit un PDF par langue, sans case coupée, sous son
budget de poids, listé dans `exports.json` ;
- webtoon.recit.dev est en ligne (`toon.recit.dev` redirige), et la version `0.3.0-alpha` est
publiée.
## P8 — Book : book.recit.dev (L)
Spec et tâches B1 à B5 dans `08-formats.md` §3. Nouveau package : `@recit/book`.
- [ ] Accepté (plan 15, 24/10) : PDF3, spike go/no-go Paged.js (PDF3.0), puis moteur `pagedjs`
derrière `PrintEngine`, réglages du livre à plat (`trim` → `pdf.page.size`), table des
matières numérotée (aussi en option pour le report), notes, titres courants.
- [ ] Accepté (plan 15, 24/10), optionnel, **après P8** : PDF4, PDF des pages et sections de doc
(`recit export --to pdf --site`, bouton piloté par `exports.json`), après le spike PDF4.0. Ce
n'est pas un critère de sortie de P8.
**Sortie :**
- `examples/book-novella` produit un PDF imprimable, un EPUB valide (`epubcheck`) et une édition web
;
- accepté (plan 15) : ce PDF est balisé, a des signets, des numéros de table des matières vérifiés,
un fichier par langue, et il est listé dans `exports.json` ;
- book.recit.dev est en ligne, et la version `0.4.0-alpha` est publiée.
## P9 — Roadmap : roadmap.recit.dev (M/L)
Spec et tâches RM1 à RM5 dans `08-formats.md` §4. Nouveaux packages : `@recit/time`,
`@recit/roadmap` ; lot : `@recit/directory`.
- [ ] Accepté (plan 12, 24/10) : lot avancé DI0 (schémas, analyseur `{k=v}` créé avant RM1 et
réutilisé par la roadmap, liste « awesome » lue en annuaire, vue A–Z minimale).
**Sortie :**
- `examples/roadmap-product` s'affiche dans les trois vues, en en et en fr ;
- les exports ICS, RSS et PDF sont valides ;
- **la roadmap de Récit est publiée sur roadmap.recit.dev depuis ce plan** ;
- la version `0.5.0-alpha` est publiée.
## P10 — Calendar : calendar.recit.dev (M/L)
Spec et tâches CA1 à CA5 dans `08-formats.md` §5. Nouveau package : `@recit/calendar` ; lot :
`@recit/form`.
- [ ] Accepté (plan 12, 24/10) : le type `Place` unique, livré avec `calendar`.
- [ ] Accepté (plan 10, 24/10) : lot avancé FO0 et FO1 (contrat d'API des formulaires, bloc
`:::form` minimal en mode `native` et `mock`).
**Sortie :**
- `examples/calendar-meetups` (JSON multilingue) s'affiche dans les quatre vues ;
- le flux ICS est abonnable, et les récurrences sont correctes aux changements d'heure ;
- les jalons de la roadmap remontent dans le calendrier ;
- la version `0.6.0-alpha` est publiée.
## P11 — Stories : story.recit.dev (M)
Spec et tâches ST1 à ST4 dans `08-formats.md` §6. Nouveau package : `@recit/stories`.
- [ ] Accepté (plan 11, 24/10) : lot avancé IM1 et IM2 (bloc de code ` ```pixel `, `textcard` en
plan motion `9:16` puis en carte stories).
**Sortie :**
- `examples/stories-launch` se lit au tap, au clavier et au swipe ;
- l'export d'images et le pont vers motion (MP4 vertical) fonctionnent ;
- la version `0.7.0-alpha` est publiée.
## P12 — 1.0 (M)
- [ ] Stabiliser l'API publique de `Story`, `recit.config.ts`, la CLI et `@recit/site-stories`. Les
alias dépréciés (`compileDeck`, `presentation.config.ts`, `PresentationEmbed`…) sont retirés.
- [ ] Les ponts entre formats de `08-formats.md` §0 sont documentés et testés.
- [ ] Les neuf formats de la 1.0 ont leur page sur docs.recit.dev, leur site, au moins deux exemples
(dont un bilingue) et un JSON Schema publié (`recit.dev/schema/v1`).
- [ ] Le schéma JSON `v1` est figé, et `recit migrate` est prêt pour une future `v2`. Un nouveau
format ou un nouveau `kind` ajouté après la 1.0 reste un ajout compatible en `v1` (règle B1
ci-dessous).
- [ ] `play.recit.dev` (studio en ligne), si `@recit/studio` est prêt.
## Backlog : plans 10 à 14 (ordre accepté le 24/10/2026)
Les cinq idées de `sites/plans/pages/archive/BACKLOG_IDEA.md` ont chacune leur plan. Cette section
fixe **un seul ordre** et les règles qu'ils partagent. Les questions 14 à 27 ont été tranchées le
24/10/2026, sans l'utilisateur et à sa demande (« réponds tout seul »), sauf celles qui lui restent
(« Questions ouvertes », « À l'utilisateur »). Toutes ces décisions sont réversibles.
| Idée du backlog | Plan | Nature | Plus petite tranche (lot avancé) | Lot avancé | Phase complète |
| ------------------------------ | -------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------- | -------------------------------------------- |
| form.recit.dev | `10-formulaires.md` | bloc `:::form` et contrat d'API (fondation `@recit/form`) ; format multi-étapes en option | FO0 (contrat, « TODO API ») et FO1 (bloc minimal, `native` et `mock`) | P10 | P13 Form |
| motion : Pixel Image, « Text » | `11-images.md` | blocs `pixel` et `textcard`, pas de format (tranché) | IM1 (` ```pixel `) et IM2 (`textcard` en plan motion `9:16`, puis carte stories) | P11 | aucune ; personnage en P16 une fois débloqué |
| glossaire / annuaire | `12-glossaire-annuaire.md` | formats `glossary` et `directory` (un package), `:term` | DI0 (schémas, `{k=v}`, liste « awesome », A–Z minimale) | P9 | P14 Directory |
| cartes | `13-cartes.md` | bloc `::map` (fondation `@recit/geo`) ; format `atlas` retenu (P15) | `::map` statique (régions, marqueurs), sans source `data=` | P6 | P15 Atlas |
| ai / scenario | `14-ia-scenario.md` | outillage, documentation et site d'outil, pas de format | IA0 (guide MCP, docs, `examples/scenario-lorem` sans package) | P7 | P16 Scenario |
Ordre : **P4 et P5 ne reçoivent rien** (l'import de motion est en cours, l'alpha passe d'abord).
Après P5, seuls les lots avancés ci-dessus s'ajoutent, un par phase, comme petites tâches. Les
formats, packages et sites complets viennent après la 1.0, en P13 à P16. Avec toutes les options, le
backlog ajouterait quatre formats, quatre sites et cinq packages : à peu près autant que P6 à P11.
Le format `atlas` est retenu (P15). Les options restent hors des lots avancés : format `form`
multi-étapes, `worldview`, MapLibre, Turnstile et Fountain (import et export) plus tard, chacune en
option.
### Règles communes
| # | Règle | À reporter dans |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| B1 | **Versionnement** : un nouveau format ou un nouveau `kind` est un ajout compatible en `v1`. L'union reste ouverte en lecture : un lecteur `v1` qui rencontre un format ou un `kind` inconnu renvoie une erreur claire (« installez @recit/… »), pas une erreur de schéma. Seule une rupture donne une `v2` | `09` §2.1 (après P3) |
| B2 | **Blocs transverses en JSON** : en `v1`, `:::form`, ` ```pixel `, `:::textcard`, `::map` restent des **directives dans le `body`** de la scène. `SceneSource` ne gagne pas de champ `blocks`. Les schémas `FormBlock`, `PixelBlock`, `TextCardBlock`, `MapBlock` valident les directives | `09` §2.2 (après P3) |
| B3 | **Un seul `Place`**, porté par le plan 12 (adresse structurée, `geo` facultatif, `address` libre pour l'affichage seulement), livré avec `calendar` (P10). `location` accepte une chaîne libre, un `@id` d'annuaire ou un `Place` inline, avec une seule résolution | `08` §5, `09` §2.3 (à P10) |
| B4 | **Registre des directives et des attributs de scène** : le cœur ne garde que les noms. Le plugin de chaque bloc vit dans la fondation qui le porte (`@recit/form`, `@recit/geo`, `@recit/scenario`) ; ceux qui servent à tous les formats sans fondation dédiée, `:term` (plan 12) et ` ```pixel ` (plan 11), vivent dans `@recit/components`, jamais dans le cœur. Attributs réservés : `type=` (blocs motion), `entry=` (bible), `end` (écran de fin), `prompt=` (image d'une scène de scénario), `cast=`, `beat=`, `set=`, `shot=`, `pose=`, `expression=` (scénario, `14-ia-scenario.md` IA2.3), `camera=` (emprise d'atlas), `background` (un seul nom, jamais `bg`) | `02` §3, `03` §8 |
| B5 | **Domaines** : le domaine principal porte le nom anglais. Les mots du backlog (`glossaire`, `annuaire`, `cartes`, `scenario`) et le nom technique deviennent des alias 301. Nouvelle catégorie « site d'outil » (form tant qu'il n'y a pas de format, ai), à côté de www, docs et components | `07` §1 et §2 (fait) |
| B6 | **Ports locaux** : components 3010, form 3011, directory 3012, maps 3013, ai 3014 | `07` §4 (fait), `SITES` |
| B7 | **Exemples** : `examples/-*`, ou `examples/-*` pour un bloc ou un outil sans format (`form-*`, `map-*`, `scenario-*`). lebrocoli.fr n'a qu'**un** dossier, `examples/scenario-lebrocoli` (plan 14), avec des sections optionnelles des plans 10 à 13, un seul jeu de lignes NOTICE et une seule exception à la règle Lorem | `03` §1 |
| B8 | **Doc** : tous les blocs transverses sous `docs.recit.dev/components/` (form, pixel, textcard, map, term). Le contrat des formulaires sous la section API | `07` §2 |
| B9 | **Une commande par besoin** : `recit validate --strict` (contrôles de scénario inclus, pas de `recit check` ni de `scenario check`), `recit skills export` (seul générateur de skills, tous les guides `recit://guide/*`), `recit form check-endpoint` (plan 10, test d'une API de formulaire), `recit validate --links` (plan 12, une option plutôt qu'un verbe), `recit prompts build` et `recit assets register` (plan 14), Fountain par `recit convert` (pas de `export fountain`), `recit geocode` (plan 12, écrit dans le compagnon JSON ; pas en v1, où les coordonnées sont écrites par l'auteur). Liste complète, par phase : ligne `@recit/cli` de `03` §6 | `03` §6 (`@recit/cli`) |
| B10 | **Identifiants** : préfixe + numéro, comme R1 ou ST1 dans `08`. Un plan découpé en lots écrit ses sous-tâches `lot.n` (FO2.3). Statut d'un package : un `Pn` seulement | — |
| B11 | **Un package peut déclarer plusieurs formats** s'ils partagent leur modèle (`@recit/directory` : `glossary` et `directory`) | `03` §1 |
## P13 — Form : bloc `:::form`, contrat d'API et form.recit.dev (M)
Spec et tâches FO0 à FO7 dans `10-formulaires.md`. Nouveau package : `@recit/form` (fondation, créé
au lot avancé de P10).
- [ ] Lot avancé, en P10 : FO0 (contrat « Récit Form Submission API v1 », checklist « TODO API »),
FO1 (bloc `:::form` minimal, `native` et `mock`, honeypot, consentement, accessibilité).
- [ ] FO2 : envoi `fetch` en urlencoded par défaut (sans preflight), JSON en opt-in, erreurs
problem+json, idempotence.
- [ ] FO3 : handler de référence `@recit/form/server`, `examples/form-api-node` et
`recit form check-endpoint` (question 15 tranchée : aucun service hébergé par Récit).
- [ ] FO7 : `sites/form` (site d'outil, port 3011), `examples/form-contact`
(`examples/form-api-node` vient de FO3).
- [ ] Plus tard : génération depuis OpenAPI (FO4), format multi-étapes (FO5, sur un besoin réel),
rendus dans les autres formats (FO6).
**Sortie :**
- un `:::form` dans une page `docs` envoie ses réponses à une API externe sans preflight, et affiche
les erreurs par champ en en et en fr ;
- le contrat est publié en OpenAPI et rendu sur docs.recit.dev ;
- form.recit.dev est en ligne en mode `mock`, et aucune donnée n'en part.
## P14 — Directory : glossaire et annuaire, directory.recit.dev (M/L)
Spec et tâches DI0 à DI7 dans `12-glossaire-annuaire.md`. Nouveau package : `@recit/directory` (deux
formats, créé au lot avancé de P9).
- [ ] Lot avancé, en P9 : DI0 (schémas, `{k=v}`, liste « awesome » en `entries: links`, A–Z
minimale).
- [ ] En P10 : `Place` livré avec `calendar`.
- [ ] DI1 (`:term` explicite ; lien automatique désactivé par défaut, mode `first` en option
ensuite), DI2 (glossaire de Récit), DI3, DI4, DI5, DI7 (`sites/directory`, port 3012).
- [ ] Plus tard : DI6 (`validate --links`, import CSV ; `geocode` après la v1 ; pas d'import
MkDocs), JSON-LD.
**Sortie :**
- `examples/glossary-lorem`, `examples/directory-links` et `examples/directory-places` s'affichent
en en et en fr ;
- docs.recit.dev définit `Story` et `stories` à un seul endroit ;
- directory.recit.dev est en ligne.
## P15 — Atlas : cartes et maps.recit.dev (L)
Spec et tâches GE1 à GE14 et AT1 à AT5 dans `13-cartes.md`. Nouveaux packages : `@recit/geo`
(fondation, créé au lot avancé de P6), `@recit/atlas` (retenu, P15).
- [ ] Lot avancé, en P6 : bloc `::map` statique (GE1 à GE8), sans `worldview` ni choroplèthe.
- [ ] GE9 à GE11 : choroplèthe sur `@recit/data`, tracés et zones, cartes en motion et en stories.
- [ ] AT1 à AT5 : format `atlas` et ponts (retenu, question 26).
- [ ] `sites/maps` (port 3013).
- [ ] Options, plus tard : `worldview` (Natural Earth par défaut), MapLibre, gazetteer. Natural
Earth est la seule source de fond en v1.
**Sortie :**
- une choroplèthe se calcule depuis les données, et la même carte se rend en web, PDF, MP4 et story
sans requête réseau ;
- maps.recit.dev est en ligne.
## P16 — Scenario : bible, MCP et ai.recit.dev (L)
Spec et tâches IA0 à IA5 dans `14-ia-scenario.md`. Nouveau package : `@recit/scenario` (fondation),
seulement si l'exemple du lot avancé en montre le besoin.
- [ ] Lot avancé, en P7 : IA0 (guide MCP du scénariste, pages docs.recit.dev/ai et /scenario,
`examples/scenario-lorem` en Markdown simple).
- [ ] IA1 à IA3 : schéma de la bible limité aux champs relevés, `@recit/scenario`, outils MCP,
`recit skills export`.
- [ ] IA4 : `sites/ai` (site d'outil, port 3014, alias `scenario.recit.dev`).
- [ ] IA5 : `examples/scenario-lebrocoli`, après accord (question 19 : licence de l'image de Broc),
avec le kit de Broc (`14` D12) et son sprite (`11` D9, IM4).
- [ ] Plus tard : `:::dialogue` et ponts, registre des assets, Fountain (import et export
seulement), prompts MCP, Elicitation.
**Sortie :**
- `examples/scenario-lorem` passe `recit validate --strict` et se rend en stories et en motion, en
en et en fr, avec les mêmes images ;
- ai.recit.dev est en ligne, sans aucune doc propre.
## Risques transverses
| Risque | Parade |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| L'API des plugins du framework de sites change (0.86 → 0.93 → …) | `examples/site-embed` et e2e en CI. `@recit/site-stories` déclare une plage `@recit/site` testée |
| Confusion de marque avec le framework de sites d'origine | marque Q07, sites `*.recit.dev` |
| Neuf formats, c'est beaucoup de périmètre | un format à la fois (P6, puis P7, puis P8), chacun avec son critère de sortie. Le socle commun (`Story`, `@recit/paged`, `@recit/data`) limite le code propre à chaque format |
| Le backlog (plans 10 à 14) retarde l'alpha ou la 1.0 | rien en P4 ni en P5, un seul petit lot par phase de P6 à P11, formats et sites complets après la 1.0 (P13 à P16), options lancées seulement sur réponse explicite |
| Bundle client lourd (Shiki, Mermaid, motion) | entrée `browser` sans Shiki, Mermaid à la demande, `size-limit` |
| Couleur non arrêtée au moment du lancement | marque Q07 choisie. P0 et P1 ne dépendent pas de la couleur, seule la mise en ligne de P2 l'attend |
| Supprimer des packages du framework de sites casse le cœur | une suppression par commit avec vérification (P0.3). `examples/with-config` est gardé pour les tests du cœur |
| Sous-domaines qui dupliquent la doc | règle : aucune doc hors de docs.recit.dev, liens via la table `SITES` (`07-domaines.md`) |
## Décisions prises
Les décisions sont tenues dans le [registre des décisions](/decisions), une ligne par décision.
## Questions ouvertes
1. **Couleur** exacte de la teinte unique de Q07 (itérations en cours).
2. Organisation GitHub : rester sur `vguerand/recit`, ou transférer vers `recit-dev/recit` dès P0 ?
3. Directive de scène : confirmer les attributs du séparateur comme forme canonique, avec le
commentaire HTML en alias.
4. ~~`@recit/deck` et son runtime : un seul package avec un sous-chemin (proposé), ou deux packages
?~~ Tranché par le code (P1) : un seul package, sous-chemins `@recit/deck/runtime` et
`@recit/deck/page-data`.
5. Remotion : la licence est-elle compatible avec l'usage prévu (projet personnel ou société) ?
6. Faut-il publier un jour une distribution du framework de sites renommée, ou rester un plugin ?
7. ~~emaki : accord de l'auteur ?~~ Tranché : accord donné, import par copie.
8. ~~Arborescence : `packages/*` à plat avec des sous-groupes (`03-packaging.md`), ou tout sous
`recit/` (zéro collision avec upstream) ?~~ Tranché par le code (P1) : `packages/*` à plat avec
les sous-groupes `formats`, `integrations` et `tools`.
9. ~~`docs/` ?~~ Tranché : gardé, déplacé dans `sites/docs`, et devient la doc de Récit.
10. ~~Graphiques : Observable Plot (proposé) ou Vega-Lite (`08-formats.md` §0) ? `13-cartes.md` (D9,
§2.7) propose une troisième voie : d3 sans DOM, que les cartes partageraient.~~ Tranché (24/10)
: d3 sans DOM (`d3-scale`, `d3-shape`, déjà requis par les cartes), plutôt qu'Observable Plot.
`03-packaging.md` §6 et `08-formats.md` §0 et R1 sont mis à jour.
11. **story.recit.dev** : interprété comme des _stories web_ (cartes plein écran à la Instagram).
S'il s'agissait plutôt de _user stories_ (backlog produit, lié à la roadmap), le format change
complètement (`08-formats.md` §6).
12. Langues des sites au lancement : `en` et `fr` (proposé). Le multilingue est optionnel, et toutes
les langues du monde peuvent être ajoutées ensuite dans `recit.config.ts` (`i18n.locales`). La
doc (docs.recit.dev) reste en anglais.
13. ~~Routage des langues : `prefix-except-default` (proposé, `/fr/…`, l'anglais sans préfixe) ou
`prefix-always` ?~~ Tranché par le code (P3) : `prefix-except-default` par défaut
(`packages/core/src/i18n/locales.ts`), `prefix-always` en option (`i18n.routing`).
### Backlog (plans 10 à 15)
Questions communes, posées une seule fois ici. Les questions propres à chaque idée restent dans son
plan (§8). Celles qui suivent ont été tranchées le 24/10/2026 sans l'utilisateur, à sa demande («
réponds tout seul ») : toutes sont réversibles. Celles qui ne peuvent être tranchées que par lui
sont regroupées sous « À l'utilisateur ».
**Ordre et périmètre**
14. ~~**Ordre** : rien en P4 ni en P5, un lot avancé par phase (P6 cartes, P7 scénario, P9 annuaire,
P10 formulaires, P11 images), puis P13 Form, P14 Directory, P15 Atlas, P16 Scenario après la 1.0
: d'accord ? Le format multi-étapes des formulaires (`10` §3.2) est-il voulu ?~~ Tranché (24/10)
: ordre accepté, sans changement de P13 à P16. Formulaires : bloc `:::form` d'abord, le format
multi-étapes plus tard.
15. ~~**« Créer un TODO afin de mettre en place une API »** : la checklist et un handler de
référence suffisent-ils, ou faut-il un service hébergé par Récit ?~~ Tranché (24/10) : checklist
et handler de référence, pas de service hébergé par Récit.
**Le brocoli et les images (motion, ai/scenario)**
16. → « À l'utilisateur ».
17. → « À l'utilisateur ».
18. → « À l'utilisateur ».
19. → « À l'utilisateur ».
20. ~~**« Format Text »** (`11-images.md` D1) : un nouveau format fait de cartes de texte seules, ou
une carte de texte (`textcard`) dans `motion` et `stories` ?~~ Tranché (24/10) : `textcard` est
un bloc de `motion` et `stories`, pas un nouveau format ; le nom `textcard` est retenu.
21. ~~**Mention IA** (AI Act, article 50) : dans les crédits, sur chaque image, ou nulle part ?~~
Tranché (24/10) : mention « généré par IA » dans les métadonnées et dans l'attribution visible
des images. La génération d'images reste toujours hors de Récit (les prompts sont des données).
La relecture juridique demandée n'est pas tranchée.
**Domaines**
22. ~~**Noms** : domaines principaux en anglais avec les mots du backlog en alias 301 ? Les sites
d'outil (form, ai) sont-ils acceptés ?~~ Tranché (24/10) : domaines principaux en anglais
(`form`, `directory`, `maps`, `ai`), mots français du backlog en alias 301 ; sites d'outil
acceptés.
23. → « À l'utilisateur ».
**Choix techniques transverses**
24. ~~**Blocs en JSON** (règle B2) : directives dans le `body` en `v1`, ou champ typé `blocks?` dès
P3 ?~~ Tranché (24/10) : directives dans le `body` en `v1`.
25. ~~**Lien automatique des termes** (`12` D4) : défaut `none` en v1, puis `first` en option ?~~
Tranché (24/10) : désactivé par défaut en v1, mode `first` en option ensuite.
26. ~~**Format `atlas`** et **carte interactive** (MapLibre) ? « Sous différents pays » : régions
d'un pays, frontières disputées (`worldview`), ou les deux ?~~ Tranché (24/10) : bloc `::map`
d'abord (lot P6), format `atlas` retenu (P15) ; MapLibre plus tard et en option ; « différents
pays » = les régions d'un pays, plus l'option `worldview` (Natural Earth par défaut) ; Natural
Earth seule source en v1.
27. ~~**Géocodage** : une commande `recit geocode`, ou seulement des coordonnées écrites par
l'auteur ?~~ Tranché (24/10) : coordonnées écrites par l'auteur, pas de commande de géocodage en
v1.
**Export PDF (plan 15)** : les questions 1 à 6 de `15-export-pdf.md` §8 sont tranchées le 24/10
(webtoon en pages coupées entre les cases, sans CBZ ; table des matières du report sans numéros en
P6, numérotée en P8 ; runner dans `@recit/paged/runner` ; réglages à plat ; pas de PDF pour
`stories`, PDF des docs optionnel après P8 ; PDF balisé par défaut, `alt` manquant = avertissement).
Les questions 7 à 9 restent dans le plan.
#### À l'utilisateur
16. ~~**« Pet »** (« personna généré via Pet ») : le skill `hatch-pet` d'OpenAI (`openai/skills`,
Apache-2.0), le `/buddy` de Claude Code, ou un outil à toi (Base for Music) ? Si c'est un outil
à toi : où, et sous quelle licence ?~~ Répondu (25/10, pets.md) : le skill open source
`hatch-pet` d'OpenAI (Apache-2.0, vérifié dans son `LICENSE.txt`), qui génère les poses avec le
skill `imagegen` et produit une planche au format Codex à 9 lignes. La variante
`work-pets:create-pet` de ChatGPT Work (format v2 à 11 lignes) n'a pas de copie publique. Les
deux restent des outils externes, jamais une dépendance (`14` §2.2 et D12, `11` D9 et D10).
17. ~~**« Récupération du skill afin de faire le brocoli »** : quel skill, où, sous quelle licence ?
Rien n'a été trouvé dans emaki, `.claude/skills`, `sites/plans/pages/` ni `context.md`.~~
Répondu (25/10, pets.md) : c'est `hatch-pet`, lancé avec l'image de référence du personnage
comme source de vérité de son identité. Sa planche s'importe par une étape manuelle documentée,
sans commande ni code repris (`14` D12).
18. ~~**« Récupération de projet basic afin de créer des images en full JS »** : un dépôt existant à
importer (où, quelle licence), ou l'idée du bloc `pixel` (`11-images.md`) à construire ?~~
Répondu (25/10) : c'est un **atelier de création de personnages 2D/pixel en JavaScript**, à
construire. Recherche et état de l'art dans `16-atelier-personnages.md`.
19. ~~**lebrocoli.fr** : confirmes-tu que c'est **le seul** exemple réel autorisé (exception à la
règle Lorem Ipsum), dans le dossier unique `examples/scenario-lebrocoli` ? Le personnage a-t-il
déjà un nom ?~~ Répondu (25/10, pets.md puis l'image elle-même) : **oui**, lebrocoli.fr est le
seul nom réel autorisé, mais ses **lieux sont fictifs**. Le personnage s'appelle **Broc** ; son
image de référence est `examples/scenario-lebrocoli/cast/broc/reference.png` (1024×1024, fournie
par l'utilisateur), **© vguerand, tous droits réservés**, hors licence MIT du dépôt. Elle montre
un brocoli vert souriant au rendu 3D doux en T-pose, **sans smoking ni casquette** (la
description de `pets.md` est corrigée d'après l'image). La police de titre est **Unbounded**
(SIL OFL 1.1), à la place de Monument Extended. La voix, la personnalité et cinq scénarios ont
été délégués à l'assistant et écrits dans `sites/plans/pages/annexes/broc/` : ils restent
`inferred` jusqu'à la relecture de l'utilisateur, qui valide aussi les traits inférés. Détail
dans `14` D13.
Question 23, ~~**doublon dans le backlog** : la ligne « cartes.recit.dev | cartes.recit.dev » répète
le même nom. Le second devait-il être autre chose (par exemple `maps` ou `atlas`) ?~~ Répondu
(25/10) : le domaine principal est **maps.recit.dev**, `cartes.recit.dev` en est un alias 301 (`13`
D1, `07` §2).