Uma calculadora de quatro operações cujo teclado se comporta como a superfície do oceano: cada tecla acompanha um marulho vertical contínuo, com cristas viajando em diagonal pelo convés, enquanto a calculadora permanece totalmente funcional e acessível. A peça é também uma vitrine de orquestração do anime.js v4 — stagger em grade, loops sem emenda, interrupção por tecla — envolta em uma identidade visual pirata: convés de madeira, teclas de latão, visor de pergaminho.
Usuário final — o bucaneiro operando a calculadora
Desenvolvedor frontend que mantém a demo
Toda animação contínua e interativa é implementada com anime.js v4, fixado em 4.3.5. Nenhuma outra biblioteca de animação e nenhum loop artesanal de requestAnimationFrame para o marulho.
As animações de onda e de pressionamento só podem tocar propriedades amigáveis ao compositor: transform (translateY, scale) e opacity. Animar top, margin ou height é proibido — dispararia layout a cada frame.
HTML, CSS e módulos ES puros sob demos/pirate-calculator/. O anime.js chega como import ESM fixado via CDN; servir a pasta a partir de qualquer servidor estático é toda a toolchain.
A calculadora deve permanecer totalmente operável com a onda desabilitada: navegação por teclado, estados de foco visíveis, nomes acessíveis em cada tecla e suporte a prefers-reduced-motion são inegociáveis.
the system shall disponibilizar os dígitos 0-9, o ponto decimal e as quatro operações (soma, subtração, multiplicação, divisão), avaliadas com semântica de execução imediata: cada pressionamento de operador aplica a operação pendente antes de armar a próxima.
When o usuário ativa uma tecla na tela por ponteiro, toque ou Enter/Espaço com a tecla em foco, the system shall registrar exatamente um evento de entrada e refleti-lo no visor em até 100 ms.
When o usuário pressiona uma tecla física mapeada (dígitos, ponto decimal, + - * /, Enter, =, Escape, Backspace), the system shall rotear a entrada pelo mesmo caminho do engine usado pela tecla equivalente na tela e espelhar o estado pressionado naquela tecla.
the system shall exibir a entrada atual ou o resultado alinhado à direita no visor de pergaminho, limitado a 12 dígitos significativos, com overflow renderizado em notação científica.
When o usuário ativa a tecla de limpar ou pressiona Escape, the system shall reiniciar o engine ao estado inicial e exibir 0 no visor.
If o usuário solicita uma divisão por zero, then the system shall exibir a mensagem 'Não se reparte o butim entre zero piratas!' no visor e tratar a próxima entrada como o início de uma nova digitação.
the system shall manter todas as teclas da calculadora oscilando verticalmente (translateY entre crista e cavado) em um loop sem emenda sempre que a onda estiver habilitada.
the system shall derivar a fase de oscilação de cada tecla a partir de sua linha e coluna na grade, de modo que uma crista viaje visivelmente em diagonal pelo teclado, como um marulho cruzando a superfície.
When o usuário pressiona uma tecla, the system shall interromper o marulho daquela tecla com uma animação de mergulho (a tecla afunda abaixo do cavado e retorna com efeito de mola) e então reencaixá-la na onda coletiva sem salto visível de posição.
O anime.js v4 (fixado em 4.3.5) substitui o export default anime() da v3 por exports nomeados: animate(), createTimeline(), stagger(), utils, engine. stagger() aceita uma opção grid — stagger(valor, { grid: [colunas, linhas], from: índice }) — que produz atrasos por alvo formando uma frente radial ou diagonal, exatamente a fonte de fase de que o FR-7 precisa. Loops emendam sem costura com loop true mais alternate true, e uma única tecla pode ser animada por uma chamada animate() separada que assume precedência — a primitiva de interrupção da qual o FR-8 depende. A maioria dos resultados de busca ainda mostra sintaxe v3; trate snippets v3 como uma armadilha conhecida (ver Riscos nas tarefas).
No escopo: uma página de demonstração estática sob demos/pirate-calculator/ entregando uma calculadora de quatro operações com execução imediata, o teclado com marulho oceânico contínuo, o feedback de mergulho no pressionamento, a tematização pirata, a entrada por teclado físico e o suporte a movimento reduzido. Fora do escopo: funções científicas, histórico de expressões, som, persistência, i18n e qualquer tooling de build. A spec também serve como exemplo de referência do formato visual-spec conduzindo uma pequena feature de frontend.
FR-6/FR-7 precisam de todas as teclas oscilando em um loop sem emenda, com fase por tecla derivada da posição na grade, e o FR-8 precisa de interrupção por tecla e reencaixe suave. O mandato de implementação é anime.js. Três técnicas competem para conduzir o marulho.
animate() com loop mais alternate e stagger({ grid }) entrega a frente de fase diagonal de forma declarativa, a interrupção por tecla é de primeira classe (anima-se a tecla pressionada isoladamente e depois ela é devolvida ao coletivo), e um único controlador pode pausar ou encerrar o loop quando prefers-reduced-motion muda. Keyframes CSS descumprem o mandato e tornam o reencaixe pós-pressionamento travado; um loop rAF artesanal reimplementa a biblioteca que a demo existe para demonstrar.
| Criterion | loop animate() do anime.js com stagger em grade✓ chosen | keyframes CSS com animation-delay por tecla | loop senoidal artesanal com requestAnimationFrame |
|---|---|---|---|
| aderência ao mandato do anime.jsweight 5 |
10 × 5 = 50
|
1 × 5 = 5
|
2 × 5 = 10
|
| controle de fase da onda viajanteweight 4 |
9 × 4 = 36
opção grid do stagger
|
6 × 4 = 24
|
10 × 4 = 40
|
| interrupção do pressionamento e reencaixeweight 4 |
9 × 4 = 36
|
3 × 4 = 12
|
8 × 4 = 32
|
| controle de ciclo de vida para movimento reduzidoweight 3 |
9 × 3 = 27
|
6 × 3 = 18
|
7 × 3 = 21
|
| folga de desempenhoweight 3 |
8 × 3 = 24
|
9 × 3 = 27
|
7 × 3 = 21
|
| Total | 173 | 86 | 124 |
Tarefa 4 · Tarefa 5 · Tarefa 6
O FR-1 precisa de aritmética de quatro operações com UX previsível de calculadora, o FR-9 precisa de um caminho tematizado para divisão por zero, e o engine deve ser testável unitariamente, isolado do DOM e da camada de animação.
Uma máquina de estados pura (estados: entering-first, operator-staged, entering-second, result, error) avalia a cada pressionamento de operador exatamente como uma calculadora de mesa clássica, dispensa eval e é testada unitariamente como um módulo comum. Shunting-yard adiciona uma precedência que a UX de quatro operações não quer; eval é um beco sem saída de segurança e de testabilidade.
| Criterion | máquina de estados finitos com execução imediata✓ chosen | string de expressão avaliada com Function/eval | tokenizador com parser de precedência shunting-yard |
|---|---|---|---|
| corretude e testabilidadeweight 5 |
9 × 5 = 45
|
4 × 5 = 20
|
9 × 5 = 45
|
| segurança (sem eval)weight 4 |
10 × 4 = 40
|
2 × 4 = 8
|
10 × 4 = 40
|
| aderência à UX de calculadora de quatro operaçõesweight 4 |
10 × 4 = 40
|
6 × 4 = 24
|
5 × 4 = 20
precedência de operadores surpreende usuários de calculadoras de mesa clássicas
|
| esforço de implementaçãoweight 3 |
9 × 3 = 27
|
8 × 3 = 24
|
5 × 3 = 15
|
| Total | 152 | 76 | 120 |
Tarefa 2 · Tarefa 3
A demo deve rodar em qualquer lugar onde o repo seja clonado, sem etapa de build, mantendo o anime.js fixado em uma versão sabidamente boa (4.3.5).
Importar animate e stagger da URL ESM do jsDelivr fixada em animejs@4.3.5 mantém a demo como uma pasta com poucos arquivos escritos à mão. Se o CDN estiver inacessível, a página ainda renderiza uma calculadora estática e totalmente funcional (o controlador da onda vira no-op), o que também serve como o caminho de código do movimento reduzido.
| Criterion | página estática com anime.js ESM fixado via CDN✓ chosen | projeto npm com bundling via Vite | vendorizar anime.esm.js no repo |
|---|---|---|---|
| simplicidade zero-toolchainweight 5 |
10 × 5 = 50
|
3 × 5 = 15
|
9 × 5 = 45
|
| fidelidade da fixação de versãoweight 4 |
9 × 4 = 36
versão exata na URL do import
|
10 × 4 = 40
|
10 × 4 = 40
|
| comportamento offlineweight 3 |
4 × 3 = 12
|
9 × 3 = 27
|
10 × 3 = 30
|
| higiene do repoweight 3 |
9 × 3 = 27
|
5 × 3 = 15
|
4 × 3 = 12
um artefato vendorizado de 40 kB+ em um repo de prompts
|
| Total | 125 | 97 | 127 |
Tarefa 1 · Tarefa 4
O design se divide ao longo de uma única costura: módulos que calculam (engine.js, o formatador do visor) nunca tocam módulos que se movem (wave.js envolvendo o anime.js). As três figuras leem-se de cima para baixo: o contexto de implantação, as fronteiras entre módulos e, por fim, a única interação de runtime delicada — um pressionamento de tecla interrompendo o marulho e reencaixando nele.
flowchart TB user["Usuário final — o bucaneiro"] -->|"ponteiro, toque, teclado físico"| page["Calculadora Pirata — página estática sob demos/pirate-calculator"] page -->|"import animate, stagger (animejs 4.3.5 fixado)"| cdn["anime.js v4 ESM no CDN jsDelivr"]
flowchart LR
subgraph page["Página da Calculadora Pirata"]
keys["keyboard.js — grade de teclas, entrada por ponteiro e teclado físico"]
engine["engine.js — máquina de estados de execução imediata, pura"]
display["display.js — formatador do visor de pergaminho"]
wave["wave.js — controlador do marulho oceânico"]
end
anime["anime.js v4 — animate e stagger"]
keys -->|"tokens de entrada"| engine
engine -->|"snapshots de estado"| display
keys -->|"eventos de pressionar e soltar"| wave
wave -->|"animações por tecla"| animeA regra que sustenta o design é a direção de dependência ao redor do engine.js: ele não importa nada e nada sabe sobre o DOM ou sobre o anime.js. O keyboard.js empurra tokens de entrada puros para dentro; o display.js lê snapshots de estado puros para fora; o wave.js é o único módulo autorizado a importar o anime.js, então o feedback de pressionamento flui de keyboard.js para wave.js, nunca direto para a biblioteca de animação. Mantenha o engine.js puro, ou os testes unitários da Tarefa 2 perdem o chão.
sequenceDiagram participant U as Usuário participant K as keyboard.js participant W as wave.js participant E as engine.js participant D as display.js U->>K: pointerdown na tecla 7 K->>W: libera a tecla 7 do marulho W->>W: executa o mergulho na tecla 7 K->>E: token de entrada com o dígito 7 E-->>D: snapshot de estado D-->>U: visor exibe 7 W->>W: mergulho encerrado, mede a fase viva do marulho W->>K: tecla 7 reencaixada suavemente no marulho
Leia as duas autochamadas do wave.js: o mergulho nunca pausa o loop global — apenas a tecla pressionada sai dele — e o reencaixe é ciente de fase. O controlador mede onde o marulho está naquele instante e conduz a tecla suavemente até esse offset. Esse passo de medir-e-conduzir é o que sustenta a cláusula de sem-salto-visível do AC-3; pulá-lo produz o clássico artefato da tecla que teleporta.
Duas fundações independentes — o shell tematizado da página e o engine puro da calculadora — correm em paralelo na Onda 0. Uma única tarefa de fiação então torna a calculadora real antes de qualquer trabalho de animação: o marulho é aplicado como camada sobre uma calculadora que já funciona, nunca o inverso. O trabalho de animação se divide entre a onda viajante ociosa (a matemática de fase difícil, uma única tarefa) e dois finalizadores paralelos — o feedback de pressionamento e o passe de verificação de acessibilidade/desempenho — que se apoiam ambos no marulho em execução.
Makespan 4 tiers · critical path Tarefa 1 -> Tarefa 3 -> Tarefa 4 -> Tarefa 5 · sequential 6 units sequential · critical path length 4 tasks
Ganho de paralelismo: os fan-outs nas duas pontas (fundações, polimento) cortam o cronograma de 6 slots de tarefa para 4. Gargalo: a Tarefa 3 e a Tarefa 4 carregam folga zero — todo caminho cruza a espinha fiação-depois-marulho, então um atraso em qualquer uma delas desloca o makespan inteiro. Nota: a Tarefa 6 tem executor Pair — agende o protocolo humano de toques e a revisão de movimento reduzido para o checkpoint da Onda 3.
graph TD
subgraph W0["Onda 0 — Fundações"]
T1["Tarefa 1 — Shell da página e tema pirata"]
T2["Tarefa 2 — Engine da calculadora, puro"]
end
subgraph W1["Onda 1 — Fiação"]
T3["Tarefa 3 — Fiação do visor e das entradas"]
end
subgraph W2["Onda 2 — Marulho oceânico"]
T4["Tarefa 4 — Onda viajante ociosa"]
end
subgraph W3["Onda 3 — Polimento de interação"]
T5["Tarefa 5 — Mergulho no pressionamento e reencaixe"]
T6["Tarefa 6 — Movimento reduzido e verificação"]
end
T1 --> CP0{{Checkpoint 0}}
T2 --> CP0
CP0 --> T3
T3 --> CP1{{Checkpoint 1}} --> T4
T4 --> CP2{{Checkpoint 2}}
CP2 --> T5
CP2 --> T6
T5 --> CP3{{Checkpoint 3}}
T6 --> CP3| Risk | Impact | Mitigation |
|---|---|---|
| deriva da API do anime.js v4 em relação à documentação encontrada online (exemplos v3 dominam os resultados de busca) | medium | fixar 4.3.5 na URL do import e verificar o grid do stagger mais a emenda do loop em um spike dentro da Tarefa 4, antes de ligar todas as teclas |
| mergulho de pressionamento reencaixando no marulho com salto visível (descasamento de fase) | high | o reencaixe conduz do translateY medido da tecla até a fase viva do loop; o AC-3 é verificado no Checkpoint 3 |
| animação contínua drena bateria e distrai usuários | low | pausar o loop quando a aba está oculta (visibilitychange) e honrar prefers-reduced-motion (NFR-2) |
As ondas rodam sequencialmente; as duas tarefas dentro da Onda 0 e as duas dentro da Onda 3 rodam em paralelo. Toda onda termina em seu checkpoint: testes unitários do engine via node --test onde o código mudou, mais uma revisão manual no navegador para as checagens visuais. Não há etapa de build — verificar significa servir demos/pirate-calculator/ de um servidor estático local, abrir o index.html e recarregar (F5) após as edições.
Build steps
Acceptance
Verification
Build steps
Acceptance
Verification
Build steps
Acceptance
Verification
Build steps
Acceptance
Verification
Build steps
Acceptance
Verification
Build steps
Acceptance
Verification
Uma única seta carrega toda a história de implantação: a única dependência externa da página é o import ESM fixado do anime.js. Quando essa seta falha (offline), a página ainda precisa subir como uma calculadora estática, porém totalmente funcional — o mesmo caminho degradado que o movimento reduzido usa (ADR-3, NFR-2).