vos-remix

Ein vos-Programm remixen

Jedes Video auf vos.so/gallery ist ein Programm: Eingaben + eine deterministische Funktion → Video. Remixen bedeutet, die JSON-Konfiguration des Programms zu bearbeiten und das Ergebnis als privates vos auf dem Benutzerkonto mit Abstammung zurückzupushen. Du bearbeitest lokal; die Plattform validiert, kompiliert und rendert eine Vorschau.

Einrichtung

npm i -D @vosjs/cli   # der Fetch/Check/Push/Pull-Zyklus

Für diesen Zyklus wird kein Browser benötigt (das Rendern von Vorschauen erfolgt auf der Plattform). Alles funktioniert auch als einfaches HTTP, falls die CLI nicht verfügbar ist: references/remix-contract.md dokumentiert jeden Endpunkt.

Anmeldedaten (niemals ausgeben)

Zwei Formen, beide verwendet als Authorization: Bearer:

1. Remix-Grant (vos_rg_…) – wenn die Eingabeaufforderung des Benutzers einen enthält, verwende ihn. 24h Gültigkeit, gebunden an EIN Quell-vos, max. 5 Pushes.
2. Dauerhafter Schlüssel (vos_sk_…) – Auflösungsreihenfolge vor dem Nachfragen: VOS_API_KEY-Umgebungsvariable, dann die erste Zeile von ~/.config/vos/credentials. Menschen erstellen Schlüssel unter https://vos.so/app/api.
3. Keine Anmeldedaten – der beanspruchbare Push (nur Programme):

   vos push my-remix.json --claimable --title "My remix"
   # → claim: https://vos.so/claim/…   expires: <72h ab jetzt>
   
   # Keine CLI oder eine ältere? Das Gleiche über einfaches HTTP:
   curl -s -X POST https://vos.so/api/claim \
     -H 'content-type: application/json' \
     -d '{"title": "My remix", "config": <das VosConfigJson>}'
   # → { "claimUrl": "https://vos.so/claim/…", "expiresAt": "…" }
   

   Übergib claimUrl dem Benutzer und niemandem sonst – es ist der einzige Verweis und die einzige Berechtigung. Der Link hält 72 Stunden; nicht beanspruchte Arbeit wird danach gelöscht (bewusste Bereinigung, kein Datenverlust – erneut pushen, falls es abläuft). Das Beanspruchen verschiebt das vos in die Bibliothek des Benutzers und startet seine gehostete Vorschau; die Iteration nach dem Anspruch verwendet seinen Schlüssel (der Zyklus unten). Grenzen: Konfiguration ≤200KB, 5 Pushes pro Tag pro Netzwerk.

Die CLI löst Grants und Schlüssel automatisch auf (export VOS_API_KEY=…). Keine Form kann veröffentlichen: Gepushte Voses bleiben privat, bis ein Mensch sie auf vos.so veröffentlicht.

Der Zyklus

1. Holen des Quellprogramms (öffentliche Programme benötigen keine Authentifizierung):

   vos fetch https://vos.so/vos/<id>        # oder die bloße ID
   # → <slug>/config.json (Parameter erhalten) + <slug>/vos.json (Nachverfolgung)
   

2. Bearbeiten von config.json lokal. Die Funktionsfelder (setup, createContent, createTimeline, onFrame) sind JavaScript als Zeichenketten – keine TypeScript-Syntax, keine ${}-Template-Interpolation. Ändere 1–2 Achsen entschlossen (Palette, Bewegungsgrammatik, Dichte) – niemals eine 10%-Anpassungskopie. Wenn das Programm params deklariert, bevorzuge das Nachjustieren oder Erweitern dieser Knöpfe gegenüber einem Eingriff in die Funktionszeichenketten.

3. Deklarieren von Knöpfen und Looks – die Steueroberfläche des Remixes. 2–4 zweckbenannte Parameter plus 2–3 Voreinstellungen. Dies ist ein Handwerk mit Regeln: references/params-knobs.md.

4. Überprüfen lokal vor dem Pushen:

   vos check <slug>/config.json     # migrieren → Schema → Syntax → kompilieren → Lints
   vos still <slug>/config.json probe.webp --time 2   # AUSFÜHREN – Kompilierung prüfen
                                    # aber das Modul niemals ausführen; ein Laufzeit-
                                    # Fehler (ein TDZ gegen die eigenen Deklarationen
                                    # der Funktion) wird allein beim Check unsichtbar
                                    # übertragen. Rendere nach jeder Code-Änderung,
                                    # vor jedem Push ein Standbild.
   

   Behebe jeden Fehler; behandle Determinismus-Warnungen ernst (eine Konfiguration, die pro Durchlauf anders rendert, ist per Definition defekt).

5. Pushen als privates vos mit Abstammung (die CLI liest vos.json neben der Konfiguration für die remixOfId-Gutschrift):

   vos push <slug>/config.json --title "Aurora Ribbons – Dämmerung"
   # → Privates vos <id> erstellt
   #   watch:  https://vos.so/vos/<id>
   #   studio: https://vos.so/studio?vos=<id>
   

6. Iterieren – weitere Bearbeitungen werden zu Versionen desselben vos:

   vos push <slug>/config.json --vos <id> --note "kühlere Palette, langsamerer Drift"
   

   Das Verzeichnis VERFOLGT sein vos durch vos.json, sodass die Basisversion automatisch mitgeführt wird: Wenn der Mensch seit deinem letzten Push im Studio bearbeitet hat, wird der Push MIT deren eingegebenem Änderungsprotokoll abgelehnt. --note ist deine Übergabezeile – sie wird vom Menschen zuerst gelesen; --label benennt die Version.

7. Ziehen vor jeder Bearbeitungsrunde – der Mensch könnte nachjustiert haben:

   vos pull <slug>          # was sich seit deiner Basis geändert hat, dann synchronisieren
   

   Gibt jede Version mit Quellenangabe aus (v3 (studio · wärmer): Knopf hue 0,2→0,35 plus deren Notizen), synchronisiert config.json auf den neuesten Stand (deine vorherige Kopie wird als config.backup.json aufbewahrt) und setzt die Basis neu. Vom Menschen bearbeitete Knoten sind geschützt: Ein Push, der sie berührt, wird abgelehnt, es sei denn, du übergibst --override <id> – tue das NUR, wenn die Anweisung des Benutzers ausdrücklich diesen Knoten betrifft. Ihre Drehungen an deinen Knöpfen sind Präferenzdaten: lies das Änderungsprotokoll, bevor du entscheidest, was als Nächstes zu tun ist.

8. Gib BEIDE Links zurück – die Beobachtungsseite (Vorschau, Knöpfe, Code) und das Studio (https://vos.so/studio?vos=<id>), wo der Benutzer deine Knöpfe live nachjustieren kann. Das Veröffentlichen ist seine Handlung, auf vos.so.

Regeln, die Pushes ehrlich halten

• Privat ist der Vertrag. Versuche niemals visibility: "public" – es wird auf privat gesetzt, und das Veröffentlichen per Schlüssel wird bewusst abgelehnt.
• Kontingentbewusst: Dauerhafte Schlüssel erstellen ≤50 Voses/24h; Grants pushen ≤5. Iteriere Versionen auf einem vos anstatt viele Voses zu erstellen.
• Server-Rendering-Einschränkungen (die Vorschau-Flotte verwendet Software-GL): kein THREE.DoubleSide bei Transmissionsmaterialien, keine dispersion, und jedes abgerufene Asset muss eine absolute https-URL sein, die die Flotte erreichen kann.
• Jeder Knopf muss wirken. Ein Parameter, den der Code nie liest, ist schlimmer als kein Parameter – siehe den Ehrlichkeitsabschnitt von references/params-knobs.md.
• 3D-Modell-Austausch (GLB in ein Showcase-Programm): references/3d-recipe.md.
• Vollständige Endpunkt-Referenz, Kontingente und Fehlertabelle: references/remix-contract.md.