Criar um anim
Um anim é um arquivo, <kebab-name>@<major>.<minor>.yaml, com exatamente quatro chaves: t (o literal c), j (um módulo ES), s (CSS), h (HTML/SVG). Um player host o executa com uma API global G que fornece as sílabas, palavras, linhas, seções e batidas da música. Seu trabalho: transformar um resumo em um desses arquivos que seja correto sob seek/pause/redimensionar/tema, legível e bonito. Os caminhos abaixo são relativos a este diretório skill/.
As regras mais importantes
- Um quadro é uma função pura do tempo de reprodução.
render(t)deve desenhar a mesma imagem quer a reprodução tenha atingidotquer o usuário tenha arrastado até ele. SemMath.random,Date.now, integração acumulada ou estado "o que aconteceu no último quadro" que um seek pularia. Derive tudo dos dados da música, da semente e det. - Duas metades. Uma metade pura exportada, livre de DOM (
buildPlan,frameAt, helpers; testável por unidade) acima de um comentário de banner, depois uma metade fina de navegador (export default function (G, shadowRoot, config)) que apenas conecta e desenha. Vejaguides/architecture.md. - Registre em
default, leia dados da música emINIT.G.on/G.off/G.onFrameapenas dentro dedefault.G.map/forEach/lookup/iterator/relayoutapenas depois queINITfor disparado (um manipuladorINIT, ou callbacks posteriores comorender), nunca no própriodefault. InscrevaG.on(G.TYPE.TICK, render)para reprodução;G.onFrame({ render, reset })cobre SEEK/PLAY/PAUSE/RESIZE e UNINIT. - Limpe com
G.dispose/G.listen. Uma função retornada dedefaulté ignorada. Libere WebGL (forceContextLoss), listeners, timers, câmera. - As cores vivem no CSS, não em
c.v. Valores claros em:host, substituições escuras em[data-bs-theme=dark] { }; o canvas lê de volta com g-libcssColors. Ambos os temas devem parecer intencionais. - Nunca implemente manualmente o que g-lib já tem (clamp, lerp, easing, RNG baseado em semente, ajuste de canvas, molas, layout de texto, pools...). Importe do pin de tag exata; consulte
pitfalls/dont-hand-roll.mdespec/g-lib.mdantes de escrever qualquer helper. - Legibilidade supera o efeito. A sílaba ativa é legível em claro e escuro, no telefone e no laptop, para linhas longas, CJK, RTL e Mianmar. Grandes flashes permanecem abaixo de 3 Hz (
guides/accessibility.md). - Poucas opções tipadas.
cecSchemasão literais simples; cada opção faz algo visível.
Fluxo de trabalho (com as ferramentas do repositório)
- Resumo. Escreva o resumo de design a partir de
guides/design-brief.md: uma imagem física forte; o mecanismo; quais eventos impulsionam o quê (o mapa de sincronia); estrutura (estrofe/refrão/batida); plano de legibilidade; opções; armadilhas. Escolha o backend com sua tabela de seleção. Rejeite ideias que não possam permanecer legíveis. - Estrutura.
npm run new -- <name> --backend canvas2d|svg|dom|three(ou copietemplates/<backend>.yamlmanualmente e substitua__NAME__). - Leia uma vez:
spec/module-format.md,pitfalls/general.md, a seção do seu backend empitfalls/backends.md,pitfalls/dont-hand-roll.md. Abra qualquer outra coisa apenas através da tabela de roteamento abaixo. - Implemente primeiro a metade pura (tempo para estado), depois a metade fina do navegador.
- Valide.
npm run validate -- anims/<file>.yaml. Corrija todos os erros; justifique todos os avisos no docblock ou corrija-os. - Verifique.
npm run check -- anims/<file>.yamlmonta 13 músicas de borda headlessly, pontua a tabela de conformidade e escreve PNGs emout/<name>/. Abra os PNGs (telefone/laptop, claro/escuro). Uma tabela verde sobre um quadro feio ou ilegível é uma falha. Um WARN em uma linha de pureza de seek significa que a imagem depende do histórico: corrija ou justifique no docblock (uma simulação deliberada). - Pré-visualize (opcional).
npm run preview -- anims/<file>.yamlpara reproduzir, arrastar, alternar tema e ajustar opções. - Revise contra
guides/quality-rubric.md(20 perguntas), depois entregue o único arquivo YAML e um breve relatório (nome do arquivo, tabela de verificação final, decisões que o resumo deixou em aberto, o que você deliberadamente não fez). Não envieout/ou o harness.
Modo sem ferramentas (modelos de chat, sem shell)
Pule as etapas 2, 5-7. Comece pelo texto do modelo correspondente, escreva o resumo de design em seu raciocínio, depois percorra pitfalls/general.md, a seção do backend e a rubrica de 20 perguntas linha por linha em relação ao seu próprio código antes de responder. Produza apenas o arquivo YAML em um bloco com cerca, e mencione quais itens da rubrica você não pôde verificar sem executá-lo (pureza de seek, inversão de tema, redimensionamento).
Tabela de roteamento: abra um documento apenas quando seu gatilho se aplicar
| Quando você estiver prestes a... | Leia |
|---|---|
| decidir o que construir; escolher um backend | guides/design-brief.md |
| organizar o arquivo; nomear estágios; escrever o docblock | guides/architecture.md |
usar qualquer chamada G.*, opção de evento ou intervalo de id | spec/events.md, spec/event-shapes.md, spec/g.d.ts |
| adicionar opções, cores, temas | spec/config.md |
| usar utilitários de tempo, medição de texto, helpers de canvas, ciclo de vida | spec/utilities.md |
| dividir linhas em linhas de exibição, quebrar texto | spec/relayout.md, guides/patterns-text.md |
| acionar coisas em sílabas/linhas/batidas; pré-criar; pausar; molas | guides/patterns-timing.md |
| ajustar, destacar ou estilizar texto; scripts não latinos | guides/patterns-text.md |
| escrever código de renderização (DOM, SVG, canvas, three, simulação, camadas) | guides/patterns-render.md, pitfalls/backends.md |
| câmera, terreno, enxames, empacotamento, 3D procedural | guides/techniques.md, pitfalls/techniques.md |
| usar uma foto ou câmera | spec/image-input.md |
| construir um jogo (autoPlay false, pontuação, estados) | guides/games.md |
| usar qualquer helper g-lib | spec/g-lib.md |
| sentir dúvidas sobre flash, movimento, contraste | guides/accessibility.md |
| terminar | guides/quality-rubric.md |
Forma mínima (não envie isto; comece a partir de um modelo)
"t": |-
c
"j": |
import { hash01 } from 'https://cdn.jsdelivr.net/gh/prjctg/[email protected]/index.js';
/* [email protected]: <uma linha>
* 1. <reivindicação de design numerada: o mecanismo e a resposta errada tentadora que ele rejeita> */
export function frameAt(plan, t) { /* puro */ }
/* Metade do navegador. Tudo acima desta linha é intencionalmente livre de DOM. */
export default function (G, shadowRoot, config) {
const cfg = G.cfg(config, { channel: G.cfg.int(0) });
let ready = false;
const render = (t) => { if (!ready) return; /* desenha frameAt(plan, t) */ };
G.on(G.TYPE.INIT, () => { ready = true; /* G.map(...) é válido aqui */ });
G.on(G.TYPE.TICK, render);
G.onFrame({ render, reset() { ready = false; } });
}
export const c = { v: { fadeMs: 150 }, m: [{ s: 'fadeMs', t: 'fadeMs' }] };
export const cSchema = [{ i: 'fadeMs', n: 'Fade (ms)', t: 'int', mn: 0, mx: 2000 }];
"s": |
:host { display: block; --ink: var(--inkColor, #111); }
[data-bs-theme=dark] { --ink: var(--inkColor, #eee); }
"h": |
<canvas id="c"></canvas>
j, s, h contêm texto bruto (nunca envolvido em crases ou aspas). t usa |-. O nome do arquivo carrega a versão; nunca edite uma versão publicada no local.