react-native-skia-webgpu-video 0.0.0-stage → 0.1.0-beta.0

package/docs/UPSTREAM_NOTES.md

@@ -0,0 +1,188 @@
+# Points amont à revoir lors d'une mise à jour Skia
+
+**Migration du 19 octobre 2026 :** le code et les dépendances déclarées ciblent désormais **`react-native-skia@3.7.0` / `react-native-webgpu@0.17.0`**, sur Graphite **157.0.0** et **`react-native-webgpu-dawn@157.0.0`** (Skia `chrome/m157`). Les deux paquets doivent monter ensemble : Gradle et le podspec refusent deux Dawn différents. Le patch local garde 61 de ses 62 éditions ; seule tombe l'include `<stdexcept>`, désormais présent en amont. Le Dawn 157 demande trois images FIFO à la swapchain Android, ce qui supprime l'attente du thread principal dans `dequeueBuffer` sur Android 10 ; il garde aussi la robustesse des shaders sur Android, nos WGSL compris. L'[audit](../migration/skia-3.7.0/upstream-audit.md) détaille ces changements ; la [vérification](../migration/skia-3.7.0/verification.md) donne les mesures sur iPhone 15 Pro et Pixel 8a. Après une mise à jour, supprimer le bundle JS généré par Gradle avant de construire un APK de qualification : sa tâche ne voit pas le `node_modules` racine.
+
+**Migration du 16 octobre 2026 :** le code et les dépendances déclarées ciblaient alors **`react-native-skia@3.6.1` / `react-native-webgpu@0.16.0`**, toujours sur Graphite **154.3.0** et **`react-native-webgpu-dawn@154.3.0`** : les binaires Skia et Dawn ne changent pas. L'[audit](../migration/skia-3.6.1/upstream-audit.md) détaille les changements amont, la régression de couleurs des frames décodées Android introduite par WebGPU 0.15 et sa correction, puis l'import en place à l'export Android. La [vérification](../migration/skia-3.6.1/verification.md) donne les mesures sur iPhone 15 Pro et Pixel 8a. **À chaque mise à jour WebGPU, relancer le contrôle `interop` du Pixel** : il compare les pixels décodés et exportés au chemin CPU, et c'est lui qui a révélé cette régression.
+
+**Migration précédente, 14 octobre 2026 :** le code et les dépendances déclarées ciblent désormais **`react-native-skia@3.4.4` / `react-native-webgpu@0.14.2`**, Graphite **154.3.0** et un Dawn unique, **`react-native-webgpu-dawn@154.3.0`** (tag `chrome-m154a`). L'[audit de migration](../migration/skia-3.4.4/upstream-audit.md) détaille les changements amont, le patch rebasé et la passe d'export iOS ; la [vérification](../migration/skia-3.4.4/verification.md) liste ce qui a réellement été exécuté. Les mesures physiques citées ci-dessous, iPhone comme Android, restent celles du couple **3.0.6 / 0.12.1** : elles ne qualifient pas ces nouveaux binaires.
+
+État précédent, revu le **8 octobre 2026**. Le code et les dépendances déclarées ciblaient alors **`react-native-skia@3.0.6` / `react-native-webgpu@0.12.1`**, Graphite **154.1.0** et Dawn **m154a**. Le code courant passe **196 tests JavaScript dans huit suites et le contrôle TypeScript**. La voie AHardwareBuffer Android a passé **24/24 essais physiques ciblés**, trois répétitions des huit scénarios, avec fermeture suivie à zéro ; **6/6 tests natifs AHB** passent sans skip. Le fallback scoped-copy antérieur avait terminé **8/8 opérations sans OOM**, mais **0/8 fermetures strictes**, après une première campagne CPU à **0/24 réussites strictes**. Les [diagnostics Android](ANDROID_DEVICE_306.md) conservent chaque checkpoint. La [passe iPhone initial/optimisé 3.0.6](PERFORMANCE_IPHONE_306_OPTIMIZATION.md) précède ces changements Android et ne les qualifie pas. Les [mesures iPhone 3.0.3](PERFORMANCE_AB_IPHONE_303.md), l'[endurance iPhone 3.0.3](PERFORMANCE_SOAK_IPHONE_303.md) et les chiffres simulateur conservés plus bas restent des résultats historiques du couple **3.0.3 / 0.11.0**.
+
+La [correction du 8 octobre](NATIVE_MEMORY_INVESTIGATION_306.md) réutilise une seule fonction worklet par export, au lieu de recréer son graphe capturé à chaque image. Elle est intégrée dans `main` par la [PR #4](https://github.com/batical/react-native-skia-webgpu-video/pull/4), sans nouveau patch natif amont. Les mesures Release nominales après deux montages et 60 s au repos passent de 425,99 à 257,70 Mio d’empreinte physique sur iPhone, et de 737,83 à 577,20 Mio de PSS sur Pixel. Six montages iPhone et quatre Android passent ensuite. Lors d’une mise à jour Worklets, conserver le test d’identité de fonction et refaire les mesures : le comportement de sérialisation/rétention fait partie du diagnostic, sans supposer que toute mémoire restante appartient à Skia.
+
+## Interop actuelle et coût de la migration
+
+Skia 3.0.5 a déplacé l'import natif vidéo vers WebGPU ; 3.0.6 conserve les mêmes sources d'API et livre les nouveaux binaires Graphite. Le changement vient de [#4139](https://github.com/wcandillon/react-native-skia/pull/4139), pas d'un renommage suffisant à lui seul.
+
+| API utilisée en 3.0.3 | Contrat en 3.0.6 |
+| --- | --- |
+| `Image.MakeImageFromNativeTexture` | `Image.MakeImageFromGPUTexture`, avec objet GPUTexture ou pointeur WGPUTexture en BigInt |
+| `Surface.MakeFromNativeTexture` | `Surface.MakeFromGPUTexture`, sur le device partagé et avec `RENDER_ATTACHMENT` |
+| `Image.MakeNativeTextureFromImage` | `Image.MakeGPUTextureFromImage` ; référence native à adopter exactement une fois |
+| `Image.MakeImageFromNativeBuffer` | Toujours présente pour le web, mais lève une erreur en natif ; notre adaptateur emploie désormais le wrapper NativeVideoFrame de WebGPU |
+| `Skia.NativeBuffer` | Supprimée ; ne pas restaurer cette API dans notre patch |
+
+Sur iOS, [frameInterop.ts](../src/frameInterop.ts) conserve notre CVPixelBuffer et le fait retenir aussi par un `NativeVideoFrame`. WebGPU copie les pixels dans **une texture réutilisable par runtime**, puis Skia crée directement un snapshot possédé depuis une surface enveloppant cette texture. La fin de la queue partagée précède la libération des deux leases, la fermeture des wrappers de surface/canvas et la réutilisation de l'intermédiaire. Il n'y a plus de surface de staging distincte ni de `drawImage` plein cadre entre l'import et le snapshot.
+
+La surface Skia est **un wrapper neuf par frame**, sans nouvelle texture associée : les écritures externes WebGPU n'invalident pas son cache de snapshot. Réutiliser ce wrapper pourrait rendre l'image précédente. Le snapshot Graphite reste une copie indépendante, et `COPY_SRC` ajouté à la texture permet sa copie GPU directe. La fermeture explicite des wrappers conserve uniquement la texture réutilisable et les images publiées. Les tests modélisent notamment ce cache de snapshot, un producteur en pause, les redimensionnements, les erreurs de wrapping/drain et la rétention des leases ; ils ne prouvent pas les pixels effectivement calculés par le GPU.
+
+Le chemin iOS optimisé comporte **deux écritures GPU plein cadre** : buffer natif → texture d'import → snapshot. Le premier build 3.0.6, archivé comme référence avant cette optimisation, en comportait trois avec un staging Skia supplémentaire. Le changement enlève donc une passe et une cible GPU : **31,64 Mio à 3840 × 2160 BGRA8 par runtime**, hors alignement et pilote. Une texture d'import de cette taille reste nécessaire, en plus des snapshots des producteurs. Cette déduction des allocations ne constitue pas à elle seule une mesure mémoire ou vitesse : la [passe iPhone dédiée](PERFORMANCE_IPHONE_306_OPTIMIZATION.md) conserve ses résultats et ses limites, notamment ses conditions thermiques non nominales. La synchronisation et la durée de vie des images n'ont pas été relâchées.
+
+Depuis le 8 octobre, l'export iOS dessine directement dans les buffers du pool encodeur via leur IOSurface, avec repli sur le readback CPU si la sonde échoue. Depuis la migration 3.4.4, il échantillonne aussi les frames décodées en place, sans le blit ni le snapshot décrits ci-dessus, et ferme chaque import par `GPUSharedTextureMemory.destroy()` ; voir l'[audit](../migration/skia-3.4.4/upstream-audit.md#passe-export-ios-de-cette-migration). Sur Android, l'export dessine désormais dans des AHardwareBuffer prêtés par l'encodeur, échantillonnés par EGL dans la Surface du codec, si l'interop AHB est négociée ; voir l'[audit](../migration/skia-3.4.4/upstream-audit.md#passe-export-android-14-octobre-soir--compilée-non-mesurée). Depuis la migration 3.6.1, il échantillonne aussi en place les frames décodées par `ImageReader` : chaque buffer YUV, importé une fois, est converti dans une texture RGBA par producteur, sans snapshot ni attente par clip ; voir l'[audit](../migration/skia-3.6.1/upstream-audit.md#import-en-place-à-lexport-android). Le paragraphe suivant décrit le chemin de readback, désormais repli sur les deux plateformes.
+
+L'export par readback garde son `readPixels` vers un buffer CPU réutilisé puis le pool encodeur natif. Les modes publics `copy` et `direct` restent des options de compatibilité, avec le même transport effectif dans ce backend. Android emploie AHardwareBuffer quand les capacités requises sont disponibles, et conserve un fallback CPU RGBA scoped-copy. La voie AHB évite le readback d'entrée et son upload CPU, comme détaillé ci-dessous ; elle ne transforme pas l'export composé en sortie sans copie.
+
+## Android : éviter le cache d'images raster du provider
+
+Les sources **installées de Skia 3.0.6** montrent un autre cache, distinct des budgets GPU en octets : `node_modules/react-native-skia/cpp/rnskia/RNImageProvider.h:21,49–62,97` conserve jusqu'à **256 images** dans un LRU de références fortes `sk_sp<SkImage>`. Le provider convertit une image raster avec `TextureFromImage` puis conserve l'image GPU obtenue. `cpp/skia/include/gpu/graphite/ImageProvider.h:19–23` indique que Graphite consulte ce provider pour les images qui ne sont pas déjà Graphite. Le provider persiste avec chaque Recorder ; voir `cpp/rnskia/RNDawnContext.h:88–92,343–350` dans le même paquet.
+
+Créer une nouvelle image raster pour chaque frame vidéo fournit donc de nouvelles clés au cache. Fermer nos wrappers raster ne retire pas les images GPU détenues par ce provider. Sa limite porte sur un nombre d'images, indépendamment de leur résolution ; les budgets de cache Graphite ne peuvent pas garantir l'éviction de ressources encore référencées. Le budget vidéo comptabilise nos propriétaires, pas ces références amont. Cette chaîne explique une rétention possible hors budget vidéo ; elle ne suffit pas à attribuer un relevé PSS/RSS ou à prouver une fuite.
+
+Les deux voies Android de [frameInterop.ts](../src/frameInterop.ts) évitent ce cache : elles ne créent plus de `SkData` ni d'image raster. Le fallback testé conserve le readback EGL, puis `copyPixelsTo` copie les pixels dans **un ArrayBuffer CPU privé réutilisable par runtime, dimensions et stride**, sans matérialiser le getter natif `texture.data`. `queue.writeTexture` alimente ensuite une texture d'import réutilisable et Skia en fait un snapshot Graphite indépendant. La lecture explicite de `texture.data` reste disponible aux consommateurs ; leurs alias ont une durée de vie distincte.
+
+La voie AHardwareBuffer remplace ce transfert CPU d'entrée par **rendu EGL du codec dans un AHardwareBuffer RGBA → blit WebGPU → texture d'import RGBA → snapshot Graphite indépendant**. [gpuDevice.ts](../src/gpuDevice.ts) négocie avant création des décodeurs : le device Skia partagé doit exposer `shared-texture-memory-ahardware-buffer` et `shared-fence-sync-fd`, et le wrapper natif doit être disponible. Un refus de capacité identifié permet le fallback ; une erreur de quota, d'allocation ou de programmation reste une erreur. Dans WebGPU 0.12.1, `AndroidPlatformContext.h:390–433` et `GPUExternalTexture.cpp:318–354` importent l'AHB RGBA mais l'exposent avec le marqueur `pixelFormat: 'bgra8'` pour une source RGB à un seul plan. Le format réel de destination Android reste RGBA. L'API d'import ne transmet pas de fence producteur : [NativeHardwareBuffer.cpp](../android/cpp/NativeHardwareBuffer.cpp) termine et vérifie les écritures EGL avant publication du pointeur.
+
+Dans les deux voies, chaque écriture utilise un wrapper de surface neuf, une soumission vérifiée et une attente avant fermeture des leases ou réécriture de l'intermédiaire. Les transitions CPU/AHB ferment le scratch CPU inutilisé, même à dimensions identiques. Dimensions, stride et stockage sont contrôlés avant allocation ; les buffers, textures et snapshots possédés sont réservés dans le budget vidéo. Un drain échoué conserve les ressources et bloque les imports suivants. Aucun cache global ni device partagé n'est purgé ou remplacé.
+
+Les backings Java/JSI exposés aux consommateurs gardent leur durée de vie **ART/Hermes à deux phases** : leurs vues et alias ArrayBuffer doivent mourir avant restitution de la réservation. Retirer notre référence au scratch CPU et sa réservation logique ne garantit pas un retour physique immédiat de ses pages. Aucun GC forcé n'est ajouté. Le fallback a terminé les huit opérations ciblées sans OOM, mais a échoué aux huit contrôles de fermeture après deux secondes ; ce résultat ne prouve ni fuite permanente ni stabilité mémoire.
+
+Sur Pixel 8a, le binaire AHB a passé les **24 essais et leurs fermetures strictes**, avec **986 relevés nominal/normal/active**, un budget de **512 Mio** et les ressources suivies finales à zéro. L'oracle CPU/AHB séparé a passé **10/10 cas** : disposition de lignes 638×358, portrait, rotation 90°, H.264 et HEVC 4K, en copy/direct. Les **66 560 canaux RGBA échantillonnés** sont identiques, y compris sur les frames retenues ; ce diagnostic effectue un readback et ne mesure pas la performance. Les tests natifs 5×3 vérifient séparément pixels, stride, finish/abort, retenue après fermeture EGL et quota. Ces preuves ne qualifient pas toute l'image, le HDR, l'audio, la mémoire complète du pilote ou l'absence de fuite longue. Lors d'une mise à jour Skia, relire le provider, les formats AHB et les contrats de fences avant de changer la stratégie vidéo.
+
+Une passe séparée a passé **4/4 cas de cycle de vie**, une répétition chacun : pause/reprise, retrait des items fermés, pause/attente suivie de seeks, et composition de huit clips 4K en lazy/direct, avec **25 cycles courts et 40 remontages**. Ce dernier cas a atteint **800,25 Mio de RSS, 1 037,91 Mio de PSS et 257,08 Mio de réservations suivies** au pic ; le RSS final reste à **785,82 Mio** malgré les réservations à zéro. Ces pics sont échantillonnés indépendamment et n'attribuent pas les pages aux caches Graphite, au pilote ou aux codecs. Le cas nommé `held-image-survives-seek` ne conserve pas de SkImage distincte et ne valide pas ses pixels : la preuve de retenue reste l'oracle raw frame séparé. Les **5 tests JNI CPU** ont aussi repassé sur le binaire AHB, sans skip. Aucune stabilité sur longue durée ni configuration à 256 Mio n'est qualifiée.
+
+## Historique 3.0.3 : pourquoi éviter `Skia.NativeBuffer.MakeFromImage`
+
+En 3.0.3, le chemin Apple de `makeNativeBuffer` réalise une lecture des pixels sur CPU, construit un IOSurface puis un CVPixelBuffer. Ce n'est pas une sortie vidéo sans copie. Dans [`apple/RNSkApplePlatformContext.mm`, version 3.0.3](https://github.com/wcandillon/react-native-skia/blob/v3.0.3/packages/skia/apple/RNSkApplePlatformContext.mm#L122-L174), les objets retournés par `CFNumberCreate`, le dictionnaire créé par `CFDictionaryCreateMutable` et l'IOSurface créé par `IOSurfaceCreate` n'ont pas de libération correspondante dans ce chemin, y compris lors de certaines erreurs.
+
+**Décision historique, conservée : ne pas utiliser cette fonction dans la boucle d'export.** L'encodeur de référence reçoit des pixels RGBA/BGRA et utilise son propre pool borné. Cela évite de dépendre de cette allocation amont par frame. Corriger seulement les références Core Foundation ne transformerait pas la fonction en export GPU direct : les copies CPU resteraient présentes.
+
+Cette API est maintenant supprimée en 3.0.6. Si une future API de sortie de buffers natifs apparaît, reprendre les critères suivants :
+
+1. Lire la nouvelle fonction et les chemins d'erreur, vérifier l'équilibre de chaque Create/Retain et du release du CVPixelBuffer retourné.
+2. Vérifier le format, les strides, le coût de copie et l'ownership de l'objet exporté, indépendamment de la correction des références.
+3. Exécuter des exports longs, répétés et annulés sur appareils iOS physiques, avec des tailles alternées ; vérifier les compteurs de session et un palier des allocations natives/GPU après warmup.
+4. Comparer au chemin de référence avec les mêmes fichiers, dimensions, codecs et collecteurs. Activer le nouveau chemin explicitement seulement si ses pixels, timestamps, fermeture et résultats mémoire sont qualifiés.
+
+Aucun correctif de cette fonction n'est inclus dans ce dépôt et aucune issue amont n'a été publiée dans le cadre de ce travail. Cette analyse historique ne décrit pas une fonction encore disponible dans le build 3.0.6.
+
+## Prototype futur : rendre dans le buffer de l'encodeur
+
+**Implémenté le 8 octobre 2026** (sortie seulement, une frame à la fois, attente explicite), puis complété en 3.4.4 par la fermeture immédiate des imports et l'entrée en place. La proposition d'origine est conservée ci-dessous ; la version asynchrone par propagation de fences reste à faire.
+
+**Proposition à discuter, sans implémentation ni validation de performances.** Le backend actuel attend le GPU puis appelle `readPixels` et transmet ces pixels au pool natif, pour les deux valeurs de `encoderMode` : [exportVideoComposition.ts](../src/exportVideoComposition.ts). Les deux valeurs de `textureMode` produisent des images possédées selon le chemin décrit ci-dessus : [frameInterop.ts](../src/frameInterop.ts). Le [contrat public](../src/types.ts) décrit cette compatibilité. Le mot `direct` dans un scénario ne prouve donc pas que le nouveau chemin évite les copies.
+
+L'ancien moteur iOS utilisait déjà Metal. Son export direct copiait sur GPU la texture vers une vue Metal du CVPixelBuffer destiné à l'encodeur. La piste d'optimisation du candidat consiste surtout à supprimer son aller-retour CPU par image ; ajouter un autre canvas natif ne règle pas à lui seul cet intermédiaire. La comparaison de bibliothèques doit conserver cette différence de chemins dans son interprétation.
+
+Les sources des versions ciblées contiennent plusieurs briques utiles :
+
+- WebGPU 0.12.1 expose `importSharedTextureMemory`, puis `createTexture`, `beginAccess` et `endAccess`. Sur iOS, son `handle` est un **IOSurfaceRef**, tandis que `createVideoFrameFromNativeBuffer` reçoit un **CVPixelBufferRef**. Ne pas intervertir ces pointeurs. La fermeture explicite des ressources d'import reste à vérifier pour le prototype de sortie. [Description officielle des imports natifs](https://wcandillon.github.io/react-native-webgpu/docs/getting-started/native-api).
+- Skia 3.0.6 expose `Skia.Surface.MakeFromGPUTexture` pour dessiner dans une texture du device partagé ; le wrapper exige l'usage `RenderAttachment`. [Source versionnée](https://github.com/wcandillon/react-native-skia/blob/v3.0.6/packages/skia/cpp/rnskia/RNDawnContext.h). Cette existence ne prouve pas que tous les formats ou buffers vidéo importés sont des cibles de rendu acceptées.
+- Le pool de [VideoEncoderHostObject.mm](../ios/VideoEncoderHostObject.mm) crée des buffers BGRA compatibles Metal/IOSurface, refuse de dépasser trois allocations et attend leur disponibilité. Sa branche native `encodeFrame(CVPixelBufferRef, ...)` peut soumettre directement un buffer ; elle n'est pas utilisée par le chemin JavaScript actuel de lecture des pixels.
+
+Le device principal de Skia 3.0.6 demande `SharedTextureMemoryIOSurface` et `SharedFenceMTLSharedEvent` dans [RNDawnUtils.h](https://github.com/wcandillon/react-native-skia/blob/v3.0.6/packages/skia/cpp/rnskia/RNDawnUtils.h). Le commentaire natif impose une soumission avant `EndAccess` sur ce chemin Metal ; le device secondaire possède un contrat différent et omet délibérément cette feature de fence. Le prototype doit donc utiliser le device principal partagé, vérifier ses capacités effectives et ne pas transposer le chemin caméra du device secondaire.
+
+Le plus petit prototype iOS devrait porter sur **la sortie seulement**, à taille fixe, avec une frame préparée à la fois. Il conserverait le décodage et `drawFrame` existants :
+
+1. Acquérir un CVPixelBuffer du pool par une nouvelle interface native de session. La session doit conserver explicitement le buffer et fournir un identifiant de réservation, son IOSurface, ses dimensions et son format ; un pointeur nu sans propriétaire ne suffit pas.
+2. Importer cet IOSurface sur le device de Skia, vérifier les usages/format permis, ouvrir son accès et envelopper la texture dans une surface Skia. Initialiser toute l'image avant de dessiner. Ne pas créer de snapshot intermédiaire pour ce chemin.
+3. Soumettre le dessin Skia, fermer l'accès partagé et établir la fin effective des écritures GPU avant la soumission à AVAssetWriter. Le premier prototype peut attendre cette fin explicitement ; une version asynchrone ultérieure demandera une propagation correcte des fences. `endAccess` ou l'acceptation d'une commande ne doit pas être confondu avec la fin physique de son exécution.
+4. Transmettre le CVPixelBuffer à l'encodeur, détacher et fermer ses consommateurs GPU, puis relâcher la réservation de la session dans un ordre prouvé. AVAssetWriter peut conserver le buffer après son acceptation : le pool doit attendre sa restitution, sans réécrire manuellement dans un buffer encore en cours d'encodage.
+5. Traiter annulation, erreur d'import, erreur d'encodage et échec de synchronisation sans fermer une ressource encore utilisée. Garder des files et réservations bornées, comptabiliser les allocations réelles et revenir au chemin de référence si la capacité requise manque avant le démarrage. Une perte du device partagé demande l'arrêt du travail concerné, pas la création silencieuse d'un device de remplacement.
+
+Cette architecture pourrait éviter la lecture CPU de la **sortie composée**. Elle ne supprimerait pas automatiquement la copie des frames d'entrée, les conversions du codec ni toutes les copies internes du pilote. Elle ne doit pas être présentée comme une vidéo intégralement « zero-copy ». L'équivalent Android exige une étude distincte des buffers et de l'entrée de MediaCodec.
+
+**Décision proposée : essayer les APIs existantes avant un nouveau patch Skia.** Le travail principal appartient à l'interface entre notre pool vidéo, l'accès partagé et l'encodeur. Si une capacité manque réellement, isoler un reproducer et proposer le plus petit changement amont ; ne pas maintenir un fork général de Graphite ou Dawn. Les critères de passage seront les pixels/couleurs/timestamps, les annulations et changements de taille, puis les mêmes sessions longues sur appareils avec mesure de mémoire et durée. Le petit patch de durée de vie décrit ci-dessous reste indépendant de ce prototype.
+
+## Patch distinct : durée de vie et soumissions vérifiées
+
+Ces quatre protections restent nécessaires en **3.4.4**, puis en **3.6.1**, dont les fichiers patchés sont identiques à ceux de 3.4.4 : l'amont n'a ajouté ni `dispose()` de canvas, ni contrôle d'`insertRecording`, ni garde du snapshot nul, et sa factory d'`ImageProvider` n'a pas changé. Le `dispose()` rebasé remet la surface au `Dispatcher` de son thread créateur, comme le fait désormais le destructeur amont du canvas. Le reste de cette section décrit le patch d'origine.
+
+Dans Skia 3.0.3 et encore dans les sources 3.0.6, le wrapper `JsiSkCanvas` peut garder une référence propriétaire à la surface dont il provient. Disposer uniquement le wrapper `SkSurface` ne ferme donc pas cette référence tant que le canvas est encore détenu ; attendre le GC pour les surfaces temporaires est insuffisant pour une fermeture déterministe.
+
+Le patch local ajoute `canvas.dispose()`, idempotent, qui annule `_canvas` et relâche `_surface`, ainsi que la déclaration TypeScript. Les accès ultérieurs via `getCanvas()` échouent explicitement.
+
+Il vérifie aussi le résultat de `makeImageSnapshot()` dans `JsiSkSurface.h`. En cas d'échec d'allocation, une erreur est levée avant de remplacer l'image détenue par le consommateur ou de construire un wrapper autour d'une image nulle. Cette garde est nécessaire sous pression mémoire. Le patch ne restaure pas `Skia.NativeBuffer`.
+
+La migration ajoute aussi une activation interne par surface, `enableCheckedSubmissions()`, appelée par [getVideoCanvas](../src/canvas.ts). Pour ces seules surfaces, la soumission de `flush` et celle de `makeImageSnapshot` refusent un recording nul et vérifient les résultats de `insertRecording` et `submit`. Les surfaces qui n'activent pas ce mode conservent le comportement amont. Cette méthode est une garde privée de notre adaptateur, pas une nouvelle API publique à utiliser dans une application de montage.
+
+Cette protection répond à un cas précis : le blit WebGPU peut déjà être soumis lorsque Graphite échoue. Un retour normal de `flush(true)` ne doit pas être interprété comme une preuve de fin de queue si l'amont a ignoré l'échec d'insertion ou de soumission. Les chemins d'erreur conservent les leases et leurs réservations jusqu'à un drain réussi, et refusent de les fermer lors d'un retry du même frame encore retenu.
+
+La [source Skia de ce build](https://chromium.googlesource.com/skia/+/2466dcf3937437e217e7f284afe0e1aae15891ce/src/gpu/graphite/Recorder.cpp) distingue un recording vide valide d'un recording nul signalant un échec. Le mode vérifié accepte donc le premier. En fonctionnement normal, [DawnQueueManager](https://chromium.googlesource.com/skia/+/2466dcf3937437e217e7f284afe0e1aae15891ce/src/gpu/graphite/dawn/DawnQueueManager.cpp) soumet sur la même queue que WebGPU puis attend `OnSubmittedWorkDone` pour le flush synchrone. Cette revue de source et les tests JavaScript ne remplacent pas la qualification du chemin optimisé sur appareil ; ils ne garantissent pas une récupération générale après perte du device.
+
+Fichiers inspectables :
+
+- [`patches/react-native-skia+3.6.1.patch`](../patches/react-native-skia+3.6.1.patch) : diff du correctif courant, identique à celui de 3.4.4 ; ceux de 3.4.4 et 3.0.6 sont conservés comme historique.
+- [`scripts/skia-canvas-patch.json`](../scripts/skia-canvas-patch.json) : version, empreintes avant/après et substitutions attendues.
+- [`scripts/apply-skia-canvas-patch.mjs`](../scripts/apply-skia-canvas-patch.mjs) : vérifie tout avant toute écriture, accepte un patch déjà appliqué, refuse un paquet différent.
+
+Les appels de la bibliothèque doivent soumettre et attendre les enregistrements concernés avant cette fermeture, sur le runtime propriétaire. Le patch n'autorise pas la libération anticipée d'une texture encore utilisée par le GPU. Reconstruire le binaire après son application et refaire les cycles de preview/export.
+
+L'application consommatrice doit intégrer le patch avant sa compilation native, dans son propre mécanisme d'installation/CI. Le script conservé dans le paquet est une entrée explicite ; il n'est pas appliqué silencieusement par le chargement JavaScript. Lors d'une mise à jour Skia, conserver l'échec du garde-fou jusqu'à la revue de la nouvelle durée de vie et des erreurs d'allocation. Retirer chaque partie du patch lorsque l'amont offre une protection équivalente et que les tests de ressources l'ont confirmé.
+
+### Readback d'export : garde amont à étudier séparément
+
+**En 3.4.4**, `canvas.readPixels` lit le rectangle demandé directement dans la destination via `JsiSkImage::readPixelsInto`, et `DawnContext::readPixelsSync` attend hors du verrou du contexte, un thread dédié interrogeant le GPU. Le readback ne fige donc plus les autres vues Skia. Le snapshot du canvas n'est toujours pas vérifié, et le résultat nul est désormais propagé en `null` plutôt que déréférencé. Le paragraphe suivant décrit les sources 3.0.6.
+
+Dans les sources 3.0.6, `JsiSkCanvas::readPixels` crée son propre snapshot et le soumet directement à `DawnContext`, sans passer par le mode vérifié du wrapper surface. Ce chemin ne vérifie pas son snapshot nul. `DawnContext::MakeRasterImage` ne vérifie pas non plus le résultat nul du callback asynchrone avant son utilisation et ignore le résultat de sa soumission. Les sources sont [JsiSkCanvas.h](https://github.com/wcandillon/react-native-skia/blob/v3.0.6/packages/skia/cpp/api/JsiSkCanvas.h) et [RNDawnContext.h](https://github.com/wcandillon/react-native-skia/blob/v3.0.6/packages/skia/cpp/rnskia/RNDawnContext.h).
+
+Ce sont des chemins d'échec à reproduire sous pression mémoire ou perte du device, pas un crash attribué aux mesures actuelles. Le flush vérifié avant le readback sécurise le travail déjà enregistré ; il ne transforme pas ces opérations suivantes en soumissions vérifiées. Aucun correctif supplémentaire de ce readback n'est inclus dans l'optimisation d'entrée. Avant de supprimer une attente ou de modifier l'export, isoler ce contrat et tester les échecs et la fermeture ; conserver le petit patch existant dans son périmètre actuel.
+
+## Couple Skia / WebGPU et anciens modules natifs
+
+Le partage de textures demande le même Dawn et le même device natif. Le couple actuel ne doit pas être mis à jour séparément sans revue des versions natives et des APIs d'interop. Une nouvelle version de package ou un nouveau SDK peut changer les formats, les fences et la durée de vie des buffers.
+
+Le device possédé par Skia doit rester possédé par Skia. Un adaptateur de la bibliothèque ne doit pas le détruire à la fermeture d'une session. Les imports natifs Metal/GL historiques, les définitions Ganesh et les modules compilés contre les anciens headers demandent une migration explicite. Réappliquer le patch de destruction de surface de l'application Skia 2 à Skia 3 sans cette revue serait une hypothèse injustifiée.
+
+La paire a été vérifiée dans les **archives npm publiées**, sans contourner le contrôle du podspec : Graphite Apple iOS 154.1.0 contient `libs/.dawn-version = dawn-chrome-m154a` ; WebGPU 0.12.1 annonce `chrome-m154a`, commit Dawn `3d786993a7ded64c4ebb4884b9b079db9ad0e580`. Le couple historique mesuré 3.0.3 / 0.11.0 utilisait le tag `dawn-chrome-m154`. Ne pas mélanger ces binaires dans une série A/B. La [documentation d'interop](https://wcandillon.github.io/react-native-webgpu/docs/integrations/react-native-skia) demande un couple compatible et une instance Dawn commune.
+
+La [release Skia 3.0.5](https://github.com/wcandillon/react-native-skia/releases/tag/v3.0.5) annonce le déplacement des APIs NativeBuffer. La [release 3.0.6 du 7 octobre](https://github.com/wcandillon/react-native-skia/releases/tag/v3.0.6) livre Graphite 154.1.0, le build Android avec RTTI et un correctif de publication SwiftPM. La comparaison des tarballs 3.0.5 et 3.0.6 ne trouve qu'un changement de `package.json` : les sources d'interop sont identiques. Le patch de durée de vie reste nécessaire et doit porter les empreintes 3.0.6.
+
+**Depuis Skia 3.4.x / WebGPU 0.14.x**, les deux paquets dépendent du même paquet npm `react-native-webgpu-dawn` ; le podspec et le Gradle de Skia comparent les versions résolues de ce paquet, et non plus une chaîne de tag. Le couple courant est 3.4.4 / 0.14.2 avec `react-native-webgpu-dawn@154.3.0`. Associer Skia 3.0.6 à WebGPU 0.14.x passerait l'ancien contrôle de tag tout en mélangeant deux builds Dawn : ne pas le faire.
+
+WebGPU 0.12.0 ajoute le blit de `NativeVideoFrame` dans `copyExternalImageToTexture`, des helpers publics de vidéo et des contrôles supplémentaires de lecteur. Notre migration conserve ses propres codecs ; elle utilise le wrapper et le blit. Entre 0.12.0 et 0.12.1, les sources JS/C++ de binding sont identiques : les changements portent sur les binaires Dawn et leur packaging.
+
+Le suffixe **m154a** désigne une fabrication corrigée de Dawn, pas une nouvelle version du standard WebGPU. Le [correctif Tint au tag exact](https://github.com/wcandillon/react-native-webgpu/blob/dawn-chrome-m154a/packages/webgpu/scripts/dawn-patches/tint-looprange-function-variable.patch) adapte les variables de boucle pour éviter un blocage GPU documenté sur Pixel 8 / Mali-G715. Il ne démontre aucun gain de vitesse sur iPhone. Les pages de documentation non versionnées doivent toujours être confrontées au tag et aux dépendances verrouillées ; le fait qu'une API y figure ne prouve pas sa présence dans un ancien build.
+
+## Pourquoi investir dans WebGPU pour la composition vidéo
+
+WebGPU est l'API de rendu et de calcul GPU ; Dawn en est une implémentation native utilisant notamment Metal et Vulkan ; Graphite est le backend de rendu de Skia ; React Native Skia 3 expose ce rendu à l'application. Three.js ajoute un moteur 3D. Core ML/Vision et les modèles ML restent des composants séparés. Une annonce concernant l'un de ces niveaux ne livre pas automatiquement une capacité dans tous les autres. [Présentation officielle de Dawn](https://dawn.googlesource.com/dawn/+/refs/heads/main/README.md).
+
+William Candillon explique que React Native WebGPU vise la 3D et le calcul GPU général, puis décrit Redraw comme une bibliothèque de nouvelles primitives vectorielles communes au web et au natif. Ce sont ses objectifs publiés, pas une hypothèse sur ses motivations personnelles. [Présentation de William](https://wcandillon.dev/).
+
+Pour une application de montage avec widgets, la valeur immédiate à explorer est le partage de textures entre une petite scène 3D ou un effet de calcul et le canvas Skia qui porte déjà les widgets. L'[intégration Three.js](https://wcandillon.github.io/react-native-webgpu/docs/integrations/three-js) décrit une scène rendue sur le device de Skia puis composée comme une image. Ce partage peut éviter une copie entre ces deux rendus ; il ne préjuge pas du chemin d'export vidéo ni de son coût global. Le [guide de migration](MIGRATION.md) distingue les fonctionnalités disponibles des intégrations encore à construire.
+
+La mention d'une prochaine « version WebGPU par Google » n'a pas pu être rattachée à une annonce précise dans cette étude. Ne pas décider de la migration à partir de cette formulation seule : relever le lien, la date, le composant concerné, puis sa disponibilité dans les versions natives retenues. Une sortie Chrome ou Dawn ne met pas automatiquement à jour le binaire de l'application iPhone. Aucun suivi automatique n'est créé par cette note.
+
+## Caches Graphite : budget indépendant des ressources vidéo
+
+Les headers inspectés dans **Skia 3.0.3 et 3.0.6** fixent un budget GPU par défaut de **256 Mio pour chaque Recorder** et de **256 Mio pour le Context**. Références exactes dans ces paquets : `cpp/skia/include/gpu/graphite/Recorder.h:79–81` et `ContextOptions.h:123–127`. Ce sont des budgets de ressources allouées/retenues et de cache ; cela ne signifie pas que 256 Mio sont alloués en permanence, ni que le RSS leur est attribuable.
+
+Le wrapper [RNDawnContext.h de Skia 3.0.3](https://github.com/wcandillon/react-native-skia/blob/v3.0.3/packages/skia/cpp/rnskia/RNDawnContext.h) crée les options et le Recorder en `thread_local` aux lignes 429–436 et le Context avec son budget par défaut aux lignes 480–485, sans override de ces budgets. Les sources 3.0.6 conservent cette politique par défaut. Le Recorder appartient à un thread, pas à chaque export ; plusieurs threads peuvent posséder leurs Recorders. Ces budgets ne sont pas comptés par le budget `ownedBytes` de la vidéo et ne plafonnent pas le RSS du processus.
+
+Les APIs natives distinguent `currentBudgetedBytes`, `currentPurgeableBytes`, `maxBudgetedBytes` et `setMaxBudgetedBytes` (`Recorder.h:218–238`, `Context.h:240–260`). Une baisse du budget tente de libérer des ressources ; ce n'est pas un plafond strict de mémoire physique. `freeGpuResources` conserve les ressources en cours d'utilisation et demande de soumettre/attendre les travaux pour une fermeture complète (`Recorder.h:200–206`, `Context.h:222–228`).
+
+**Point futur amont : obtenir une API prise en charge pour inspecter/configurer ces caches au niveau de l'application.** La bibliothèque ne purge pas globalement Graphite, ne modifie pas le budget du device partagé et ne le détruit pas. Une politique globale décidée par la vidéo pourrait perturber les scènes 3D, compute ou ML de l'application. Lors d'une mise à jour Skia, revoir ces valeurs, l'affinité des Recorders et les APIs exposées, puis qualifier toute politique de cache avec les autres consommateurs GPU. Les relevés RSS du simulateur ne permettent pas de conclure quels caches ou allocateurs expliquent leur variation.
+
+La [comparaison du 6 octobre 2026](PERFORMANCE_AB_SOAK_SIMULATOR.md) apporte désormais une référence à rejouer après chaque changement : 300 exports par moteur, mêmes dimensions et collecteur, puis trois minutes de repos. Le RSS final du candidat progresse de 416 à 553 puis 626 Mio, contre environ 308/315/300 Mio pour l'ancien ; au repos à trois minutes, il reste à 437,38 Mio contre 133,20 Mio. Les compteurs vidéo du candidat reviennent à zéro. Ces chiffres motivent l'inspection des allocations encore résidentes, mais **n'attribuent pas la différence aux caches Graphite** : une preuve par catégorie d'allocation reste nécessaire avant de modifier une politique globale.
+
+Une autre catégorie à instrumenter est le buffer CPU de [l'export](../src/exportVideoComposition.ts) : un `Uint8Array` est alloué par session, réutilisé pour les frames, puis sa référence est mise à null après fermeture ; le runtime d'export persiste entre sessions. La disparition de cette référence et de sa réservation comptable n'atteste pas la restitution immédiate du backing store ou des pages de l'allocateur. Distinguer ce stockage, les rasters transitoires du readback, les codecs et les ressources Graphite avant d'attribuer la hausse à l'un d'eux. Cette lecture de code ne prouve pas l'origine de la rétention observée et n'ajoute ni GC forcé ni nouveau cache partagé.
+
+### Mesure Android et référence orpheline du provider — 7 octobre 2026
+
+L'[investigation sur Pixel 8a](ANDROID_MEMORY_RETENTION_306.md) a mesuré les caches du couple 3.0.6 / 0.12.1 : le binaire diagnostique observe les Recorders sur leurs threads propriétaires et compare observation, drain seul et drain avec purge. Le rapport conserve les catégories mémoire, les compteurs et les limites de ce test. Ce mécanisme n'est pas ajouté au patch de production ; une purge du Context partagé demande une politique au niveau de l'application.
+
+Autre point concret à revoir lors de la prochaine mise à jour : `RNImageProvider.h` amont en 3.0.6 construit son provider avec `sk_ref_sp(new ImageProvider)`. Ce helper incrémente la référence initiale au lieu de l'adopter. Le patch versionné remplace maintenant cette expression par `sk_make_sp<ImageProvider>()`. Le [test de propriété](../scripts/test-skia-provider-ownership.mjs) compile le corps de la factory installée avec le véritable `SkRefCnt` et un objet dont on compte les destructions ; il vérifie aussi la survie d'un alias puis la destruction à sa fermeture. Cette correction ne suffit pas à expliquer la mémoire restante, comme le montre le [test isolé sur appareil](ANDROID_EXPORT_CACHE_306.md).
+
+Le patch ajoute également une méthode privée `__rnskvTrimRecorderCache` : elle soumet et attend le recording courant en vérifiant les erreurs, relâche ce recording, puis appelle `freeGpuResources` sur ce seul Recorder. Elle ne purge pas le Context. La bibliothèque l'utilise uniquement sur son runtime d'export privé, après fermeture des consommateurs et avant restitution des réservations. Une erreur de drain conserve la quarantaine et interdit de réutiliser ce runtime. La preview ne l'appelle pas ; ses caches et ceux des autres Recorders restent inchangés. Recompiler le binaire natif après réapplication du patch : l'export refuse une ancienne version avant ses allocations si la méthode manque.
+
+Lors d'une mise à jour amont, vérifier séparément la correction de la factory, l'affinité de thread du Recorder, les erreurs de soumission et une éventuelle API officielle de nettoyage. Ne pas remplacer cette politique limitée par une purge globale à chaque frame.
+
+## Référence fournie : `enzomanuelmangano/demos`
+
+Le [dépôt de démos](https://github.com/enzomanuelmangano/demos) est utile pour choisir des scènes visuelles : transitions, reflets de shader et interactions pilotées par des valeurs partagées. Le [manifest consulté](https://github.com/enzomanuelmangano/demos/blob/main/package.json) fixe encore Skia 2.6.2 et WebGPU 0.5.14 ; ses patches de compatibilité ne sont donc pas une preuve de compatibilité avec le couple désormais ciblé 3.0.6/0.12.1, ni avec le couple mesuré 3.0.3/0.11.0.
+
+Les idées retenues pour les futurs adaptateurs sont une transition à progression déterministe, un shader piloté par les mêmes paramètres en preview/export et une scène 3D calculée au temps de composition. Aucun code ou asset de ce dépôt n'est copié dans la bibliothèque. Sa [licence publiée](https://github.com/enzomanuelmangano/demos/blob/main/LICENSE.md) comporte des restrictions de redistribution et de création de bibliothèques d'animation concurrentes ; la référence sert ici à l'étude visuelle. Les implémentations de comparaison doivent être originales ou venir d'une source réutilisable dans ce paquet.
+
+## Procédure de mise à jour
+
+Pour chaque nouvelle version Skia : relever le couple Dawn/WebGPU et les versions RN/Reanimated/Worklets compatibles, relire les imports/sorties de buffers, les soumissions vérifiées, la fermeture canvas/snapshot et les budgets/caches Graphite, revoir les empreintes, compiler les deux plateformes, exécuter les tests de pixels/timestamps puis les **65 workloads du catalogue `2026-10-07.1`** (59 historiques, trois lectures continues `copy` et leurs trois équivalents `direct`) et les sessions longues. La configuration iPhone déjà compilée pour la référence 3.0.3 utilise RN 0.86.2, Reanimated 4.5.3 et Worklets 0.11.3 ; ces versions sont conservées pour la migration 3.0.6. Ne pas laisser une plage ouverte sélectionner une autre version sans refaire l'installation native. Documenter la version et le transport effectif dans les résultats. La présence d'un cas dans le catalogue ne signifie pas qu'il a été exécuté sur toutes les cibles. Une correction amont ou des tests de l'hôte verts seuls ne justifient pas de supprimer un garde-fou mémoire.

package/docs/assets/banner.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="300" viewBox="0 0 1200 300" role="img" aria-labelledby="title desc">
+  <title id="title">React Native Skia WebGPU Video</title>
+  <desc id="desc">Play, compose, and export. Layered video frames on a dark blue background.</desc>
+  <defs>
+    <linearGradient id="bg" x2="1" y2="1"><stop stop-color="#0b1225"/><stop offset="1" stop-color="#17233b"/></linearGradient>
+    <linearGradient id="accent" x2="1" y2="1"><stop stop-color="#38bdf8"/><stop offset="1" stop-color="#a78bfa"/></linearGradient>
+    <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse"><path d="M40 0H0V40" fill="none" stroke="#334155" stroke-opacity=".28"/></pattern>
+  </defs>
+  <rect width="1200" height="300" rx="22" fill="url(#bg)"/>
+  <rect width="1200" height="300" rx="22" fill="url(#grid)"/>
+  <rect x="54" y="54" width="5" height="192" rx="2.5" fill="url(#accent)"/>
+  <g font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif">
+    <text x="82" y="87" fill="#7dd3fc" font-size="16" font-weight="600" letter-spacing="3">REACT NATIVE · SKIA 3</text>
+    <text x="79" y="157" fill="#f8fafc" font-size="55" font-weight="700" letter-spacing="-1.8">WebGPU Video</text>
+    <text x="82" y="206" fill="#cbd5e1" font-size="24">Play. Compose. Export.</text>
+    <text x="82" y="242" fill="#94a3b8" font-size="16">One timeline. Your Skia canvas.</text>
+  </g>
+  <g transform="translate(835 51)">
+    <rect x="60" y="0" width="214" height="132" rx="14" fill="#172b44" stroke="#38bdf8" stroke-opacity=".45"/>
+    <rect x="30" y="34" width="214" height="132" rx="14" fill="#1b2947" stroke="#818cf8" stroke-opacity=".65"/>
+    <rect y="68" width="214" height="132" rx="14" fill="#0f172a" stroke="url(#accent)" stroke-width="2"/>
+    <path d="m88 104 50 30-50 30z" fill="url(#accent)"/>
+    <path d="M21 179h51m10 0h30m10 0h72" stroke="#475569" stroke-width="4" stroke-linecap="round"/>
+    <path d="M21 179h51" stroke="#38bdf8" stroke-width="4" stroke-linecap="round"/>
+  </g>
+</svg>

package/examples/webgpu-overlay.ts

@@ -0,0 +1,147 @@
+import type { VideoFrame } from "../src/types";
+import type { VideoFrameProcessor } from "../src/exportVideoComposition";
+import { createVideoGpuScope } from "../src/gpu";
+import {
+  GPUBufferUsage,
+  GPUShaderStage,
+  GPUTextureUsage,
+} from "react-native-webgpu";
+
+// Original minimal 3D example: one color target, one depth target, one uniform
+// buffer, reused for the whole export. Draw frames['gpu-overlay'] with
+// drawVideoFrame in the existing synchronous drawFrame callback.
+const cubeShader = `
+struct Params { value: vec4f };
+@group(0) @binding(0) var<uniform> params: Params;
+struct Vertex { @builtin(position) position: vec4f, @location(0) color: vec3f };
+@vertex fn vertexMain(@builtin(vertex_index) index: u32) -> Vertex {
+  let points = array<vec3f,8>(
+    vec3f(-1,-1,-1), vec3f(1,-1,-1), vec3f(1,1,-1), vec3f(-1,1,-1),
+    vec3f(-1,-1,1), vec3f(1,-1,1), vec3f(1,1,1), vec3f(-1,1,1));
+  let indices = array<u32,36>(
+    0,2,1,0,3,2,4,5,6,4,6,7,0,1,5,0,5,4,
+    3,7,6,3,6,2,0,4,7,0,7,3,1,2,6,1,6,5);
+  let p = points[indices[index]] * 0.65;
+  let t = params.value.x;
+  let q = vec3f(cos(t)*p.x+sin(t)*p.z, p.y, -sin(t)*p.x+cos(t)*p.z);
+  let r = vec3f(q.x, cos(t*0.7)*q.y-sin(t*0.7)*q.z, sin(t*0.7)*q.y+cos(t*0.7)*q.z);
+  let z = r.z+3.0;
+  var out: Vertex;
+  out.position = vec4f(r.x/params.value.y, r.y, (z-0.1)*10.0/9.9, z);
+  out.color = (p+vec3f(0.65))/1.3;
+  return out;
+}
+@fragment fn fragmentMain(input: Vertex) -> @location(0) vec4f {
+  return vec4f(input.color, 1.0);
+}`;
+
+export const createCubeOverlay = async ({
+  width,
+  height,
+}: {
+  width: number;
+  height: number;
+}): Promise<VideoFrameProcessor> => {
+  "worklet";
+  const scope = createVideoGpuScope({ maxResources: 3 });
+  try {
+    const color = scope.createTexture({ width, height, label: "3D color" });
+    const depth = scope.createTexture({
+      width,
+      height,
+      format: "depth24plus",
+      skia: "none",
+      usage: GPUTextureUsage.RENDER_ATTACHMENT,
+      label: "3D depth",
+    });
+    const uniform = scope.createBuffer({
+      size: 16,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+      label: "3D time",
+    });
+    const device = scope.device;
+    const module = device.createShaderModule({ code: cubeShader });
+    const layout = device.createBindGroupLayout({
+      entries: [
+        {
+          binding: 0,
+          visibility: GPUShaderStage.VERTEX,
+          buffer: { type: "uniform" },
+        },
+      ],
+    });
+    const pipeline = await device.createRenderPipelineAsync({
+      layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+      vertex: { module, entryPoint: "vertexMain" },
+      fragment: {
+        module,
+        entryPoint: "fragmentMain",
+        targets: [{ format: "rgba8unorm" }],
+      },
+      primitive: { topology: "triangle-list" },
+      depthStencil: {
+        format: "depth24plus",
+        depthWriteEnabled: true,
+        depthCompare: "less",
+      },
+    });
+    const binding = device.createBindGroup({
+      layout,
+      entries: [{ binding: 0, resource: { buffer: uniform } }],
+    });
+    // Worklets capture primitive bindings separately. Share an object so the
+    // cleanup observes the last map published by prepareFrame.
+    const output: { published: Record<string, VideoFrame> | null } = { published: null };
+    return {
+      prepareFrame: ({ frames, currentTime, isCancelled }) => {
+        "worklet";
+        if (isCancelled()) return;
+        device.queue.writeBuffer(
+          uniform,
+          0,
+          new Float32Array([currentTime, width / height, 0, 0]),
+        );
+        const encoder = device.createCommandEncoder();
+        const pass = encoder.beginRenderPass({
+          colorAttachments: [
+            {
+              view: color.texture.createView(),
+              clearValue: { r: 0, g: 0, b: 0, a: 0 },
+              loadOp: "clear",
+              storeOp: "store",
+            },
+          ],
+          depthStencilAttachment: {
+            view: depth.texture.createView(),
+            depthClearValue: 1,
+            depthLoadOp: "clear",
+            depthStoreOp: "store",
+          },
+        });
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, binding);
+        pass.draw(36);
+        pass.end();
+        device.queue.submit([encoder.finish()]);
+        // Ordered with Skia on the SAME queue/device. No per-frame texture or
+        // image allocation; export flush/readback is the synchronization point.
+        output.published = frames;
+        frames["gpu-overlay"] = {
+          width,
+          height,
+          rotation: 0,
+          texture: { kind: "skia-image", image: color.image },
+        };
+      },
+      dispose: () => {
+        "worklet";
+        if (output.published) delete output.published["gpu-overlay"];
+        output.published = null;
+        return scope.dispose();
+      },
+    };
+  } catch (error) {
+    await scope.dispose();
+    throw error;
+  }
+};

package/ios/AVAssetTrackUtils.h

@@ -0,0 +1,24 @@
+#pragma once
+
+#define RADIANS_TO_DEGREES(radians) ((radians) * (180.0 / M_PI))
+namespace RNSkiaVideo {
+
+class AVAssetTrackUtils {
+public:
+  static float radiansToDegrees(CGFloat radians) {
+    // Input range [-pi, pi] or [-180, 180]
+    CGFloat degrees = RADIANS_TO_DEGREES((float)radians);
+    if (degrees < 0) {
+      // Convert -90 to 270 and -180 to 180
+      return degrees + 360;
+    }
+    // Output degrees in between [0, 360]
+    return degrees;
+  };
+
+  static int GetTrackRotationInDegree(AVAssetTrack* track) {
+    CGAffineTransform t = track.preferredTransform;
+    return round(radiansToDegrees(atan2(t.b, t.a)));
+  }
+};
+} // namespace RNSkiaVideo

package/ios/AudioCompositionUtils.h

@@ -0,0 +1,27 @@
+#pragma once
+
+#import "VideoComposition.h"
+#import <AVFoundation/AVFoundation.h>
+
+namespace RNSkiaVideo {
+
+struct AudioComposition {
+  AVMutableComposition* composition;
+  AVMutableAudioMix* audioMix;
+};
+
+/**
+ * Builds an audio only AVComposition (with an audio mix for per item
+ * volumes) from the audio-enabled items of the given video composition.
+ * Returns {nil, nil} if no item provides audio.
+ * Throws NSError* if an audio item points to a file without audio track.
+ */
+AudioComposition
+buildAudioComposition(const std::shared_ptr<VideoComposition>& composition,
+                      NSMutableDictionary<NSString*, AVURLAsset*>* assetCache);
+
+AVURLAsset*
+getOrCreateAsset(const std::string& path,
+                 NSMutableDictionary<NSString*, AVURLAsset*>* assetCache);
+
+} // namespace RNSkiaVideo

package/ios/AudioCompositionUtils.mm

@@ -0,0 +1,113 @@
+#import "AudioCompositionUtils.h"
+
+namespace RNSkiaVideo {
+
+NS_INLINE NSError* audioErrorWithMessage(NSString* message) {
+  return [NSError errorWithDomain:@"com.azzapp.rnskv"
+                             code:0
+                         userInfo:@{NSLocalizedDescriptionKey : message}];
+}
+
+AVURLAsset*
+getOrCreateAsset(const std::string& path,
+                 NSMutableDictionary<NSString*, AVURLAsset*>* assetCache) {
+  NSString* nsPath =
+      [NSString stringWithCString:path.c_str()
+                         encoding:[NSString defaultCStringEncoding]];
+  AVURLAsset* asset = assetCache ? assetCache[nsPath] : nil;
+  if (!asset) {
+    asset = [AVURLAsset URLAssetWithURL:[NSURL fileURLWithPath:nsPath]
+                                options:nil];
+    if (assetCache) {
+      assetCache[nsPath] = asset;
+    }
+  }
+  return asset;
+}
+
+AudioComposition
+buildAudioComposition(const std::shared_ptr<VideoComposition>& composition,
+                      NSMutableDictionary<NSString*, AVURLAsset*>* assetCache) {
+  AVMutableComposition* audioComposition = [AVMutableComposition composition];
+  NSMutableArray<AVAudioMixInputParameters*>* inputParameters =
+      [NSMutableArray array];
+  bool hasTracks = false;
+  for (const auto& item : composition->items) {
+    if (!item->audioEnabled) {
+      continue;
+    }
+    AVURLAsset* asset = getOrCreateAsset(item->path, assetCache);
+    AVAssetTrack* audioTrack =
+        [[asset tracksWithMediaType:AVMediaTypeAudio] firstObject];
+    if (!audioTrack) {
+      if (!item->isVideo) {
+        throw audioErrorWithMessage(
+            [NSString stringWithFormat:@"No audio track for path: %s",
+                                       item->path.c_str()]);
+      }
+      continue;
+    }
+
+    CMTime startTime = CMTimeMakeWithSeconds(item->startTime, NSEC_PER_SEC);
+    auto sourceRange = CMTimeRangeGetIntersection(
+        CMTimeRangeMake(startTime,
+                        CMTimeMakeWithSeconds(item->duration, NSEC_PER_SEC)),
+        audioTrack.timeRange);
+    if (CMTimeCompare(sourceRange.duration, kCMTimeZero) <= 0) {
+      continue;
+    }
+
+    AVMutableCompositionTrack* compositionTrack = [audioComposition
+        addMutableTrackWithMediaType:AVMediaTypeAudio
+                    preferredTrackID:kCMPersistentTrackID_Invalid];
+    // If the audio track starts after the requested start time, keep the
+    // offset so the audio stays aligned on the composition timeline.
+    CMTime insertTime = CMTimeAdd(
+        CMTimeMakeWithSeconds(item->compositionStartTime, NSEC_PER_SEC),
+        CMTimeSubtract(sourceRange.start, startTime));
+    NSError* insertError = nil;
+    if (![compositionTrack insertTimeRange:sourceRange
+                                   ofTrack:audioTrack
+                                    atTime:insertTime
+                                     error:&insertError]) {
+      throw insertError
+          ?: audioErrorWithMessage([NSString
+                 stringWithFormat:@"Could not insert audio track for item: %s",
+                                  item->id.c_str()]);
+    }
+    hasTracks = true;
+
+    if (item->audioVolume != 1.0) {
+      AVMutableAudioMixInputParameters* parameters =
+          [AVMutableAudioMixInputParameters
+              audioMixInputParametersWithTrack:compositionTrack];
+      [parameters setVolume:MAX(0.0, MIN(1.0, item->audioVolume))
+                     atTime:kCMTimeZero];
+      [inputParameters addObject:parameters];
+    }
+  }
+
+  if (!hasTracks) {
+    return {nil, nil};
+  }
+
+  // The playback clock is driven by the audio player: the composition is
+  // padded with silence so the playhead can run the whole timeline and go
+  // past its duration (completion detection).
+  CMTime paddedDuration =
+      CMTimeMakeWithSeconds(composition->duration + 0.5, NSEC_PER_SEC);
+  if (CMTimeCompare(audioComposition.duration, paddedDuration) < 0) {
+    [audioComposition
+        insertEmptyTimeRange:CMTimeRangeFromTimeToTime(
+                                 audioComposition.duration, paddedDuration)];
+  }
+
+  AVMutableAudioMix* audioMix = nil;
+  if (inputParameters.count > 0) {
+    audioMix = [AVMutableAudioMix audioMix];
+    audioMix.inputParameters = inputParameters;
+  }
+  return {audioComposition, audioMix};
+}
+
+} // namespace RNSkiaVideo

package/ios/DecoderWindow.h

@@ -0,0 +1,52 @@
+#pragma once
+
+namespace RNSkiaVideo {
+
+/**
+ * When an item's decoder is open, for a composition with lazy decoders: from a
+ * little before the item starts to a little after it ends. Without lazy
+ * decoders every decoder is open for the life of the player. Same numbers as
+ * android/.../DecoderWindow.java.
+ */
+class DecoderWindow {
+public:
+  DecoderWindow(bool lazy, bool realTime)
+      : lazy(lazy), lead(realTime ? kPreviewLead : kExportLead) {}
+
+  bool isLazy() const { return lazy; }
+
+  bool opens(double start, double end, double position, double duration,
+             bool looping) const {
+    return !lazy || within(start - lead, end, position, duration, looping);
+  }
+
+  /** Wider than opens, so an item is never closed and reopened at one edge. */
+  bool keeps(double start, double end, double position, double duration,
+             bool looping) const {
+    return !lazy || within(start - lead - kMargin, end + kMargin, position,
+                           duration, looping);
+  }
+
+private:
+  // The preview has to open a reader and decode the first frame before the
+  // item is on screen; the export waits for it anyway. Chosen, not measured.
+  static constexpr double kPreviewLead = 1.5;
+  static constexpr double kExportLead = 0.5;
+  // Kept a little past both ends, so a scrub across a cut does not reopen it.
+  static constexpr double kMargin = 0.5;
+
+  bool lazy;
+  double lead;
+
+  static bool within(double from, double to, double position, double duration,
+                     bool looping) {
+    if (position >= from && position < to) {
+      return true;
+    }
+    // Near the end of a loop, the items at the start come next.
+    double wrapped = position - duration;
+    return looping && wrapped >= from && wrapped < to;
+  }
+};
+
+} // namespace RNSkiaVideo