Contrat serveur du cockpit (StudioHost)

Statut (migration Orbit, 2026-10). Contrat d'ingénierie de Creative Studio dans Orbit (BoostEcom/orbit.easyconnector.app). Le cockpit est déjà transplanté dans ce dépôt (apps/web/src/components/studio/**, branché par apps/web/src/cockpit/produce.ts) ; la colonne « Cockpit d'origine » nomme l'API du cockpit de l'ancienne plateforme, que l'adaptateur imite, pas un service dont Orbit dépend. Les lignes « pont B1 » désignent une capture par l'ancienne plateforme, retirée dans Orbit (aucune plateforme parente) ; les gardes de ce document (section « Les gardes ») acceptent encore ce libellé pour une ligne sans export. La Fabrique (production par lots) est retirée ; le rendu de gabarit reste servi par la Composition (mode Motion).

Pour qui : quiconque touche l'adaptateur du cockpit Creative Studio (apps/web/src/components/studio/**, transplanté par l'ancien chantier studio/06-design-plateforme). Ce document dit, appel par appel, quelle fonction ou quelle route du studio remplace chaque appel du cockpit d'origine, comment passer les entrées et lire les résultats. Constat de l'audit de la phase 3 : G1-27. La v1 est du lot 4 ; la table est close depuis le lot 10 : chaque ligne nomme une fonction serveur exportée ou une route servie, ou dit en toutes lettres « phase 4 » ou « pont B1 », et une garde le vérifie (section « La garde », en fin de document). Source côté plateforme : src/components/studio/actions.ts et types.ts au commit 8df697416.

La règle : les mutations sont des actions, les lectures sont des routes GET

Next exécute les fonctions serveur une à une, en POST, sans cache, et sa documentation déconseille d'y lire des données. Un cockpit qui interroge une vidéo en cours par une action attendrait derrière chaque autre action de la page. Donc (G2-07) :

• Mutations : les fonctions serveur de apps/web/src/generation/actions.ts, et elles seules : generateImage, editImage, composeProductImage, generateVideo, generateVoiceover, generateLipsync, packLoopGif, generatePicto, generateAvatar, renderTemplate, deleteRender, uploadReference, confirmReferenceUpload, saveAvatar, deleteAvatar, purgeProductBlobs. actions-are-mutations.test.ts refuse toute autre exportation, et tout nom de lecture (get…, list…, load…).
• Lectures : cinq routes GET, chacune derrière requireMemberApi (session relue en base, 401 sans session, 403 sans permission), réponses cache-control: no-store :

La page qui lie les actions exporte maxDuration = 300 : une fonction serveur tourne sous la limite de sa page, et une génération peut durer jusqu'à la limite de la fonction (STUDIO_FUNCTION_MAX_DURATION_S, G2-08). max-duration.test.ts l'exigera dès qu'une page importe @/generation/actions.

Une vidéo se lit, elle ne s'attend pas

generateVideo et generateLipsync rendent aussitôt (ADR 0014) :

{ "ok": true, "status": "running", "generationId": "g…", "heldUsd": "1.200000",
  "pollUrl": "/api/generations/g…", "url": null, "chargedUsd": null,
  "balance": "8.800000", "notice": "La vidéo est lancée. …" }

L'adaptateur pose une carte GalleryItem en status: "pending" (le mode du compositeur, le prompt, les réglages), puis lit pollUrl :

• toutes les 5 s pendant la première minute, puis toutes les 15 s ; la route ne demande rien à la Gateway avant 15 s de vie (VIDEO_PULL_AFTER_MS), puis une lecture par appel ;
• generation.status passe à done : url, mediaType et chargedUsd sont remplis ; la carte devient ready avec videoSrc = url ;
• failed : generation.message est la phrase française à afficher (rien n'a été débité) ; la carte est retirée ou marquée en échec ;
• l'adaptateur arrête de lire après 2 h : le balayage aura fermé la ligne (video_timeout, remboursée).

Rien ne dépend de l'onglet ouvert : fermer la page ne perd pas la vidéo. Le webhook de la Gateway ou le balayage la ferment, et la galerie la retrouve par GET /api/generations.

Ce que l'adaptateur fournit à chaque mutation

• idempotencyKey : généré par l'adaptateur une fois par geste (un clic sur « Générer » : crypto.randomUUID()), et renvoyé à l'identique si le même geste est rejoué (double clic, réseau coupé, nouvelle tentative). Le même appel avec la même clé rend replayed: true et n'appelle rien ; la même clé pour une autre demande est refusée (invalid). La plateforme n'avait pas de clé : l'adaptateur la crée, le cockpit n'a rien à changer.
• productId : le studio n'a pas de boutique. Le storeId du cockpit devient l'id d'un produit du registre (GenerationContext.products), ou null pour le mode libre.
• Des ids d'asset, pas des URL. Le cockpit passe des URL (une image comme visage, des images à empaqueter en GIF) ; le studio attend des ids (faceAssetId, voiceAssetId, frameAssetIds) pour ne jamais lire une adresse arbitraire. L'adaptateur traduit l'URL d'une carte en son assetId (chaque RenderRow et chaque résultat portent les deux).

Les correspondances

StudioRenderResult (plateforme) se construit depuis GenerationResult (studio) :

Appel par appel :

Ce qui change pour le cockpit

0. La CSP du studio autorise l'hôte exact de son store Blob dans img-src et media-src, et https://vercel.com/api/blob/ dans connect-src (overview §7.5). Sans elle, le cockpit transplanté ne pourrait ni afficher une image ou un clip stockés, ni téléverser un rush. Une image d'un autre hôte (le CDN d'une boutique) ne s'affiche pas telle quelle : la montrer après l'avoir passée en référence, ou la téléverser.

1. Une vidéo ne rend plus d'URL dans la réponse : lire pollUrl.

2. Chaque résultat donne le solde après l'appel (balance) : le cockpit n'a plus à recharger loadStudioHost pour l'afficher.

3. L'argent est du texte décimal USD ("0.067000"), jamais un nombre flottant côté serveur ; l'adaptateur convertit pour l'affichage (formatSpend).

4. Les refus portent un code stable et la phrase française (message) ; le cockpit affiche message et branche sur code.

Les gardes

Ce contrat est tenu par trois gardes, dont aucune ne dépend d’un autre dépôt cloné à côté pour les tests de l’application :

• Dans ce dépôt (node scripts/audit-docs.mjs) : la structure du tableau « Appel par appel » et de la règle des mutations. Chaque ligne cite une fonction (`nom(`) ou une route (/api/…), ou dit « phase 4 » ou « pont B1 » ; une ligne qui ne cite rien ne s’annonce pas v1 ; la liste en prose des mutations est exactement l’ensemble des fonctions citées ; la table des lectures compte cinq lignes, chacune une route GET.
• Contre le code de l’application (node scripts/audit-orbit-claims.mjs --orbit <clone>, CI orbit-claims) : chaque fonction citée est exportée par apps/web/src/generation/actions.ts, chaque route citée a son route.ts et sert GET quand la ligne la lit en GET, la liste des mutations est exactement celle des exports, et chaque type de résultat nommé ici (GenerationResult, GenerationContext, RenderRow, VoiceDesk, AvatarView, ReferenceView, LipsyncResult) est exporté par apps/web/src/generation/types.ts.
• Dans le dépôt applicatif (Vitest, côté code) : actions-are-mutations.test.ts tient les exports de actions.ts à la liste des mutations et les cinq lectures à GET seul ; studiohost-surface.test.ts tient les types de résultat exportés, les cas vidéo nova et replace exécutés par le serveur, et l’existence de upload de @vercel/blob/client.

Ce que ces gardes ne font pas : exercer chaque appel du cockpit avec ses réponses enregistrées. Ce test-là lit gallery-context.tsx et n’existe qu’une fois le cockpit transplanté (l’autre chantier, phase 4, reporté par le plan).