Product Visual Context et Product Film

Cette page décrit la couche ajoutée par l'ADR 0019. Elle est indépendante de l'implémentation Brain legacy du Studio et complète la chaîne Cinema/Remotion. Le Brain d'Orbit (/brain, ses Spaces et leurs Memories, ADR 0020) pourra fournir du contexte sémantique sans devenir une dépendance du Visual IR.

1. Le contrat

public product page
      │
      ▼
Browser capture adapter
      │ RawVisualSnapshot
      ▼
@orbit/engine/visual
      │ VisualIR
      ├──────────────► optional semantic context (future Orbit Brain boundary)
      │
      ▼
createScenePlan()
      │ ProductFilmPlan
      ▼
timelineFromPlan()
      │ ProductFilmTimeline
      ▼
Cinema scene/camera/focus
      ▼
Remotion composition
      ▼
MP4 / stills
      ▼
Motion QC
      ▼
Studio QC / Relecture / Learning

Le cœur @orbit/engine/visual est pur et ne sait rien de Playwright, Remotion, des providers, du ledger ou de Blob.

2. RawVisualSnapshot

L'adaptateur navigateur ne renvoie pas le DOM. Il mesure :

• URL et viewport ;
• sections visibles avec selector stable, rôle, box, heading et texte utile ;
• assets visuels avec source et box ;
• actions avec label/href et box ;
• surfaces peintes utiles au focus/cadrage.

Le snapshot est une frontière de données. Les scripts, cookies, listeners, classes arbitraires et feuilles CSS restent dans le navigateur.

3. VisualIR

buildVisualIR() nettoie et stabilise le snapshot :

• ids dérivés du contenu, jamais UUID ;
• déduplication d'un même asset/action ;
• texte plafonné et espaces normalisés ;
• ordre des sections par géométrie ;
• aucune date de capture, donc aucune dérive d'un run à l'autre.

Une version incompatible crée VisualIR.version = 2, jamais un changement silencieux du sens de v1.

4. Planner

createScenePlan() doit rester explicable. La v1 choisit :

1. hero ;
2. plus grand asset produit s'il apporte une scène distincte ;
3. sections riches, avec une scène proof lorsqu'un fait chiffré est visible ;
4. closing avec action lorsque possible.

Le plan est plafonné en scènes et en durée. Le futur Brain Orbit pourra ajouter une passe sémantique par une frontière neutre, par exemple privilégier une feature stratégique ou refuser une promesse contraire aux Guidelines. Cette passe ne modifie pas la preuve visuelle elle-même et ne demande pas de conserver l'ancienne implémentation Brain du Studio.

5. Timeline

ProductFilmTimeline est l'horloge commune :

• FPS et formats ;
• marks de début/fin de scène ;
• événements visuels (hook, scene-enter, subject-land, cta) ;
• futurs cues audio qui référencent ces marks ;
• tempo optionnel, jamais requis.

Une future piste audio se synchronise donc sur les mêmes marks que l'image au lieu d'entretenir un second fichier de timing.

6. Capture sécurisée

La capture distante passe par un proxy local qui résout le host avant connexion, refuse toute adresse non publique et ouvre le tunnel vers l'IP résolue. Chromium ne fait donc pas une nouvelle résolution DNS au moment de la connexion. Le contexte bloque WebSockets, service workers et downloads.

Le mode loopback est réservé aux fixtures locales et n'est jamais inféré à partir d'une URL distante.

7. Motion

Deux familles restent complémentaires :

• keyframes/rails de @orbit/cinema pour caméra, focus et trajectoires continues ;
• springs fermés pour cartes, indicateurs et retargets qui changent plusieurs fois de cible.

Une primitive de spring est pure : pas de requestAnimationFrame, pas d'état caché, pas de restart lors d'un retarget. Une frame peut être calculée seule.

8. Formats

packages/remotion/src/canvas.ts reste la source des profils de canvas et des safe zones. Le Product Film doit re-bloquer la composition pour 16:9, 9:16, 1:1 et 4:5 ; un crop/letterbox n'est pas considéré comme un layout.

9. Motion QC

Le QC automatique ne donne pas un verdict artistique. Il produit des preuves reproductibles :

• contact sheet ;
• phone strip à 360 px ;
• overlay safe-zone vertical ;
• seam première/dernière frame ;
• scan de frames quasi uniformes ;
• gaps entre événements visuels ;
• métadonnées codec/couleur lorsque ffprobe est disponible.

Les seuils déterministes peuvent bloquer une approbation future. Le jugement humain reste dans Studio QC/Relecture.

10. Vertical slice et suite

La tranche 31 prouve le cœur, la capture sécurisée, les springs et le QC sur fixtures. Les étapes suivantes branchent ce contrat sur une surface Cinema de Studio, puis sur StudioAsset/QC, sans déplacer les responsabilités du moteur, du ledger ou des connecteurs.