vos-remix

Remixer un programme vos

Chaque vidéo sur vos.so/gallery est un programme : entrées + une fonction déterministe → vidéo. Remixer, c'est éditer la configuration JSON de ce programme et pousser le résultat en tant que vos privé sur le compte de l'utilisateur, avec filiation. Vous éditez localement ; la plateforme valide, compile et génère un aperçu.

Configuration

npm i -D @vosjs/cli   # la boucle fetch/check/push/pull

Aucun navigateur n'est nécessaire pour cette boucle (le rendu des aperçus se fait sur la plateforme). Tout fonctionne également en HTTP simple si le CLI n'est pas disponible : references/remix-contract.md documente chaque point d'accès.

Identifiants (ne jamais les afficher)

Deux formes, toutes deux utilisées comme Authorization: Bearer :

1. Remix grant (vos_rg_…) — si l'invite de l'utilisateur en contient une, utilisez-la. Durée de vie 24h, liée à UN seul vos source, max 5 poussées.
2. Clé durable (vos_sk_…) — ordre de résolution avant de demander : variable d'environnement VOS_API_KEY, puis première ligne de ~/.config/vos/credentials. Les humains créent des clés sur https://vos.so/app/api.
3. Aucun identifiant — la poussée réclamable (programmes uniquement) :

   vos push mon-remix.json --claimable --title "Mon remix"
   # → claim: https://vos.so/claim/…   expires: <72h à partir de maintenant>
   
   # Pas de CLI, ou une version ancienne ? La même chose en HTTP simple :
   curl -s -X POST https://vos.so/api/claim \
     -H 'content-type: application/json' \
     -d '{"title": "Mon remix", "config": <le VosConfigJson>}'
   # → { "claimUrl": "https://vos.so/claim/…", "expiresAt": "…" }
   

   Transmettez claimUrl à l'utilisateur et nulle part ailleurs — c'est la seule référence et le seul identifiant. Le lien dure 72 heures ; le travail non réclamé est supprimé après ce délai (nettoyage délibéré, pas une perte de données — repoussez s'il expire). Réclamer déplace le vos dans la bibliothèque de l'utilisateur et démarre son aperçu hébergé ; l'itération après réclamation utilise sa clé (la boucle ci-dessous). Limites : config ≤200 Ko, 5 poussées par jour par réseau.

Le CLI résout automatiquement les grants et les clés (export VOS_API_KEY=…). Aucune forme ne peut publier : les voses poussés restent privés jusqu'à ce qu'un humain publie sur vos.so.

La boucle

1. Récupérer le programme source (les programmes publics ne nécessitent pas d'authentification) :

   vos fetch https://vos.so/vos/<id>        # ou l'id brut
   # → <slug>/config.json (paramètres conservés) + <slug>/vos.json (suivi)
   

2. Éditer config.json localement. Les champs de fonction (setup, createContent, createTimeline, onFrame) sont du JavaScript sous forme de chaînes — pas de syntaxe TypeScript, pas d'interpolation ${} de template. Modifiez 1 à 2 axes de manière décisive (palette, grammaire de mouvement, densité) — jamais une copie avec une modification de 10 %. Si le programme déclare des params, privilégiez le réglage ou l'extension de ces boutons plutôt que la chirurgie des chaînes de fonction.

3. Déclarer les boutons et les Looks — la surface de contrôle du remix. 2 à 4 paramètres nommés par intention plus 2 à 3 préréglages. C'est un art avec des règles : references/params-knobs.md.

4. Vérifier localement avant de pousser :

   vos check <slug>/config.json     # migration → schéma → syntaxe → compilation → vérifications
   vos still <slug>/config.json probe.webp --time 2   # EXÉCUTEZ-le — check compile
                                    # mais n'exécute jamais le module ; une erreur
                                    # d'exécution (un TDZ contre ses propres déclarations
                                    # de fonction) est transmise de manière invisible
                                    # par check seul. Générez une image fixe après chaque
                                    # modification de code, avant chaque poussée.
   

   Corrigez toutes les erreurs ; traitez les avertissements de déterminisme avec sérieux (une configuration qui s'affiche différemment à chaque exécution est cassée par définition).

5. Pousser en tant que vos privé avec filiation (le CLI lit vos.json à côté du config pour le crédit remixOfId) :

   vos push <slug>/config.json --title "Rubans d'Aurore — crépuscule"
   # → Vos privé créé <id>
   #   watch:  https://vos.so/vos/<id>
   #   studio: https://vos.so/studio?vos=<id>
   

6. Itérer — les modifications ultérieures deviennent des versions du même vos :

   vos push <slug>/config.json --vos <id> --note "palette plus froide, dérive plus lente"
   

   Le répertoire SUIT son vos via vos.json, donc la version de base est transportée automatiquement : si l'humain a édité dans le studio depuis votre dernière poussée, la poussée est REJETÉE avec son journal de modifications tapé. --note est votre ligne de transmission — c'est ce que l'humain lit en premier ; --label nomme la version.

7. Tirer avant chaque session d'édition — l'humain a peut-être affiné :

   vos pull <slug>          # ce qui a changé depuis votre base, puis synchroniser
   

   Affiche chaque version attribuée (v3 (studio · warmer): bouton teinte 0.2→0.35 plus leurs notes), synchronise config.json avec la tête (votre copie précédente est conservée comme config.backup.json), et repointe la base. Les nœuds édités par l'humain sont protégés : une poussée qui les touche est rejetée sauf si vous passez --override <id> — faites cela UNIQUEMENT lorsque l'instruction de l'utilisateur cible explicitement ce nœud. Leurs réglages de vos boutons sont des données de préférence : lisez le journal des modifications avant de décider quoi faire ensuite.

8. Transmettre LES DEUX liens — la page de visualisation (aperçu, boutons, code) et le studio (https://vos.so/studio?vos=<id>) où l'utilisateur peut affiner vos boutons en direct. La publication est leur action, sur vos.so.

Règles pour des poussées honnêtes

• Privé est le contrat. N'essayez jamais visibility: "public" — cela force le privé, et la publication par clé est rejetée par conception.
• Respect des quotas : les clés durables créent ≤50 voses/24h ; les grants poussent ≤5. Itérez les versions sur un seul vos plutôt que de créer de nombreux voses.
• Contraintes de rendu serveur (la flotte d'aperçus utilise du GL logiciel) : pas de THREE.DoubleSide sur les matériaux de transmission, pas de dispersion, et chaque ressource récupérée doit être une URL https absolue accessible par la flotte.
• Chaque bouton doit agir. Un paramètre que le code ne lit jamais est pire qu'aucun paramètre — voir la section sur l'honnêteté de references/params-knobs.md.
• Échanges de modèles 3D (GLB dans un programme vitrine) : references/3d-recipe.md.
• Référence complète des points d'accès, quotas et table d'erreurs : references/remix-contract.md.