vos-remix

Remixar um programa vos

Todo vídeo em vos.so/gallery é um programa: entradas + uma função determinística → vídeo. Remixar é editar a configuração JSON desse programa e enviar o resultado de volta como um vos privado na conta do usuário, com linhagem. Você edita localmente; a plataforma valida, compila e renderiza uma prévia.

Configuração

npm i -D @vosjs/cli   # o loop de fetch/check/push/pull

Nenhum navegador é necessário para este loop (a renderização de prévias acontece na plataforma). Tudo também funciona como HTTP simples se o CLI não estiver disponível: references/remix-contract.md documenta cada endpoint.

Credenciais (nunca as imprima)

Duas formas, ambas usadas como Authorization: Bearer:

1. Concessão de remix (vos_rg_…) — se o prompt do usuário contiver uma, use-a. Vida útil de 24h, vinculada a UM vos de origem, máximo de 5 envios.
2. Chave durável (vos_sk_…) — ordem de resolução antes de perguntar: env VOS_API_KEY, depois a primeira linha de ~/.config/vos/credentials. Humanos criam chaves em https://vos.so/app/api.
3. Nenhuma credencial — o envio reivindicável (apenas programas):

   vos push my-remix.json --claimable --title "Meu remix"
   # → claim: https://vos.so/claim/…   expires: <72h a partir de agora>
   
   # Sem CLI, ou uma versão antiga? A mesma coisa via HTTP simples:
   curl -s -X POST https://vos.so/api/claim \
     -H 'content-type: application/json' \
     -d '{"title": "Meu remix", "config": <o VosConfigJson>}'
   # → { "claimUrl": "https://vos.so/claim/…", "expiresAt": "…" }
   

   Entregue claimUrl ao usuário e a ninguém mais — é a única referência e a única credencial. O link dura 72 horas; o trabalho não reivindicado é excluído após esse período (limpeza deliberada, não perda de dados — re-envie se expirar). Reivindicar move o vos para a biblioteca do usuário e inicia sua prévia hospedada; iteração após a reivindicação usa a chave do usuário (o loop abaixo). Limites: config ≤200KB, 5 envios por dia por rede.

O CLI resolve concessões e chaves automaticamente (export VOS_API_KEY=…). Nenhuma forma pode publicar: voses enviados permanecem privados até que um humano publique em vos.so.

O loop

1. Busque o programa fonte (programas públicos não precisam de autenticação):

   vos fetch https://vos.so/vos/<id>        # ou o id puro
   # → <slug>/config.json (params preservados) + <slug>/vos.json (rastreamento)
   

2. Edite config.json localmente. Os campos de função (setup, createContent, createTimeline, onFrame) são JavaScript como strings — sem sintaxe TypeScript, sem interpolação de template ${}. Altere 1–2 eixos de forma decisiva (paleta, gramática de movimento, densidade) — nunca uma duplicata de ajuste de 10%. Se o programa declarar params, prefira reajustar ou estender esses controles a cirurgia nas strings de função.

3. Declare knobs e Looks — a superfície de controle do remix. 2–4 params com nomes intencionais mais 2–3 presets. Isso é uma arte com regras: references/params-knobs.md.

4. Verifique localmente antes de enviar:

   vos check <slug>/config.json     # migra → esquema → sintaxe → compila → lints
   vos still <slug>/config.json probe.webp --time 2   # EXECUTE — check compila
                                    # mas nunca executa o módulo; um lançamento
                                    # em tempo de execução (um TDZ contra as próprias declarações
                                    # da função) viaja invisivelmente apenas com check.
                                    # Renderize um still após cada edição de
                                    # código, antes de cada envio.
   

   Corrija todos os erros; trate avisos de determinismo com seriedade (uma configuração que renderiza diferente a cada execução é quebrada por definição).

5. Envie como um vos privado com linhagem (o CLI lê vos.json ao lado da configuração para o crédito remixOfId):

   vos push <slug>/config.json --title "Fitas Aurora — entardecer"
   # → Vos privado criado <id>
   #   veja:  https://vos.so/vos/<id>
   #   estúdio: https://vos.so/studio?vos=<id>
   

6. Itere — edições posteriores tornam-se versões do mesmo vos:

   vos push <slug>/config.json --vos <id> --note "paleta mais fria, deriva mais lenta"
   

   O diretório RASTREIA seu vos através de vos.json, então a versão base é carregada automaticamente: se o humano editou no estúdio desde seu último envio, o envio é REJEITADO COM o changelog digitado deles. --note é sua linha de entrega — é o que o humano lê primeiro; --label nomeia a versão.

7. Puxe antes de cada rodada de edição — o humano pode ter ajustado:

   vos pull <slug>          # o que mudou desde sua base, depois sincroniza
   

   Imprime cada versão atribuída (v3 (estúdio · mais quente): knob matiz 0.2→0.35 mais suas notas), sincroniza config.json para a cabeça (sua cópia anterior é mantida como config.backup.json) e redireciona a base. Nós editados pelo humano são protegidos: um envio que os toca é rejeitado a menos que você passe --override <id> — faça isso APENAS quando a instrução do usuário visar explicitamente aquele nó. As alterações deles em seus knobs são dados de preferência: leia o changelog antes de decidir o que fazer em seguida.

8. Entregue AMBOS os links — a página de visualização (prévia, knobs, código) e o estúdio (https://vos.so/studio?vos=<id>) onde o usuário ajusta seus knobs ao vivo. Publicar é ação deles, em vos.so.

Regras que mantêm os envios honestos

• Privado é o contrato. Nunca tente visibility: "public" — ele restringe para privado, e publicar por chave é rejeitado por design.
• Ciente de cota: chaves duráveis criam ≤50 voses/24h; concessões enviam ≤5. Itere versões em um vos em vez de criar muitos voses.
• Restrições de renderização do servidor (a frota de prévias é software-GL): sem THREE.DoubleSide em materiais de transmissão, sem dispersion, e cada ativo buscado deve ser uma URL https absoluta que a frota possa alcançar.
• Cada knob deve agir. Um param que o código nunca lê é pior do que nenhum param — veja a seção de honestidade de references/params-knobs.md.
• Trocas de modelo 3D (GLB em um programa de vitrine): references/3d-recipe.md.
• Referência completa de endpoint, cotas e tabela de erros: references/remix-contract.md.