vos-remix

Reutilizar un programa de vos

Cada video en vos.so/gallery es un programa: entradas + una función determinista → video. Reutilizar (remix) es editar la configuración JSON de ese programa y enviar el resultado de vuelta como un vos privado en la cuenta del usuario, con linaje. Editas localmente; la plataforma valida, compila y genera una vista previa.

Configuración

npm i -D @vosjs/cli   # el ciclo fetch/check/push/pull

No se necesita navegador para este ciclo (la generación de vistas previas ocure en la plataforma). Todo funciona también como HTTP plano si la CLI no está disponible: references/remix-contract.md documenta cada endpoint.

Credenciales (nunca imprimirlas)

Dos formatos, ambos usados como Authorization: Bearer:

1. Grant de remix (vos_rg_…) — si el prompt del usuario contiene uno, úsalo. Duración 24 h, vinculado a UN programa fuente, máximo 5 envíos (pushes).
2. Clave duradera (vos_sk_…) — orden de resolución antes de preguntar: la variable de entorno VOS_API_KEY, luego la primera línea de ~/.config/vos/credentials. Los humanos crean claves en https://vos.so/app/api.
3. Sin credencial alguna — el envío reclamable (solo programas):

   vos push my-remix.json --claimable --title "Mi remix"
   # → claim: https://vos.so/claim/…   expires: <72h desde ahora>
   
   # ¿Sin CLI o con una antigua? Lo mismo mediante HTTP plano:
   curl -s -X POST https://vos.so/api/claim \
     -H 'content-type: application/json' \
     -d '{"title": "Mi remix", "config": <el VosConfigJson>}'
   # → { "claimUrl": "https://vos.so/claim/…", "expiresAt": "…" }
   

   Entrega claimUrl al usuario y a nadie más: es la única referencia y la única credencial. El enlace dura 72 horas; el trabajo no reclamado se elimina después de ese tiempo (limpieza deliberada, no pérdida de datos: vuelve a enviar si caduca). Reclamar mueve el vos a la biblioteca del usuario e inicia su vista previa alojada; la iteración posterior a la reclamación utiliza su clave (el ciclo de abajo). Límites: configuración ≤200KB, 5 envíos por día por red.

La CLI resuelve grants y claves automáticamente (export VOS_API_KEY=…). Ningún formato puede publicar: los voses enviados permanecen privados hasta que un humano publique en vos.so.

El ciclo

1. Obtener el programa fuente (los programas públicos no necesitan autenticación):

   vos fetch https://vos.so/vos/<id>        # o el id solo
   # → <slug>/config.json (parámetros preservados) + <slug>/vos.json (seguimiento)
   

2. Editar config.json localmente. Los campos de función (setup, createContent, createTimeline, onFrame) son JavaScript como cadenas de texto — sin sintaxis TypeScript, sin interpolación ${}. Cambia 1–2 ejes de forma decisiva (paleta, gramática de movimiento, densidad) — nunca un duplicado de un ajuste del 10%. Si el programa declara params, prefiere reajustar o extender esos parámetros antes que modificar las cadenas de función.

3. Declarar parámetros y Looks — la superficie de control del remix. 2–4 parámetros con nombres que reflejen su intención más 2–3 preajustes. Esto es un arte con reglas: references/params-knobs.md.

4. Validar localmente antes de enviar:

   vos check <slug>/config.json     # migrar → esquema → sintaxis → compilar → lints
   vos still <slug>/config.json probe.webp --time 2   # EJECUTARLO — check compila
                                    # pero nunca ejecuta el módulo; un error
                                    # en tiempo de ejecución (un TDZ contra las declaraciones
                                    # de la propia función) se envía de forma invisible solo con
                                    # check. Renderiza un still después de cada edición
                                    # de código, antes de cada envío.
   

   Corrige cada error; trata las advertencias de determinismo con seriedad (una configuración que se renderiza diferente en cada ejecución está rota por definición).

5. Enviar como un vos privado con linaje (la CLI lee vos.json junto a la configuración para el crédito remixOfId):

   vos push <slug>/config.json --title "Cintas de aurora — atardecer"
   # → Creado vos privado <id>
   #   ver:  https://vos.so/vos/<id>
   #   estudio: https://vos.so/studio?vos=<id>
   

6. Iterar — las ediciones posteriores se convierten en versiones del mismo vos:

   vos push <slug>/config.json --vos <id> --note "paleta más fría, deriva más lenta"
   

   El directorio HACE SEGUIMIENTO de su vos mediante vos.json, por lo que la versión base se transporta automáticamente: si el humano editó en el estudio desde tu último envío, el envío es RECHAZADO con su registro de cambios escrito. --note es tu línea de entrega: es lo primero que lee el humano; --label nombra la versión.

7. Obtener (pull) antes de cada ronda de edición — el humano puede haber ajustado:

   vos pull <slug>          # qué cambió desde tu base, luego sincronizar
   

   Imprime cada versión atribuida (v3 (studio · warmer): knob hue 0.2→0.35 más sus notas), sincroniza config.json a la cabeza (tu copia anterior se conserva como config.backup.json), y reasigna la base. Los nodos editados por humanos están protegidos: un envío que los toque es rechazado a menos que pases --override <id> — haz eso SOLO cuando la instrucción del usuario apunte explícitamente a ese nodo. Sus ajustes de tus parámetros son datos de preferencia: lee el registro de cambios antes de decidir qué hacer a continuación.

8. Entregar AMBOS enlaces — la página de visualización (vista previa, parámetros, código) y el estudio (https://vos.so/studio?vos=<id>) donde el usuario ajusta tus parámetros en vivo. Publicar es su acción, en vos.so.

Reglas que mantienen los envíos honestos

• Privado es el contrato. Nunca intentes visibility: "public" — se fuerza a privado, y publicar mediante clave está rechazado por diseño.
• Consciente de cuotas: las claves duraderas crean ≤50 voses/24h; los grants envían ≤5. Itera versiones en un mismo vos en lugar de crear muchos voses.
• Restricciones de renderizado del servidor (la flota de vistas previas usa GL por software): no usar THREE.DoubleSide en materiales de transmisión, no usar dispersion, y cada recurso obtenido debe ser una URL https absoluta que la flota pueda alcanzar.
• Cada parámetro debe actuar. Un parámetro que el código nunca lee es peor que no tener parámetro — consulta la sección de honestidad en references/params-knobs.md.
• Intercambio de modelos 3D (GLB en un programa de exhibición): references/3d-recipe.md.
• Referencia completa de endpoints, cuotas y tabla de errores: references/remix-contract.md.