Fondations

03 — Packaging : la vision complète des packages

Statut : accepté · Phase : transverse · Mis à jour : 02/11/2026.

Ce document est l'inventaire exhaustif. Il couvre tout ce qui existe aujourd'hui (le framework de sites, presentation-engine, emaki), ce qu'on garde, renomme ou supprime, ce qu'on crée, et les noms réservés sans être utilisés. Aucun projet du workspace ne doit exister sans une ligne dans ce document.

Légende des décisions :

• ✅ garder tel quel ;
• ✏️ renommer ou déplacer ;
• 🆕 créer ;
• 🗑️ supprimer ;
• 🔒 réserver le nom npm sans code ;
• 📅 planifié dans une phase ultérieure. Certains ont déjà un squelette privé 0.0.0 (export {}) créé en P1 : packages/{data,time} et packages/formats/{report,toon,book,roadmap,calendar,stories,paged} ; le code arrive dans la phase.

1. Découpage en sous-projets

Le monorepo est découpé en groupes. Chacun est un dossier qui correspond à un glob pnpm :

pnpm-workspace.yaml cible :

YAML
packages:
  - packages/*
  - packages/formats/*
  - packages/integrations/*
  - packages/tools/*
  - sites/*
  - examples/*
  - brand/tools
  - "!**/dist/**"
  - "!**/dist"

On retire les globs scripts, examples/**, website et docs. emaki est copié directement dans ces dossiers (voir 05-video.md), sans glob temporaire.

2. Arborescence finale

Code
recit/
├─ packages/
│  ├─ site/                      site (privé)            ← framework de sites, code de Récit
│  ├─ core/                        @recit/core
│  ├─ data/                        @recit/data               (données et graphiques, P6)
│  ├─ time/                        @recit/time               (dates, fuseaux, récurrences, ICS, P9)
│  ├─ geo/                         @recit/geo                (bloc ::map, lot P6, complet en P15)
│  ├─ form/                        @recit/form               (bloc :::form, lot P10, complet en P13)
│  ├─ scenario/                    @recit/scenario           (bible et attributs de scénario, P16)
│  ├─ theme/                       @recit/theme
│  ├─ components/                  @recit/components         (composants partagés par tous les formats)
│  ├─ cli/                         @recit/cli                (binaire `recit`)
│  ├─ recit/                       recit                     (alias sans scope)
│  ├─ create-recit/                create-recit              (npm create recit)
│  ├─ mcp/                         @recit/mcp
│  ├─ formats/
│  │  ├─ deck/                     @recit/deck               (+ @recit/deck/runtime)
│  │  ├─ motion/                   @recit/motion
│  │  ├─ motion-blocks/            @recit/motion-blocks
│  │  ├─ motion-render/            @recit/motion-render
│  │  ├─ report/                   @recit/report             (P6)
│  │  ├─ toon/                     @recit/toon               (webtoon, P7)
│  │  ├─ book/                     @recit/book               (P8)
│  │  ├─ roadmap/                  @recit/roadmap            (P9)
│  │  ├─ calendar/                 @recit/calendar           (P10)
│  │  ├─ stories/                  @recit/stories            (P11)
│  │  ├─ directory/                @recit/directory          (glossary et directory, lot P9, complet en P14)
│  │  └─ atlas/                    @recit/atlas              (P15)
│  ├─ integrations/
│  │  └─ site/                   @recit/site-stories
│  └─ tools/
│     ├─ paged/                    @recit/paged              (chaîne d'impression Node, P6 ; le stub de packages/formats/paged y est déplacé en PDF1)
│     ├─ app/                      @recit/app                (coquille Tauri 2 : un site en application desktop et mobile, Node, importée par la CLI seulement ; `18-mobile-desktop.md`)
│     ├─ studio/                   @recit/studio             (privé, squelette ; import d'emaki différé)
│     └─ site-kit/                 @recit/site-kit           (privé : en-tête et pied communs aux sites)
├─ sites/
│  ├─ www/                         recit.dev
│  ├─ docs/                        docs.recit.dev            (ex-`docs/` du framework de sites, déplacé)
│  ├─ components/                  components.recit.dev
│  ├─ presentation/                presentation.recit.dev
│  ├─ motion/                      motion.recit.dev
│  ├─ report/                      report.recit.dev          (P6)
│  ├─ webtoon/                     webtoon.recit.dev         (P7)
│  ├─ book/                        book.recit.dev            (P8)
│  ├─ roadmap/                     roadmap.recit.dev         (P9)
│  ├─ calendar/                    calendar.recit.dev        (P10)
│  ├─ story/                       story.recit.dev           (P11)
│  ├─ form/                        form.recit.dev            (site d'outil, P13)
│  ├─ directory/                   directory.recit.dev       (P14)
│  ├─ maps/                        maps.recit.dev            (P15)
│  └─ ai/                          ai.recit.dev              (site d'outil, P16)
├─ examples/
│  ├─ deck-starter/  deck-tech-talk/  deck-showcase/  deck-pitch/  deck-course/  deck-mdx/
│  ├─ motion-hello/  motion-saas/
│  ├─ report-quarterly/  report-study/  toon-episode/  book-novella/
│  ├─ roadmap-product/  calendar-meetups/  calendar-course/  stories-launch/
│  ├─ site-embed/                (récits intégrés dans une doc du framework de sites)
│  ├─ site-i18n/                 (doc du framework de sites multilingue, fixture de `e2e/site-i18n.spec.ts`)
│  └─ with-config/                 ✅ fixture des tests du cœur du framework de sites (gardée, voir §3.1)
├─ e2e/                            deck-features.spec.ts, deck-render.spec.ts, site-*.spec.ts, site-embed.spec.ts, site-i18n.spec.ts
├─ brand/
├─ sites/plans/pages/                           ce plan
├─ README.md  LICENSE.md  AGENTS.md  CLAUDE.md (lien vers AGENTS.md)
└─ biome.jsonc  nx.json  package.json  pnpm-workspace.yaml  vitest.config.ts  playwright.config.ts  lefthook.yml

3. Inventaire du le framework de sites : ce qu'on garde, ce qu'on supprime

3.1 Projets du workspace

3.2 Fichiers racine et CI

3.3 À l'intérieur de packages/site : on ne supprime rien

Les plugins internes (openapi, api-catalog, api-keys, search-inkeep, search-pagefind, markdown, custom-pages), les providers d'authentification et le code propre à l'éditeur d'origine restent. Les supprimer créerait des conflits à chaque synchronisation upstream. Ils ne sont simplement pas activés par les sites Récit, et le tree-shaking de Vite les écarte du bundle. S'ils pèsent quand même sur la taille ou la sécurité, on les désactive par configuration, jamais par suppression de code.

4. Inventaire de presentation-engine

5. Inventaire d'emaki

6. Tous les packages Récit

Noms npm à réserver en P0, même sans code : recit, create-recit, @recit/core, @recit/data, @recit/time, @recit/paged, @recit/report, @recit/toon, @recit/book, @recit/roadmap, @recit/calendar, @recit/stories, @recit/docs, et ceux des plans 10 à 14 (paragraphe suivant). C'est la liste de P0.1 dans 06-roadmap.md. Pas de @recit/video : « video » n'est qu'une redirection de domaine vers motion (voir 07-domaines.md).

Noms ajoutés par les plans 10 à 14 (ordre accepté le 24/10/2026), à réserver : @recit/form, @recit/directory, @recit/geo, @recit/atlas, @recit/scenario, et @recit/pixel (nom réservé seulement, sans package pour l'instant). Les commandes CLI qu'ils prévoient sont uniques par besoin et figurent dans la ligne @recit/cli ci-dessus : recit form check-endpoint (P13), recit validate --links (P14, une option plutôt qu'un verbe), recit validate --strict, recit prompts build, recit assets register et recit skills export (P16), et recit geocode après la v1 seulement (06-roadmap.md, règle B9).

7. Renommage complet

À appliquer partout : code, tests, docs, exemples, CSS, config, messages d'erreur, i18n.

7.1 Packages et dossiers

7.2 Commandes, fichiers et config

7.3 API et identifiants

7.4 Identité et infrastructure

Méthode : un commit de renommage par package, puis grep -rniE "presentation|emaki|site-presentation" packages sites examples doit être vide (hors alias documentés et sites/plans/pages/archive/).

8. Exports

Chaque package expose exports avec trois conditions :

• types ;
• @recit/source, vers src/*.ts (consommer les sources sans build en dev). Pas development : webpack et Next l'activent par défaut et livreraient notre TypeScript à un utilisateur qui ne le transpile pas (audit ST-3) ;
• default, vers dist/*.js.

Les vite.config.ts des sites et des exemples ajoutent resolve.conditions: ["@recit/source"].

JSON
// packages/core/package.json
"exports": {
  ".":         { "types": "./dist/index.d.ts",   "@recit/source": "./src/index.ts",   "default": "./dist/index.js" },
  "./browser": { "types": "./dist/browser.d.ts", "@recit/source": "./src/browser.ts", "default": "./dist/browser.js" },
  "./config":  { "types": "./dist/config.d.ts",  "@recit/source": "./src/config/index.ts", "default": "./dist/config.js" }
  // … même forme pour ./schema, ./i18n (P3), ./print (P6) et ./jsonld (P10), voir §6
}

@recit/site-stories expose en plus ./vite et ./styles.css (CSS limitée au wrapper, construite par scripts/build-css.mjs).

Feuilles de style publiées (plan 19). Plus de Tailwind dans aucun paquet. Chaque paquet qui dessine publie une feuille unique, ./styles.css, compilée de ses modules CSS par Lightning CSS (scripts/build-css-modules.js, table de classes typée X.module.css.ts à côté de chaque module) : @recit/components, @recit/deck, @recit/motion-blocks, @recit/site-stories. @recit/theme publie ses feuilles de base (tokens.css, fonts.css, deck.css, page.css, print.css) et reset.css, que le site importe en couche theme, le deck en couche base et Storybook en couche theme. La CLI assemble la feuille d'un deck avec esbuild : reset, jetons, feuilles du thème, des paquets, modules de l'auteur, theme.customCss, dans cet ordre.

@recit/core expose aussi ./print (contrat d'impression, code navigateur sans dépendance au DOM hors garde typeof window). @recit/paged est Node uniquement et expose ./runner ; aucun format ne l'importe dans un bundle client (15-export-pdf.md §4).

Règle de dépendances entre groupes. Les formats et les intégrations dépendent des fondations. Une intégration peut dépendre d'un format (@recit/site-stories → @recit/deck, @recit/motion-blocks). Les fondations ne dépendent jamais d'un format. @recit/paged (scope:tool) n'est importé que par la CLI et les outils de rendu Node : ni un format ni une fondation n'en dépend, ils exposent une vue imprimable et rien d'autre (15-export-pdf.md §3.1). Une capture (tranches du toon, PNG d'une carte, image d'une story) est donc lancée par la CLI à travers @recit/paged/runner.

Les tags. Neuf, un par projet, dans nx.tags de son package.json. Cette liste est la seule (06-roadmap.md en annonçait six, ce paragraphe quatre — audit ST-6).

Ce que chaque groupe a le droit d'importer. Une fondation ne voit que les fondations ; un format voit les fondations et les formats ; une intégration y ajoute les intégrations ; un outil y ajoute les outils ; la distribution y ajoute les outils et la distribution ; un site et un exemple voient tout sauf la suite e2e ; scope:test voit tout. Les deux projets scope:vendor ne sont pas tagués dans leur package.json : ce sont des fichiers d'origine externe, gardés tels quels (NOTICE.md).

scripts/check-package-boundaries.js lit ces tags et les dépendances workspace:*, refuse toute arête hors du tableau, et tient la liste des violations connues : chacune porte le constat qui la possède, et une entrée qui ne correspond plus à aucune arête échoue elle aussi. Il tourne dans pnpm check. Une seule violation est tolérée aujourd'hui : @recit/site-stories → @recit/cli (ST-5).

9. Outillage : on adopte celui du fork

| Sujet | presentation-engine | emaki | Récit (fork) | Action | | ------------- | ---------------------------- | -------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------- | | Orchestration | turbo 2.4 | turbo | nx 23.3 | supprimer les turbo.json. Un project.json par package (ou cibles inférées), tags de groupe | | Lint | oxlint 1.88 | — | biome 2.5 | migrer les règles utiles (no-shadow…) | | Format | oxfmt 0.73 | — | oxfmt 0.36 | "**/*.mdx" dans ignorePatterns (oxfmt casse le .mdx) | | Build | tsc (+ build-css.mjs) | tsc | tsdown 0.23 | un tsdown.config.ts par package | | TypeScript | 5.7 | — | 6.0.3 | imports relatifs en .js (convention AGENTS.md) | | Tests | vitest (88 unitaires, 7 e2e) | vitest + goldens PNG | vitest 4.1 + playwright 1.63 | vitest.config.ts racine : projects: ["packages/!(formats | integrations | tools)", "packages/{formats,integrations,tools}/\*"] | | Hooks git | — | — | lefthook | rien à faire | | Node / pnpm | — | — | Node ≥ 22.22, pnpm ≥ 11 | aligner les engines |

Versions du catalogue pnpm :

• react / react-dom 19.2.8, zod 4.6.5, typescript 6.0.3, @types/node 22.20.5 ;
• vite 8.1.5 (presentation-engine utilisait ^8.3.5, à aligner) ;
• shiki 4.5.0, @mdx-js/mdx 3.1.1, react-router 8.4.0 ; @mantine/* 9.7.4 (plan 19, qui a retiré tailwindcss) ;
• @recit/site : 0.86 → 0.93 (workspace).

Points d'attention :

• minimumReleaseAge: 4320 (3 jours) s'applique à Remotion et au SDK MCP (@tailwindcss/oxide est parti avec Tailwind, plan 19).
• allowBuilds : ajouter le compositor de Remotion si nécessaire.
• Les peers react >=18 d'emaki passent à >=19.2.7.

10. Publication

• Versions 0.1.0-alpha.N, communes à tous les packages publiés (une seule version, nx release avec release.projects = packages publiés de la section 6, listés un par un : un package y entre quand il devient public, scripts/__tests__/release-workflow.spec.ts le vérifie).
• Actions GitHub épinglées par SHA (Dependabot les met à jour), npm en version exacte dans le job qui publie. Le même test passe chaque commande nx release du workflow aux contrôles d'arguments de nx (--print-config).
• Un seul workflow release.yaml, déclenché à la main depuis main, sans publication canary de @recit/site : build.yaml rejoué, contrôle des version plans, dry run, puis job d'écriture derrière l'environnement npm à relecteur obligatoire (version, changelog, commit, tag, push, GitHub Release, npm, dans cet ordre).
• Version plans en 0.x : preminor à la première release d'une phase, prerelease ensuite, un seul bump par plan. Sur une version 0.x stable (0.0.0), au moins un plan en preminor. scripts/check-version-plans.js (dans pnpm check) refuse patch, minor et major, que semver publierait en stable malgré le preid.
• publint et size-limit (.size-limit.json : le runtime du deck et examples/site-embed).
• @recit/site est privé aujourd'hui, alors que @recit/site-stories (en peer, >=0.93), recit-site et @recit/app en dépendent : hors du dépôt, personne ne peut construire un site. Le publier avec l'alpha est la décision D2 de 22 · Alpha publique, question ouverte.
• Aucune publication npm sans validation explicite.