Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

docs: spec agent-written shader effects

EtienneLescot4625612e6448
diff --git a/docs/shader-effects.md b/docs/shader-effects.md
new file mode 100644
index 000000000..5eafc05af
--- /dev/null
+++ b/docs/shader-effects.md
@@ -0,0 +1,778 @@
+# Effets shader écrits par les agents
+
+Un agent écrit un effet visuel en WGSL. Le compositeur l'applique en une passe sur l'image
+composée, en preview comme à l'export. L'effet vit dans le document comme une région de la
+timeline : on peut le relire, le régler, le déplacer et le supprimer, que l'on soit l'utilisateur
+ou un agent.
+
+Ce document fixe le modèle, le contrat, le DSL, le rendu et l'interface, puis découpe les PR.
+Il part du spike Windows (branche `worktree-custom-shader-fx-spike`, commits `9cb30018d` et
+`42728e335`).
+
+**Ce que le spike a établi**
+
+- **Coût.** +0,04 ms par frame en 1080p, +0,12 ms en 4K, pour un effet lourd.
+- **Export.** 520 ms sans effet, 523 ms avec, pour 180 frames.
+- **Preview.** Le rendu tient la cadence de la source, avec ou sans effet.
+- **SSOT.** Entre la vue live et le MP4, l'écart reste au niveau du bruit du codec.
+- **Boucle d'agent.** À partir du prompt « effet ripple lors du clic », un agent a écrit un
+ effet correct en deux itérations, par les seuls outils MCP.
+
+---
+
+## A. Les principes
+
+1. **Le compositeur reste la seule source de pixels.** Un effet est une passe de
+ `compose_frame`, que la preview et l'export appellent tous les deux. Il n'existe pas de
+ chemin de rendu propre aux effets.
+2. **Le document ne stocke que la source.** Le WGSL, son nom, sa description, ses paramètres et
+ les valeurs posées. Tout binaire compilé en est dérivé, et n'est jamais écrit dans le projet.
+3. **Un effet est une fonction pure** de l'image composée, du temps, du curseur et de ses
+ paramètres. Pas d'état d'une frame à l'autre.
+4. **Le rendu ne compile jamais.** Le code est compilé à l'écriture, puis à la pose de la scène,
+ sur un thread de fond.
+5. **Ce que seul le compositeur sait entre dans le contrat.** La place de l'écran, de la webcam
+ et du curseur dans la sortie, après zoom, layout et tilt : un effet ne peut pas la recalculer.
+ Le prompt du ripple l'a montré, il ne pouvait pas s'écrire sans.
+6. **L'agent passe par le DSL.** Il appelle des outils de document. Il n'écrit jamais le JSON du
+ projet.
+7. **Pour tout le monde.** Aucun réglage, aucune condition ne réserve la fonctionnalité à
+ certains utilisateurs.
+
+---
+
+## B. Le modèle de données
+
+### B.1 Deux objets : la définition et la région
+
+- **La définition** (`shaderEffects`) porte le code, son nom, sa description et ses paramètres
+ déclarés. Elle dit ce qu'est l'effet.
+- **La région** (`shaderEffectRanges`) pose une définition sur la timeline, avec ses valeurs de
+ paramètres. Elle dit où l'effet s'applique et comment il est réglé.
+
+La séparation sert trois choses :
+- réutiliser un effet à plusieurs endroits sans dupliquer son code ;
+- régler une région (`values`) sans réécrire de code ;
+- garder léger le snapshot de l'agent, où le code n'apparaît qu'une fois par définition.
+
+### B.2 Le schéma
+
+Deux tableaux de premier rang dans `documentSchemaShape`
+(`src/lib/ai-edition/schema/index.ts`), à côté de `zoomRanges` :
+
+```ts
+const paramName = z.string().regex(/^[a-z][a-z0-9_]{0,31}$/);
+
+const shaderEffectParamSchema = z.discriminatedUnion("type", [
+ z.object({ type: z.literal("number"), name: paramName, label: z.string().max(40),
+ default: z.number(), min: z.number(), max: z.number() }),
+ z.object({ type: z.literal("toggle"), name: paramName, label: z.string().max(40),
+ default: z.boolean() }),
+ z.object({ type: z.literal("color"), name: paramName, label: z.string().max(40),
+ default: hexColor }),
+ z.object({ type: z.literal("point"), name: paramName, label: z.string().max(40),
+ default: z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) }) }),
+]);
+
+export const shaderEffectSchema = z.object({
+ id: z.string().min(1), // "fx_…"
+ name: z.string().min(1).max(60), // ce que la pilule affiche
+ description: z.string().max(500).default(""), // pour l'agent suivant : ce que l'effet fait
+ contract: z.literal(1),
+ code: z.string().min(1).max(65_536), // plafond technique, pas un budget (C.7)
+ params: z.array(shaderEffectParamSchema).max(32).default([]),
+ origin: z.enum(["agent", "user"]).default("agent"),
+});
+
+export const shaderEffectRangeSchema = endGteStart(z.object({
+ id: z.string().min(1), // "fxr_…", un par fragment
+ groupId: z.string().min(1).optional(), // partagé par les fragments d'une même pilule
+ startMs: z.number().nonnegative(), // cache dérivé de l'ancre, comme les zooms
+ endMs: z.number().nonnegative(),
+ ...clipAnchorShape,
+ effectId: z.string().min(1),
+ values: z.record(z.string(), shaderEffectValueSchema).default({}),
+ target: z.enum(["image", "text", "both"]).default("image"),
+ lane: z.number().int().min(0).max(7).default(0),
+}), "endMs", "startMs");
+
+// documentSchemaShape
+shaderEffects: z.array(shaderEffectSchema).default([]),
+shaderEffectRanges: z.array(shaderEffectRangeSchema).default([]),
+```
+
+- **`values`** ne porte que ce qui diffère du `default` de la définition. Une valeur hors bornes
+ est ramenée dans les bornes au parse, sans erreur, comme les réglages du look.
+- **Les `label`** sont écrits par l'agent, dans la langue de l'utilisateur, et affichés tels
+ quels. Ils ne passent pas par l'i18n : c'est du contenu, pas de l'interface.
+- **`groupId`** reprend le principe du `trackId` des pistes audio. Une région coupée par un trim
+ ou une frontière de clip reste une seule pilule. Sa progression (`ctx.region`) court sur la
+ pilule entière, au lieu de repartir de zéro à chaque fragment.
+- **Une définition que plus aucune région n'utilise est retirée** à la sauvegarde. Le document ne
+ garde pas de code mort.
+- **Les `max` du schéma sont des plafonds techniques, pas des budgets.** Ils protègent le document
+ (64 Ko de code, 32 paramètres, 8 lanes) et sont loin au-dessus de tout effet raisonnable. Ce que
+ l'agent doit viser, ce sont les paliers de C.7.
+
+### B.3 Ancrée sur le clip, comme les autres régions
+
+Une région d'effet est une région de plus, pas un cas à part. Elle passe par tout le pipeline des
+modificateurs ([timeline-model.md](../technical-documentation/architecture/timeline-model.md)),
+et suit donc les clips quand on les déplace, les coupe ou les supprime. Le spike la stockait en
+ms brutes, sans ancre : elle restait en place pendant que les clips bougeaient.
+
+- **`RegionKind`** gagne `"shaderEffect"`. Les sites qui switchent dessus sont listés dans
+ [editor-shell.md, « Adding a region kind »](../technical-documentation/architecture/editor-shell.md)
+ (ses numéros de ligne sont périmés). Les principaux :
+ - **le crochet des éditions de clips :** `mapAllRegionCollections` (`document/timeline.ts`),
+ par lequel passent moveClip, duplicateClip, setClipSourceRange, removeClip, replaceTimeline
+ et l'insertion ;
+ - **les listes codées en dur :** `anchoredRegionsOf`, et `removeRegion`/`EDIT_REGIONS`, dont
+ les types rendent un oubli bloquant à la compilation ;
+ - **côté agent :** `ModifierKind`, `modifierIds`, `modifierIdsOf` et la recherche d'id de
+ `removeModifier` (`agent-tools.ts`) ;
+ - **côté éditeur :** `removeRegions` (`useTimeline.ts`), `regionClipboard.ts`, le
+ copier-coller et la touche Suppr de `NewEditorShell.tsx`.
+- **L'identité des pilules** (`regionIdentityKey`) compte tous les champs sauf la position et la
+ provenance. Deux régions contiguës du même effet, aux mêmes `values`, se fondent donc en une
+ pilule, comme deux zooms identiques.
+- **Les pistes.** Deux régions d'une même `lane` ne se chevauchent pas, avec la règle des autres
+ régions (`refuseIfBlocked`). Les lanes s'appliquent dans l'ordre : la lane 0 d'abord, au plus
+ près du contenu. C'est ce qui permet un ripple sur toute la vidéo ET un glitch
+ sur une coupe.
+- **Après une édition de clip** qui fait se chevaucher deux régions d'une même lane, le rendu
+ applique les deux, dans l'ordre du tableau, et la piste les montre superposées. Pas de
+ réparation automatique : contrairement à l'audio, deux effets superposés ne cassent rien.
+
+### B.4 Persistance
+
+- **Champs additifs, sans montée de `schemaVersion`.** C'est la convention d'`audioTracks` et de
+ `vocabulary` : `.default([])`, et `z.object` qui ignore les clés inconnues. Un document écrit
+ avant cette fonctionnalité s'ouvre tel quel.
+- **Le prix de ce choix.** Une build antérieure qui ouvre puis sauvegarde un projet perd ses
+ effets en silence. Voir K, question 1.
+- **Pas dans les style presets.** Un preset porte le look du projet, jamais son contenu
+ (`stylePresets.ts`), et un effet est posé sur des moments précis du contenu.
+- **`openscreen info`** compte les effets avec les zooms et les trims (`documentInfoFields`,
+ `projectCommands.ts`).
+
+### B.5 Ce que la scène native reçoit
+
+`buildSceneDescription` projette les régions comme les zooms (`projectRegionsToSource`). Il
+ajoute à chaque fragment ce que le compositeur ne peut pas recalculer :
+
+```json
+"shaderEffects": [{
+ "clipIndex": 0, "startSec": 1.0, "endSec": 5.0,
+ "programmeStartSec": 1.0, "programmeEndSec": 5.0,
+ "target": "image", "lane": 0,
+ "contract": 1, "code": "fn effect(uv: vec2<f32>) -> vec4<f32> { … }",
+ "params": [ { "name": "strength", "type": "number" } ],
+ "values": { "strength": 1.0 }
+}]
+```
+
+- **`programmeStart/EndSec`** est l'étendue de la pilule entière en temps programme. Le
+ compositeur en tire `ctx.region` sans rien savoir des trims.
+- **`values` est déjà normalisé :** une couleur devient 4 floats, un toggle 0 ou 1, un point
+ 2 floats, et une valeur absente prend son `default`.
+- **Le packing dans l'uniform** se fait côté Rust, au même endroit que la struct WGSL générée.
+ Le layout n'a qu'une source.
+- **Les fragments sous un trim** (`underTrim`) restent dans la scène, comme pour les autres
+ régions. Ils se dessinent quand la tête de lecture est posée sur le trim, et l'export ne les
+ rencontre jamais.
+
+---
+
+## C. Le contrat WGSL (version 1)
+
+### C.1 Ce que l'agent écrit
+
+Une seule fonction, appelée pour chaque pixel de la sortie :
+
+```wgsl
+fn effect(uv: vec2<f32>) -> vec4<f32>
+```
+
+`uv` va de (0, 0) en haut à gauche à (1, 1) en bas à droite de la sortie. La fonction rend la
+couleur finale du pixel. Le reste du module (bindings, entrées, `@vertex`, `@fragment`) est écrit
+par le compositeur et placé APRÈS le code de l'agent : en WGSL, l'ordre des déclarations est
+libre, et les erreurs pointent ainsi les lignes que l'agent a écrites.
+
+### C.2 Ce qui est fourni
+
+| Nom | Type | Sens |
+|---|---|---|
+| `frame(uv)` | `vec4<f32>` | L'image composée en ce point (D.1 dit ce qu'elle contient). Échantillonnage bilinéaire, bords répétés. |
+| `ctx.resolution` | `vec2<f32>` | Taille de la sortie, en px. |
+| `ctx.time` | `f32` | Secondes de programme, continues à travers coupes, clips et vitesses. |
+| `ctx.region` | `vec4<f32>` | x : progression de 0 à 1 sur la pilule entière. y : sa durée en s. z : secondes depuis son début. |
+| `ctx.cursor` | `vec4<f32>` | xy : la pointe en uv de sortie. z : 1 si elle est à l'écran. |
+| `ctx.clicks[i]` | `vec4<f32>` | Les 4 derniers clics des 2 dernières secondes, du plus récent au plus ancien. xy : le point du clic en uv de sortie. z : secondes écoulées depuis. w : 1 si l'entrée est occupée. |
+| `ctx.footage` | `vec4<f32>` | Le rect de l'enregistrement en uv de sortie (x, y, w, h), après zoom et layout. Sous un tilt 3D, c'est sa boîte englobante. |
+| `ctx.camera` | `vec4<f32>` | Le rect de la webcam en uv de sortie. Taille nulle sans caméra. |
+| `params.<nom>` | selon le type | Les paramètres déclarés par l'effet (C.3). |
+| `fx_px(n)` | `f32` | `n` pixels d'une sortie 1080p, en fraction de la hauteur. |
+| `fx_hash(p)` | `f32` | Hasard déterministe dans [0, 1) pour un `vec2<u32>`, identique sur tous les GPU (PCG). |
+
+- **Tout ce qui est en uv de sortie** est déjà passé par le zoom, le layout, le cadre et le
+ tilt. Ces valeurs viennent de `plan_frame` et `plan_cursor` (`frame_geometry.rs`), que les
+ trois backends partagent.
+- **Le point d'un clic** est la pointe à l'instant du clic, au même endroit que l'impact intégré
+ (mode 16).
+- **Le curseur dessiné** passe par le lissage et peut traîner un instant derrière ce point quand
+ la souris arrive pile au moment du clic. Ce cas est rare sur une vraie prise.
+- **Le spike exposait un seul clic** (`ctx.click`). Avec quatre, deux clics rapprochés gardent
+ chacun leur onde.
+
+### C.3 Les paramètres sont nommés et typés
+
+Un effet déclare ses paramètres. Le compositeur en génère une struct `FxParams` liée en uniform,
+et le code lit `params.radius`, jamais `param(2)`. Un agent qui relit l'effet six mois plus tard
+comprend ce qu'il lit, et l'inspecteur sait quel contrôle afficher.
+
+| `type` | WGSL | Dans le document | Contrôle de l'inspecteur |
+|---|---|---|---|
+| `number` | `f32` | nombre, entre `min` et `max` | curseur |
+| `toggle` | `f32` (0 ou 1) | booléen | interrupteur |
+| `color` | `vec4<f32>` (RGBA, 0 à 1) | `#rrggbb` ou `#rrggbbaa` | sélecteur de couleur |
+| `point` | `vec2<f32>` (uv de sortie) | `{ x, y }` | deux curseurs |
+
+- **Huit paramètres au plus, recommandé.** Au-delà, l'inspecteur devient une liste que personne
+ ne règle. Ce n'est pas un refus : le plafond technique est à 32.
+- **Les noms** sont des identifiants WGSL en `snake_case`, uniques, hors mots réservés.
+- **Le layout uniform est calculé côté Rust** avec les règles d'alignement de WGSL : `f32` sur 4,
+ `vec2` sur 8, `vec4` sur 16. Il produit le même ordre et les mêmes trous que la struct générée,
+ et un test compare les offsets de naga à ceux du packer.
+- **Un paramètre doit se voir.** La description de l'outil exige qu'il change visiblement
+ l'effet sur toute sa plage. Un contrôle qui ne fait rien à l'écran est exactement ce que
+ l'inspecteur doit éviter.
+
+### C.4 Les règles
+
+- **Pure.** Le résultat ne dépend que de `uv`, de `frame()`, de `ctx` et de `params`. Pas d'état
+ d'une frame à l'autre, pas d'horloge, pas de compteur de frames. La preview saute d'une frame à
+ l'autre au seek, l'export les rend dans l'ordre, et les deux doivent donner le même pixel.
+- **Indépendante de la résolution.** La preview rend plus petit que l'export. Distances en uv ou
+ en `fx_px`, jamais en px bruts.
+- **Hasard par `fx_hash`.** Le classique `fract(sin(x) * 43758.5453)` donne des valeurs
+ différentes d'un GPU à l'autre.
+- **Boucles à borne littérale.** Toute boucle s'arrête sur un compteur comparé à un littéral
+ (`for (var i = 0; i < 16; i++)`). Une boucle dont la borne n'est pas un littéral est refusée.
+ C'est la seule règle ferme du contrat, et ce n'est pas un budget : une boucle qui ne finit pas
+ bloque le GPU, le TDR de Windows le réinitialise, et l'app perd son device sans retour (G.2).
+ La valeur de la borne, elle, est libre : elle compte dans le palier de coût (C.7).
+- **Un plafond de sécurité sur le travail par pixel :** 4 096 itérations, toutes boucles
+ imbriquées comprises. L'ordre de grandeur visé est le seuil du TDR (2 s par frame) sur un GPU
+ intégré en 1080p ; c'est une estimation, que la PR 1 mesure et ajuste. Un flou de 64 taps en
+ fait 64, un raymarching de 64 pas sur 8 objets 512.
+- **Alpha.** Pour les cibles `image` et `both`, la valeur rendue remplace le pixel ; les
+ encodeurs ignorent l'alpha, et rendre `frame(uv).a` suffit. Pour la cible `text`, `frame()`
+ rend le calque des textes en alpha prémultiplié, transparent hors du texte, et l'effet doit
+ rendre de l'alpha prémultiplié lui aussi (D.1).
+
+### C.5 Le contrat est versionné
+
+Chaque définition porte `contract: 1`.
+- **Le prélude d'une version livrée ne change plus.** Une entrée nouvelle s'ajoute à la fin de
+ `FxContext` : le code existant ne la lit pas et compile à l'identique.
+- **Un changement de sens crée la version 2,** et le compositeur garde le prélude de la 1.
+- **Un document qui porte une version inconnue** (écrit par une build plus récente) garde ses
+ régions, sans les appliquer.
+
+### C.6 Exemple
+
+Le ripple du spike, réécrit pour le contrat v1 :
+
+```wgsl
+// Une onde part de chaque clic, réfracte l'image et laisse deux ou trois vagues derrière elle.
+fn ripple(uv: vec2<f32>, click: vec4<f32>) -> vec2<f32> {
+ if (click.w < 0.5 || click.z > params.duration) { return vec2<f32>(0.0); }
+ let t = click.z / params.duration;
+ let aspect = ctx.resolution.x / ctx.resolution.y;
+ let d = (uv - click.xy) * vec2<f32>(aspect, 1.0);
+ let r = length(d);
+ let x = params.radius * (1.0 - pow(1.0 - t, 3.0)) - r;
+ let env = smoothstep(-0.008, 0.0, x) * exp(-max(x, 0.0) / 0.07);
+ let wave = sin(x / 0.03 * 6.2831853) * env * (1.0 - t) * (1.0 - t) * params.strength;
+ let dir = select(vec2<f32>(0.0), d / r, r > 1e-5);
+ return dir * wave * 0.01 / vec2<f32>(aspect, 1.0);
+}
+
+fn effect(uv: vec2<f32>) -> vec4<f32> {
+ var offset = vec2<f32>(0.0);
+ for (var i = 0; i < 4; i++) { offset += ripple(uv, ctx.clicks[i]); }
+ return frame(uv - offset);
+}
+```
+
+Avec `params` : `strength` (number, 0 à 2, 1), `radius` (number, 0,05 à 0,5, 0,2), `duration`
+(number, 0,3 à 2 s, 0,9).
+
+### C.7 Le coût : des paliers indicatifs, pas des limites
+
+Le coût d'un effet est estimé depuis son code, sans le faire tourner. Il ne dépend donc pas de la
+machine : le même code reçoit le même palier partout, et un effet haut de gamme n'est jamais
+refusé parce que la machine qui l'écrit est modeste.
+
+- **L'estimation se fait sur l'IR de naga.** Elle compte les lectures de `frame()` par pixel,
+ multipliées par la borne des boucles qui les contiennent ; les fonctions appelées sont
+ dépliées. Les lectures de texture dominent le coût mesuré dans le spike : c'est la bande
+ passante qui paie.
+- **Les paliers**, en lectures par pixel :
+
+| Palier | Lectures | Exemples | Recommandation |
+|---|---|---|---|
+| Léger | ≤ 8 | vignette, étalonnage, ripple à 4 clics | Partout, y compris sur toute la vidéo. |
+| Moyen | ≤ 32 | aberration chromatique échantillonnée, petit flou, glitch | Sur des régions de quelques dizaines de secondes. |
+| Lourd | ≤ 128 | gros flou, bokeh | Sur des régions courtes : une transition, un moment fort. |
+| Très lourd | au-delà | raymarching, simulations | Quelques secondes. L'export reste juste, mais plus lent ; la preview peut ralentir sur un petit GPU. |
+
+- **Les seuils sont à calibrer à la PR 1,** en ms mesurées sur le GPU intégré de référence (le
+ Radeon 610M des mesures Linux) et sur la RTX du spike. La description de l'outil les donne
+ ensuite en ms, pour que l'agent raisonne en temps et non en lectures.
+- **Plusieurs effets au même instant s'additionnent.** Le retour d'un outil donne le palier de
+ l'effet, et le palier cumulé du moment le plus chargé de sa région.
+- **Rien n'est refusé au coût.** Le palier et sa recommandation reviennent à l'agent (E.3), qui
+ décide, et ils restent lisibles dans le snapshot (E.2).
+
+---
+
+## D. Le rendu
+
+### D.1 Où la passe s'insère
+
+`compose_frame` dessine, dans l'ordre :
+1. le fond ;
+2. le métrage et le cadre ;
+3. les flous de confidentialité ;
+4. le curseur ;
+5. la webcam ;
+6. les annotations et les sous-titres.
+
+Une région choisit sa cible (`target`). Sans demande explicite, c'est `image`.
+
+- **`image`** : l'image sans les textes. La passe s'insère avant les annotations et les
+ sous-titres. Un effet déforme l'écran, la webcam, le curseur et le fond, jamais le texte que
+ l'utilisateur a posé pour être lu.
+- **`text`** : les textes seuls (annotations et sous-titres). Les textes sont dessinés dans un
+ calque transparent à part, l'effet s'y applique, puis le calque est composé par-dessus l'image
+ (« over » prémultiplié). L'image dessous reste intacte. Le calque n'existe que si une région
+ `text` couvre la frame.
+- **`both`** : l'image finale, textes compris, par exemple pour un fondu au noir qui doit couvrir
+ les sous-titres. La passe vient après tout.
+
+Les flous de confidentialité restent sûrs. L'effet ne voit que des pixels déjà floutés et ne peut
+rien y retrouver : il n'existe aucun chemin vers l'image d'avant le flou.
+
+### D.2 Plusieurs effets à la fois
+
+- **L'ordre.** Les régions actives à la frame s'appliquent par lane croissante, puis dans
+ l'ordre du tableau.
+- **Le coût.** Chacune fait une copie du RT dans `ann_copy` et une passe plein cadre.
+- **Les cibles s'enchaînent dans l'ordre du dessin :** les effets `image`, puis les textes et
+ leurs effets `text`, puis les effets `both`. Un effet ne voit que ce qui est dessiné avant lui.
+
+### D.3 Les chemins de rendu
+
+- **Un seul `compose_frame`.** La preview (`live.rs`), l'export MP4 et l'export GIF
+ (`walk_composited_timeline`, `timeline_walk.rs`) l'appellent tous. Les effets apparaissent
+ donc partout, sans code propre à chaque chemin.
+- **Une passe par frame de sortie.** `compose_frame_mb` n'a aucun appelant, et le flou de
+ mouvement est calculé par calque (`mb_taps`).
+
+### D.4 La compilation : une fois, hors du rendu
+
+Il y a deux compilations, à deux moments :
+
+1. **À l'écriture.** Quand un outil pose ou change un code (`addEffect`,
+ `setEffectDefinition`), le processus principal appelle `validateShaderEffect` de l'addon.
+ - **La compilation est réelle,** pour le backend de la machine, en plus de la validation
+ naga. « Accepté » veut donc dire « se dessinera ».
+ - **Le coût est estimé** depuis le code (C.7), sans rendu ni mesure sur la machine.
+ - **L'erreur revient à l'agent** avec la ligne et la colonne de SON code.
+2. **À la pose de la scène** (`Compositor::set_scene`). Chaque code nouveau part compiler sur un
+ thread de fond.
+ - **La preview** saute l'effet le temps de la compilation, environ 10 ms, puis recompose la
+ frame en pause (`shader_fx_landed`).
+ - **L'export** attend le binaire, et ne rend jamais une frame sans son effet. C'est le mode
+ par défaut du compositeur : seule la vue live le coupe.
+
+Le cache est en mémoire, par compositeur.
+- **La clé** est le hash de (contrat, layout des paramètres, code).
+- **L'éviction** est LRU au-delà de 64 entrées : un agent qui itère en crée une par version.
+- **Pas de cache disque en v1.** 10 ms par effet ne le justifient pas, et Metal comme Mesa gardent
+ déjà leur propre cache de shaders. L'app ne passe d'ailleurs aujourd'hui aucun dossier
+ inscriptible au natif : il faudrait une variable d'environnement sur le modèle de
+ `OPENSCREEN_FONTS_DIR`.
+
+### D.5 Par plateforme
+
+Une seule source WGSL, traduite par naga au moment de compiler.
+
+| | Windows | macOS | Linux |
+|---|---|---|---|
+| Traduction | naga vers HLSL SM 5.0 | naga vers MSL | aucune : WGSL tel quel |
+| Compilation | `D3DCompile` (FXC) vers DXBC, puis `CreateVertexShader`/`CreatePixelShader` | `new_library_with_source`, puis `make_pipeline(…, Blend::Replace)` | `create_shader_module`, puis `create_render_pipeline` |
+| Thread de fond | naga et FXC (fait) | bibliothèque et pipeline, sous `autoreleasepool` | module et pipeline |
+| Copie du RT | `CopySubresourceRegion` vers `ann_copy` (fait) | `snapshot_rt(cmd_buf, false)` | `copy_texture_to_texture` vers `ann_copy` (comme le verre) |
+| Insertion | fin de `compose_frame` (fait) | entre `draw_annotations(…, false)` et `submit` | entre l'ann-pass et `submit` |
+| Uniforms | `Map(WRITE_DISCARD)` (fait) | `set_fragment_bytes` | `create_buffer_init(UNIFORM)` par draw |
+
+**macOS en détail**
+- **Activer `msl-out`.** Le dépôt l'obtient aujourd'hui par unification des features de wgpu ; le
+ déclarer explicitement sous `cfg(target_os = "macos")`.
+- **Pas d'objet sampler.** Les shaders Metal du dépôt utilisent des `constexpr sampler` :
+ passer le sampler en `inline_samplers` de naga (`BindSamplerTarget::Inline`).
+- **Lier les bindings explicitement.** Remplir `per_entry_point_map` pour `fx_fs` : texture,
+ sampler, buffer. Sinon `fake_missing_bindings` émet `[[user(fake0)]]`, qui n'est pas du MSL
+ valide.
+- **Lire les noms de fonctions** dans `TranslationInfo.entry_point_names`.
+- **Le thread de fond.** `Device`, `Library` et `RenderPipelineState` de metal-rs sont `Send` et
+ `Sync`, et `live.rs` déplace déjà un `Gpu` vers un thread de préchargement.
+
+**Linux en détail**
+- **Un bind group layout explicite,** jamais `layout: None`. Sinon un effet qui n'appelle pas
+ `frame()`, ou ne lit pas `ctx`, perd ces bindings, et le bind group échoue à la validation.
+- **Le thread de fond.** `wgpu::Device` est `Send`, `Sync` et `Clone` : le pipeline peut se
+ construire hors du thread de rendu.
+- **Valider avant wgpu.** Aucun `on_uncaptured_error` n'est posé, donc une erreur de validation
+ wgpu fait paniquer. La pré-validation par naga (`shader_fx::validate`) en protège.
+
+**naga reste en 24.** À partir de la 25, sa sortie HLSL déclare les samplers dans un tas D3D12
+(`register(s0, space0)`), que FXC refuse en `ps_5_0` (erreur X3721). Le test
+`a_valid_effect_becomes_hlsl_that_d3d11_accepts` garde cette frontière : il doit passer avant tout
+bump de naga ou de wgpu.
+
+### D.6 Un effet qui ne compile pas au rendu
+
+Ce cas arrive avec un document écrit ailleurs, une version de contrat inconnue ou un
+compilateur qui diffère d'une machine à l'autre.
+- **La région ne se dessine pas,** et la frame reste celle de la composition.
+- **L'erreur est écrite une fois** dans le journal natif (`[shader-fx]`) et remonte à
+ l'inspecteur (F.2).
+- **L'export ne s'arrête pas.** Un effet manquant vaut mieux qu'un export perdu, et l'agent ou
+ l'utilisateur a déjà vu l'erreur à l'écriture.
+
+---
+
+## E. Le DSL : ce que l'agent appelle et relit
+
+Les effets passent par les outils de document, comme le reste : `TOOL_ARG_SCHEMAS`,
+`TOOL_DESCRIPTIONS`, `executeAgentTool`. Le serveur MCP les sert sans rien de plus, et l'agent
+intégré les reçoit par le même tableau.
+
+### E.1 Les outils
+
+| Outil | Arguments | Effet |
+|---|---|---|
+| `addEffect` | `startSec`, `endSec` (secondes de règle), `effect` **ou** `effectId`, `values?`, `target?`, `lane?` | Pose une région. Avec `effect` (`name`, `description`, `code`, `params?`), crée d'abord la définition. Avec `effectId`, réutilise une définition du projet. |
+| `setEffect` | `effectRegionId`, `startSec?`, `endSec?`, `values?`, `target?`, `lane?` | Change une région. Seuls les champs passés changent. |
+| `setEffectDefinition` | `effectId`, `name?`, `description?`, `code?`, `params?` | Change une définition, donc toutes les régions qui l'utilisent. Un code neuf est compilé avant d'être accepté. Les `values` d'un paramètre retiré tombent, un paramètre nouveau prend son `default`. |
+| `getEffect` | `effectId` | Lecture : la définition entière, code compris. |
+| `removeModifier` | `id` | Retire une région d'effet, comme un zoom. |
+
+- **Un seul `add`.** Écrire puis poser un effet est le cas courant : un appel, pas deux.
+ `effectId` sert à réutiliser.
+- **Pas de `removeEffect`.** La définition part avec sa dernière région (B.2).
+- **Les noms suivent le DSL :** `add*`, puis `set*` qui ne touche que les champs passés, puis
+ `removeModifier` pour retirer. Pas de neutralisation (force à 0, durée nulle) à la place d'un
+ retrait.
+- **Le placement suit les autres régions :** `anchorForAgent` / `landingOf`. Le modèle est
+ `addCameraFullscreen`. Une étendue qui ne couvre aucun clip est refusée (`coversNoClip`), et
+ une région qui en heurterait une autre de la même lane aussi (`refuseIfBlocked`).
+
+### E.2 Ce que l'agent relit
+
+`getCurrentDocument` ajoute deux listes, sans le code, qui coûterait cher en tokens à chaque
+lecture :
+
+```json
+"effects": [
+ { "id": "fxr_…", "effectId": "fx_…", "name": "Ripple au clic",
+ "startSec": 0, "endSec": 6, "target": "image", "lane": 0, "values": { "strength": 1 } }
+],
+"effectDefinitions": [
+ { "effectId": "fx_…", "name": "Ripple au clic",
+ "description": "Une onde part de chaque clic et réfracte l'image.",
+ "contract": 1, "lines": 22, "regions": 1, "compiles": true,
+ "cost": { "tier": "light", "frameReads": 4 },
+ "params": [ { "name": "strength", "type": "number", "label": "Force",
+ "default": 1, "min": 0, "max": 2 } ] }
+]
+```
+
+- **Les pilules sont coalescées** comme les autres régions (`coalesceForAgent`) : un id par
+ pilule, celui de son premier fragment.
+- **Le code se lit par `getEffect`,** quand l'agent veut le modifier.
+- **`description` est écrite par l'agent** et lue par l'agent suivant. La description de l'outil
+ l'exige : ce que l'effet fait, en une phrase, pas comment il le fait.
+- **`compiles`** dit si le code compile sur cette machine. `null` signifie « pas vérifié ici ».
+- **`timeBaseNote`** nomme les effets parmi les régions en secondes de règle.
+
+### E.3 Les retours
+
+- **Accepté :** l'id, l'étendue posée (`landingReport`, comme les autres régions : fragments,
+ bornes rognées), et le coût : le palier de l'effet, le palier cumulé du moment le plus chargé,
+ et la recommandation du palier quand la région la dépasse. Par exemple : « lourd sur 45 s :
+ pour une région longue, vise moyen ».
+- **Refusé à la compilation :** l'enveloppe `{ error }`, avec l'erreur de naga ou du compilateur
+ du backend, lignes et colonnes de SON code. Le document ne change pas.
+- **Refusé pour une boucle sans borne littérale,** ou au-delà du plafond de sécurité de C.4,
+ avec la ligne de la boucle. C'est le seul refus qui ne vient pas du compilateur.
+- **Sans validateur branché** (un harnais de test), le code est stocké et `validated: false` le
+ dit.
+
+### E.4 Voir le résultat sans exporter
+
+Aujourd'hui `getFrames` (`media-tools.ts`) ne montre que le dernier export : vérifier un effet
+coûte un export complet. Sur un projet de dix minutes, la boucle de l'agent devient trop lente.
+
+**`getFrames` rend désormais depuis le document quand l'export manque ou est périmé.**
+- Il passe par le même compositeur, la même scène et les mêmes secondes de règle, et rend les
+ frames demandées à la taille d'export.
+- C'est le chemin que le spike a utilisé pour comparer la vue live à l'export : une vue sans
+ fenêtre, `setScene`, `presentTime`, `readFrame`.
+- Avec un export à jour, l'outil garde son comportement actuel.
+
+### E.5 Ce que l'agent lit avant d'écrire
+
+- **`TOOL_DESCRIPTIONS.addEffect`** porte le contrat court : la signature, les entrées de C.2,
+ les règles de C.4, les paliers de C.7 en ms, les trois cibles et le défaut `image`, l'exigence
+ d'un paramètre visible, et la vérification avec `getFrames`.
+- **La ressource MCP `openscreen://effects/contract`** porte le contrat complet et deux
+ exemples : le ripple au clic et une vignette qui respire.
+ - **Ce serait la première ressource du serveur,** qui n'en a aucune aujourd'hui.
+ - **Pourquoi une ressource :** le contrat est trop long pour une description d'outil, et il
+ évolue avec `contract`.
+- **Le prompt de base** (`BASE_SYSTEM_PROMPT`) gagne deux choses :
+ - une ligne dans la carte des intentions : un effet visuel que les réglages n'offrent pas se
+ fait avec `addEffect` ;
+ - les effets dans la ligne des bases de temps.
+- **Le skill `openscreen-demo`** gagne une entrée « effets » à son étape 6.
+
+### E.6 L'agent intégré
+
+Il a les mêmes outils, mais pas le validateur : `ChatRunEnv` ne le transmet pas. Il manque
+quatre ajouts d'une ligne, sur le modèle de `cameraSegmentation` :
+- le champ dans `ChatRunEnv` ;
+- son passage dans `chat-service.ts` ;
+- le champ dans `InvokeArgs`, et son passage à `buildTools` ;
+- `validateShaderEffect: (code) => loudnessService.validateShaderEffect(code)` dans
+ `handlers.ts`, à côté de `cameraSegmentation`.
+
+### E.7 Le banc (workbench)
+
+Deux scénarios, sur une mire avec une piste curseur :
+
+- **« ripple au clic ».** DSL attendu : une lecture du curseur, puis un `addEffect` qui couvre
+ les clics. Comportement attendu : l'effet compile et le DSL le relit.
+- **« corrige l'effet ».** Le document porte un effet qui ne compile plus. Attendu : `getEffect`,
+ puis un `setEffectDefinition` qui compile.
+
+`documentInvariants` valide les deux nouvelles listes : chaque région pointe une définition
+existante, et ses `values` sont dans les bornes. Le harnais passe un validateur factice à
+`runChat`.
+
+---
+
+## F. L'interface
+
+### F.1 Une piste « Effets » dans la timeline
+
+- **Où.** Une rangée par lane utilisée, plus une rangée vide pour en ouvrir une nouvelle. Elles se placent sous la piste Full Camera, dans l'ordre des lanes de `V4Timeline.tsx`.
+- **La pilule** porte le nom de la définition. La glisser, l'étirer, la sélectionner et la
+ supprimer se font comme pour un zoom (`selectPill`, `startPillDrag`, `removeRegions`).
+- **L'annulation** passe par l'historique habituel (`saveDocument({ history: true })`). Une
+ édition d'agent reste un seul pas d'annulation par tour (`agentDocumentApply.ts`).
+- **Pas de bouton « ajouter un effet » en v1.** Un effet naît d'un agent : le chat intégré ou un
+ client MCP. Un bouton qui ouvrirait un panneau vide n'aurait rien à proposer. La bibliothèque
+ d'effets (J) lui donnera un contenu.
+- **Le copier-coller** (`regionClipboard`) copie la région avec sa définition. Collée dans un
+ autre projet, la définition y est recréée.
+- **Le site** (`website/scripts/gen-recreation.mjs`) recopie `LANE_ORDER` à la main. La nouvelle
+ piste n'y casse rien, et la recréation ne la montrera pas tant qu'on ne l'y ajoute pas.
+
+### F.2 L'inspecteur
+
+`SelectionPane` (`FloatingInspector.tsx`) gagne une branche `shaderEffect`. Elle contient, dans
+l'ordre :
+
+- **le nom de l'effet,** sans phrase d'explication sous les contrôles ;
+- **un contrôle par paramètre déclaré,** généré depuis `params` (curseur, interrupteur, couleur
+ ou point), qui écrit `values` sur la région ;
+- **la cible :** « Image », « Textes » ou « Les deux » (`target`) ;
+- **le palier de coût,** en un mot (léger, moyen, lourd, très lourd), sans phrase ;
+- **le code,** replié par défaut, en lecture seule, avec un bouton copier ; l'édition du code
+ passe par l'agent en v1 ;
+- **supprimer,** comme pour les autres régions.
+
+**Un effet qui ne compile pas** affiche l'erreur du compilateur dans l'inspecteur. C'est
+l'exception admise aux phrases sous les réglages : sans elle, la pilule existerait sans rien
+faire, et ce serait une vraie surprise.
+
+### F.3 Textes de l'interface
+
+Les libellés fixes vont dans `timeline.json` (`labels.shaderEffect`) et dans `editor.json`
+(`inspector.effectCode`, `inspector.effectLayer`…), pour les 15 locales.
+`localeParity.test.ts` et `npm run i18n:check` vérifient leur parité. Les noms et libellés
+écrits par l'agent n'y passent pas.
+
+---
+
+## G. SSOT, déterminisme, sécurité
+
+### G.1 Ce qui garantit preview = export
+
+- **Un seul chemin de pixels.** La preview et l'export appellent le même `compose_frame`, avec la
+ même scène : `buildSceneDescription` sert aux deux.
+- **Une seule horloge.** `ctx.time` est le temps programme, et `ctx.region` vient de l'étendue
+ de la pilule en temps programme. Aucun des deux ne lit le compteur de frames.
+- **Un effet pur.** C'est le contrat C.4. La validation fait respecter ce qui se vérifie
+ statiquement (boucles, taille), et la description de l'outil donne le reste à l'agent comme
+ règle d'écriture.
+- **Jamais de placeholder à l'export.** Le mode bloquant est le défaut du compositeur.
+- **À résolution égale.** La preview rend plus petit que l'export. Un effet qui suit C.4 donne la
+ même image, mais pas les mêmes pixels, puisqu'il n'y en a pas le même nombre. C'est déjà vrai
+ de tout le reste du rendu.
+
+**Mesure du spike.** Écart entre la frame de la vue live et celle du MP4 exporté, décodé en
+BT.709 : 2,2 à 2,6 / 255, dans la région d'effet comme hors d'elle. C'est le bruit du codec.
+
+### G.2 Un GPU qui ne répond plus
+
+Le seul vrai risque d'un code écrit par un agent est une boucle qui ne finit pas. Le TDR de
+Windows réinitialise alors le GPU, et l'app perd son device. Rien ne gère ce cas dans le dépôt :
+le thread de rendu s'arrête sur son erreur (`fatal`, `live.rs`) et ne redémarre pas.
+
+La protection est statique, posée à la validation : la borne littérale de toute boucle et le
+plafond de 4 096 itérations par pixel (C.4). Ce n'est pas un budget de coût, qui n'existe qu'en
+paliers indicatifs (C.7). Récupérer un device perdu est un chantier à part : il concerne toute
+l'app, pas les effets.
+
+### G.3 Un projet partagé
+
+Un projet porte le code de ses effets. Ouvrir le projet de quelqu'un d'autre compile donc du code
+qu'on n'a pas écrit.
+- **Ce code ne tourne que sur le GPU,** sans accès aux fichiers, au réseau ni à la mémoire du
+ processus.
+- **Les garde-fous de G.2 s'appliquent aussi à l'ouverture.** Un effet refusé reste dans le
+ document, et sa région ne se dessine pas.
+
+---
+
+## H. Performance
+
+### H.1 Pas de budget ferme
+
+- **Une région inactive ne coûte rien.** La passe n'existe que si une région couvre la frame.
+- **Le coût d'un effet se lit en paliers** (C.7), estimés depuis le code et identiques sur toutes
+ les machines. L'agent les connaît et suit leurs recommandations ; rien n'est refusé au coût.
+- **Une cible `text`** ajoute un calque transparent et sa composition, seulement aux frames
+ qu'elle couvre.
+
+### H.2 Mesuré par le spike (RTX 4070 Ti, D3D11)
+
+| Mesure | Résultat |
+|---|---|
+| Compilation (naga + FXC) d'un effet de 60 lignes | 10 ms, sur un thread de fond |
+| Passe d'un effet lourd, 1080p | +0,04 ms par frame |
+| Passe d'un effet lourd, 4K | +0,12 ms par frame |
+| Export de 180 frames en 1752×1080 : sans effet, avec effet, avec effet lourd | 520, 523 et 521 ms |
+| Preview en lecture, source à 30 i/s | 30 i/s avec et sans effet |
+
+À mesurer à l'implémentation :
+- un GPU intégré (le Radeon 610M des mesures Linux) ;
+- le compilateur Metal ;
+- lavapipe en CI.
+
+Les résultats iront dans
+[rendering-performance.md](../technical-documentation/engineering/rendering-performance.md).
+
+---
+
+## I. Les tests
+
+| Niveau | Ce qu'il couvre |
+|---|---|
+| Rust, `shader_fx.rs` | Prélude et struct générée ; packer de paramètres contre les offsets de naga ; borne littérale et plafond d'itérations ; estimation du coût et paliers (boucles imbriquées, fonctions dépliées) ; erreurs aux lignes de l'agent ; sélection des régions (lane, ordre, `underTrim`) ; `ctx.region` sur une pilule coupée. |
+| Rust, par backend | Une passe repeint la frame dans sa région et nulle part ailleurs ; les trois cibles (`text` laisse l'image intacte, `image` laisse les textes intacts) ; preview non bloquante puis `shader_fx_landed` ; effet cassé = frame intacte. Windows (fait dans le spike), macOS sur le runner CI, Linux sur lavapipe. |
+| Rust, `frame_geometry.rs` | `ctx.clicks`, `ctx.footage`, `ctx.camera` en uv de sortie, sous zoom et sous tilt. |
+| TS, schéma | Parse, bornes des `values`, définition orpheline retirée, document ancien inchangé. |
+| TS, timeline | La région suit `moveClip`, `removeClip`, `replaceTimeline` et les trims (`timelineMap.test.ts`, `timeline.test.ts`). |
+| TS, outils | `addEffect` avec `effect` puis avec `effectId` ; `setEffect` ; `setEffectDefinition` ; `getEffect` ; `removeModifier` ; les refus (compilation, boucle sans borne, chevauchement, aucun clip) ; le palier et sa recommandation dans le retour ; le snapshot. |
+| TS, scène | Projection, `programmeStart/EndSec` d'une pilule coupée, normalisation des `values`. |
+| Banc | Les deux scénarios de E.7. |
+| Bout en bout | La boucle du spike par la CLI `mcp` : prompt, `addEffect`, `getFrames`, puis comparaison de la vue live avec l'export. Une ligne dans le [journal e2e](../technical-documentation/testing/manual-e2e-checklist.md). |
+
+---
+
+## J. Hors de la v1
+
+- **Effets par calque** (l'écran seul, la webcam seule). La passe agit sur l'image composée.
+- **Effets temporels** (traînées, persistance). Ils prendraient les frames précédentes comme
+ entrées explicites, jamais un état gardé ; ce n'est pas fait.
+- **Transitions entre deux clips.** Elles demandent deux images en entrée.
+- **L'édition du code dans l'interface.** En v1, le code se lit, se copie, et s'écrit par
+ l'agent.
+- **La bibliothèque d'effets** partagée entre projets, avec un bouton « ajouter » qui la propose.
+- **Une poignée sur la preview** pour les paramètres `point`.
+- **Le cache disque** des binaires compilés.
+- **La récupération d'un device GPU perdu,** un chantier qui concerne toute l'app.
+
+---
+
+## K. Décisions (14/10/2026)
+
+1. **Champs additifs, sans montée de `schemaVersion`.** Comme `audioTracks`. Une build antérieure
+ qui sauvegarde le projet perd ses effets : c'est accepté.
+2. **Pas de budget ferme, des paliers indicatifs** (C.7). Ils sont estimés depuis le code, donc
+ indépendants de la machine. L'agent les connaît, avec leurs recommandations. Un budget lié à
+ la machine aurait refusé des effets haut de gamme sur une machine modeste, alors que l'export,
+ lui, les rend très bien.
+3. **Pas de limites fermes non plus.** Paramètres, code et lanes ont des recommandations, et des
+ plafonds techniques loin au-dessus (B.2). Seule reste ferme la borne littérale des boucles,
+ avec son plafond de 4 096 itérations par pixel : une protection contre le blocage du GPU, pas
+ une limite de créativité.
+4. **Pas de bouton « ajouter un effet » en v1.** Les effets naissent des agents.
+5. **Trois cibles : `image`, `text`, `both`.** Sans demande explicite, l'effet vise `image`, sous
+ les textes.
+
+## L. Découpage en PR
+
+Le spike n'est pas fusionné tel quel : les PR 1 et 2 reprennent son code, et il est stocké
+ailleurs (`legacyEditor`, sans ancre).
+
+1. **Contrat v1 et passe Windows (Rust).**
+ - `shader_fx.rs` : struct `FxParams` générée et packer ; `ctx.region`, `ctx.clicks`,
+ `ctx.footage`, `ctx.camera`, `fx_px`, `fx_hash` ; borne littérale des boucles et plafond
+ d'itérations ; estimation du coût et paliers, calibrés en ms sur le GPU intégré de
+ référence.
+ - `validate_shader_effect` compile pour le backend et rend le palier.
+ - `scene.rs` lit la nouvelle forme ; la passe Windows gère les trois cibles (calque de textes
+ à part pour `text`), `lane` et l'éviction LRU.
+2. **Modèle de données et DSL (TS).**
+ - Schéma (B.2) et `RegionKind` dans tout le pipeline (B.3) ;
+ - outils (E.1), snapshot (E.2), projection de scène (B.5) ;
+ - validateur branché sur l'agent intégré (E.6) ;
+ - descriptions, prompt de base, ressource MCP du contrat, skill, `openscreen info`, banc.
+3. **Passe macOS.** naga `msl-out`, samplers inline, bindings explicites, thread de fond, tests
+ sur le runner CI.
+4. **Passe Linux.** WGSL direct, bind group layout explicite, thread de fond, test lavapipe.
+5. **`getFrames` depuis le document.** Rendu de frames sans export quand celui-ci manque ou est
+ périmé (E.4).
+6. **Interface.** Piste et lanes, inspecteur, copier-coller, i18n.
+
+La PR 2 dépend de la 1. Les PR 3, 4 et 5 dépendent de la 1 et peuvent avancer en parallèle. La
+PR 6 dépend de la 2.
+
+Chaque PR met à jour la documentation qu'elle rend fausse, dans le même changement :
+- `native-compositor.md` ;
+- `document-model.md` et `timeline-model.md` ;
+- `editor-shell.md`, dont la checklist « Adding a region kind » a ses numéros de ligne à
+ rafraîchir ;
+- `ai-agent.md`, dont le tableau d'outils annonce encore « 26 tools » ;
+- `mcp-server.md` ;
+- une ligne de [decisions.md](../technical-documentation/architecture/decisions.md) : WGSL et
+ naga 24, compilation hors du rendu, effet pur ;
+- et, à la PR 6, une page de `website/docs/`.