ADR-0046 — Les frames du Builder rendent la page de la Preview en mode editeur; Preview et Worktree restent des modes
L'ADR 0032 a ecarte « Frame = URL de preview » parce que « la Preview ne vit pas dans le canvas ». Le code a fait ce choix quand meme. Une frame de template demande builder-frame, qui repond par une redirection 307 vers…
Statut
Accepté · 2026-09-27
Remplace : ADR-0032 (partiellement : l'alternative ecartee « Frame = URL de preview »)
Piliers : ai-platform
Contexte
L'ADR 0032 a ecarte « Frame = URL de preview » parce que « la Preview ne
vit pas dans le canvas ». Le code a fait ce choix quand meme. Une frame de
template demande builder-frame, qui repond par une redirection 307 vers
le proxy de la Preview avec editor=1, le fichier du template et
preview_theme_id (builder-frame/route.ts, previewEditorPath dans
shopify-document.ts). Le backlog le disait deja : c'est le meme HTML
que la Preview (backlog/ai-platform/2955-onlook-builder.md).
Demande, le 2026-09-27, si le Worktree devait vivre dans la Preview ou dans le Builder, et si la Preview devait rejoindre les deux. Une revue du code a montre trois faits :
- la Preview est la seule scene storefront (Live, navigation, panier, viewports, capture) ;
- le Builder refuse le theme MAIN et avale les clics sur les elements edites ;
- le Worktree ne s'ouvrait que depuis la toolbar de la Preview, ou depuis « voir le code » sur une selection du Builder.
Décision
Une frame de template du Builder rend la page du proxy Preview en mode editeur, pour le theme choisi dans la Preview. La Preview reste un mode a part, et le Builder ne la remplace pas. Le Worktree reste un mode, sans etape dans le stepper, avec deux portes : la toolbar de la Preview (contre le selecteur de theme) et la barre flottante du Builder. Son bouton de retour ramene au mode d'ou l'operateur vient.
Alternatives écartées
| Option | Pourquoi non |
|---|---|
| Fusionner la Preview dans le Builder (un toggle « Apercu ») | Le Builder n'a ni Live, ni navigation, ni panier, ni capture, et il refuse le theme live : la Preview y perdrait tout ce qui la justifie |
| Faire du Worktree une etape du stepper | Le choix « quelle version » (selecteur de theme) et l'action « editer ses fichiers » seraient separes a nouveau (app-shell/2785) |
| Rendre la frame depuis un document a nous, sans le proxy | Deux rendus du meme theme a tenir alignes, pour afficher la meme page |
Conséquences
- Un defaut du proxy Preview (CSP, redirection, mot de passe) se voit aussi dans le Builder. C'est voulu : une seule page a corriger.
- Le Builder, le Worktree et @Atlas ecrivent le meme theme. Le Worktree relit ses fichiers propres a chaque retour, et une sauvegarde dans le Worktree recharge la Preview.
- L'historique d'annulation n'est pas partage entre le Builder (Onlook) et le Worktree (CodeMirror). Chacun annule ses propres gestes.
Comment c'est appliqué
previewEditorPath(src/features/ai/onlook/shopify-document.ts) et la redirection desrc/app/api/stores/[storeId]/builder-frame/route.ts- La porte du Builder :
openWorktreedanssrc/features/ai/onlook/chrome/builder-toolbar.tsx - Le retour :
worktreeReturndanssrc/features/ai/preview/store-browser/store-browser.tsx - Gardes :
src/test/builder-is-onlook-canvas.test.ts,src/test/builder-code-opens-the-worktree.test.ts,src/test/the-worktree-follows-the-builder.test.ts