ADR-0019 — Le contexte visuel du produit est une entrée canonique de Studio

Statut

Accepté · 2026-09-30

Origine : ADR 0009 du dépôt applicatif Orbit, renumérotée 0019 à l’intégration dans cette série (une seule série d’ADR vit désormais ici).

Statut dans Orbit (2026-10) : en vigueur. Le Brain canonique est la surface /brain d'Orbit (ses primitives dédiées, ADR 0020) ; la frontière neutre décrite ici reste la règle.

Contexte

Le Studio possède encore une implémentation Brain legacy capable de lire ce qu'un produit dit, mais cette implémentation est transitoire : le Brain canonique sera reconstruit de zéro dans BoostEcom/orbit.easyconnector.app. Cinema et Remotion savent déjà filmer une scène, préserver une horloge exacte, produire plusieurs formats et livrer les artefacts par le moteur existant.

Il manque une couche entre les deux : une représentation compacte de ce que le produit montre réellement dans son interface rendue. Sans elle, une composition doit soit connaître le produit à la main, soit réinventer une UI, soit envoyer une page entière à un modèle.

Deux références étudiées par le fondateur ont montré des motifs utiles :

1. OneMinute-Studio : page rendue → structure visuelle compacte → sélection de scènes → captures ciblées, plutôt que DOM brut ou reconstruction complète ;
2. Motion Reel Kit : rendu comme fonction déterministe du temps, une timeline commune à l'image et au son, retargeting de springs sans restart, et review faite sur le MP4 final plutôt que sur le code.

Aucun de ces projets n'entre comme dépendance. Leur code n'est pas vendored et aucun provider, stockage ou worker externe n'est adopté.

Décision

Orbit ajoute un domaine Product Visual Context dans @orbit/engine :

Brain (ce que le produit est / dit)
        +
Visual IR (ce que le produit montre)
        ↓
Deterministic Scene Planner
        ↓
Product Film Timeline
        ↓
Cinema
        ↓
Remotion
        ↓
Rendered asset
        ↓
Motion QC → Studio QC / Relecture → Learning

1. Visual IR

Le navigateur produit d'abord un RawVisualSnapshot. Le cœur pur le réduit à un VisualIR versionné : sections, titres, texte utile, assets, actions, surfaces et bounding boxes. Il ne conserve ni DOM brut, ni script, ni feuille de style, ni donnée d'horloge. Deux snapshots identiques donnent le même IR.

Le futur Brain Orbit et le Visual IR ne fusionnent pas leurs responsabilités :

• Brain Orbit = sens, marque, consignes, provenance, mémoire ;
• Visual IR = géométrie et preuves visuelles du produit rendu.

ADR 0019 n'impose aucun contrat d'implémentation au Brain. Le domaine Visual Context n'importe aucun module packages/engine/src/brain/**, aucun BrainEntry et aucun schéma de stockage Brain. Une future intégration recevra uniquement du contexte sémantique à travers une frontière neutre définie côté Orbit.

2. Planning avant IA

Le premier ScenePlanner est déterministe. Hero, produit, preuves, sections riches et closing sont choisis à partir des éléments réellement observés. Un modèle pourra enrichir plus tard un plan, mais un film valide ne dépend pas de lui.

3. Pixels réels d'abord

Une UI existante est capturée et filmée, pas redessinée. La capture pourra produire plusieurs couches (original, plate sans texte, surfaces/layers) afin d'animer une région sans régénérer ses libellés. Une amélioration générative reste une capability optionnelle du moteur existant ; elle n'est jamais une condition du film.

4. Une horloge canonique

Le plan produit une timeline versionnée. Scènes, marks, événements visuels et futurs cues audio nomment la même horloge. Les médias génératifs, la musique et la voix restent facultatifs.

5. Motion déterministe

Cinema reste le moteur spatial canonique et Remotion reste le compositeur. Une nouvelle primitive de spring fermée peut compléter les keyframes pour les retargets fréquents, sans créer une troisième runtime vidéo. À un instant donné, le résultat est indépendant des frames rendues auparavant.

6. Review sur l'artefact

Le contrôle motion travaille sur le MP4 réellement rendu : contact sheet, phone preview, safe zones, seam de boucle, frames quasi vides et pacing. Les findings doivent ensuite rejoindre le QC Studio au lieu de créer un second système de verdicts.

Sécurité du navigateur

safeFetch reste le garde des lectures HTTP du moteur, mais ne suffit pas pour Chromium : une page charge des sous-ressources et peut tenter des WebSockets ou redirections. L'adaptateur de capture doit donc :

• n'accepter que HTTPS pour une cible distante ;
• refuser userinfo et ports arbitraires ;
• résoudre les destinations avant connexion et refuser loopback, réseaux privés, link-local et metadata ;
• épingler la connexion sur l'adresse résolue afin qu'un DNS rebinding ne fasse pas une seconde résolution dans Chromium ;
• bloquer WebSockets, downloads et service workers ;
• imposer des plafonds de temps et de contenu ;
• garder un mode loopback explicite uniquement pour les fixtures E2E.

Économie et connecteurs

Cette décision n'ajoute :

• aucun provider ;
• aucun secret ;
• aucune table de crédit ;
• aucun stockage ;
• aucun système de job ;
• aucun chemin BYOK parallèle.

Si un film appelle un jour une capability générative, le moteur, le ledger et les connecteurs existants décident comment elle est satisfaite et facturée. Un film déterministe Cinema + Remotion fonctionne sans elle.

Non-objectifs de cette tranche

• remplacer @orbit/cinema ;
• remplacer Remotion ou son verrou H.264/BT.709 ;
• importer Fish Audio, Higgsfield, R2 ou un worker tiers ;
• construire un DAW, une bibliothèque de musique ou un moteur de SFX ;
• rendre un LLM obligatoire pour choisir les scènes ;
• copier les constantes de safe zone d'une référence : canvas.ts reste la source Orbit par format ;
• créer un nouveau board de review distinct du QC Studio.

Critères de sortie

• même snapshot → même Visual IR ;
• même Visual IR → même plan et même timeline ;
• aucun provider ni secret sur ce chemin ;
• première frame lisible et formats re-bloqués, pas letterboxés ;
• capture distante impossible vers une adresse privée ;
• review issue du MP4, pas du JSX ;
• le verrou d'encodage existant reste inchangé.