Kiskujab/page-swarm-rebuild

O que page-swarm-rebuild faz?

Versão 1.3.0 (módulo, add-on, folha de estilo e este arquivo; veja CHANGELOG.md no repositório; SwarmRebuild.version).

Efeito de introdução apenas para apresentação. O DOM real da página nunca é modificado: as camadas são ocultadas e reveladas com uma folha de estilo em cascata no <head>, toda animação acontece em uma sobreposição anexada a <html>, e ambos são removidos ao final. Sem dependências, sem requisições de rede (compatível com GDPR), sem deslocamento de layout, sem som, e a página nunca fica meio oculta (veja Proteção).

Especificação do efeito original (linha do tempo, visuais, HUD, curva de rolagem): references/effekt-leiras.md (Húngaro). Onde este arquivo e aquele discordarem, este arquivo prevalece (decisões de produto foram tomadas após a redação da descrição).

Arquivos

Arquivo	Finalidade
assets/swarm-rebuild.js	O módulo, fonte legível (script clássico, define window.SwarmRebuild; também importável de um bundler).
assets/swarm-rebuild.min.js, swarm-rebuild-debug.min.js, swarm-rebuild.min.css	Builds minificados para sites HTML puro (scripts/build-min.cjs; o instalador os usa; bundlers minificam as fontes por conta própria).
assets/swarm-rebuild.css	Estilos da sobreposição, todos com escopo sob #swarm-rebuild-root.
assets/swarm-rebuild-debug.js	Add-on de depuração: barra de controle, tour com rolagem automática, hooks de teste. Nunca carregado para visitantes; buscado apenas com ?rebuild-debug=1 / debug: true. Instale-o ao lado do módulo de qualquer forma (é como você testa no site ao vivo).
assets/react/SwarmRebuild.jsx	Wrapper React / Next.js + <SwarmRebuildHead /> (trecho pré-renderização); o add-on de depuração é um chunk lazy separado.
assets/demo/	Demonstração fictícia de portfólio escuro (assets/demo/index.html, 214 camadas (desktop), 6,6 alturas de viewport, cabeçalho fixo).
tests/index.html	Links para todas as páginas de teste em todos os modos (também a página inicial do GitHub Pages).
tests/pages/dental/	Clínica odontológica fictícia: tema claro, links de telefone, barra fixa "Ligue para nós" + agendamento (mobile), aviso fixo (desktop).
tests/pages/lang-*/	Páginas fictícias em Húngaro, Árabe (direita para esquerda), Japonês e uma rica em emojis (digitação em qualquer idioma).
tests/pages/law/, accounting/, bootstrap/, spa/	Padrões fictícios do mundo real: fontes da web, cabeçalho fixo, banners de consentimento, iframe, imagens lazy, modo escuro, página longa, revelação por rolagem, Bootstrap (npm), aplicativo de página única, vídeos.
tests/pages/nextjs/	Aplicativo React Next.js 15 App Router fictício: contador React (verificação de hidratação), botão de Ajuda fixo.
scripts/verify.cjs	Verificação Playwright de uma página (veja passo 4).
scripts/run-tests.cjs	Executa verify.cjs nas três páginas de teste, desktop e mobile; imprime uma tabela resumo.
scripts/bench-fps.cjs	Taxa de quadros de uma versão mais antiga do módulo contra a atual, mesma máquina, execuções intercaladas.
scripts/build-site.cjs	Constrói as três páginas de teste como um site estático (GitHub Pages) ou o serve na rede local.
scripts/next-app.cjs	Utilitário: prepara / constrói o aplicativo de teste Next.js em uma pasta temporária.
scripts/build-min.cjs	Constrói os arquivos .min e verifica o orçamento de tamanho (precisa de terser e csso do npm).
scripts/perf.cjs	Métricas Lighthouse (LCP, CLS, TBT, Speed Index, acessibilidade, SEO) com e sem o efeito.
scripts/sync-snippet.cjs	Copia o trecho do módulo para o wrapper React, SKILL.md e as páginas de teste.
scripts/record-video.cjs	Grava o efeito como .mp4 / .webm para um portfólio (tour de depuração, barra de controle oculta).
scripts/project.cjs	Instala o efeito em um projeto com backup em legacy/, o remove novamente, restaura os originais.
scripts/test-project.cjs	Testa o instalador: backup, restauração após um projeto quebrado (hash idêntico), desinstalação.

Decisões de produto (elas substituem o vídeo de referência)

• O modo principal é scroll (o padrão): a construção segue a rolagem do visitante, e apenas o que está na viewport é construído: um elemento começa quando pelo menos 60 % dele está na tela (buildVisible), nada é construído abaixo ou acima da viewport, e nenhum agente ativo sai da tela.
• Visitantes nunca veem uma barra de controle e nunca recebem uma rolagem automática. A barra e o tour vivem no add-on de depuração, carregado apenas com ?rebuild-debug=1 ou debug: true. mode: 'tour' sem o add-on recai para scroll.
• Sempre uma saída sem controles visíveis: Esc, Tab, Enter, qualquer outra tecla (exceto Shift/Ctrl/Alt/Meta isolados) e qualquer clique ou toque mostram a página finalizada imediatamente, sem animação e sem deslocamento de layout. prefers-reduced-motion significa nenhum efeito (WCAG 2.2.2).
• Teclas de rolagem rolam: Espaço, setas, Page Up / Down e Home / End (com o foco na própria página, sem Ctrl / Alt / Meta) dirigem a construção exatamente como a roda do mouse. Em um link, botão ou campo focado, ou com um modificador, elas finalizam o efeito como qualquer outra tecla. Tab, Enter e Esc sempre o finalizam, para que usuários de teclado alcancem o conteúdo real (e sua ordem de foco) na primeira Tab.
• O clique que finaliza o efeito nunca faz algo que o visitante não viu: se cair em conteúdo que ainda não foi finalizado (oculto, ou ainda sendo construído), ele é engolido (preventDefault + stopPropagation, no mouse já em pointerdown, então sem foco, sem link, sem ação de botão). Se cair em conteúdo finalizado (visível, nada dentro dele ou o revelando ainda em andamento — por exemplo, um link de telefone, que é mostrado desde o início, ou um botão construído), ele passa como um clique normal e o efeito finaliza ao mesmo tempo. Motivo: engolir todo clique faria um link visível "Ligue para nós" falhar no primeiro toque; deixar todo clique passar seguiria links que o visitante nunca viu. A rolagem por toque e a barra de rolagem nunca finalizam o efeito (rolar é como a construção é dirigida).
• Sem som. O módulo não possui código de áudio.

Modos

modo	velocidade	comportamento
scroll (padrão)	3x	Sem rolagem automática. Agentes constroem apenas o que está na viewport: um elemento começa quando pelo menos buildVisible (60 %) de sua altura está na tela; um elemento mais alto que a tela quando preenche 60 % da tela, então é construído de cima para baixo conforme entra. Nada é construído fora da viewport e um agente ativo nunca a deixa (um quadro mais alto que a tela é puxado da borda da tela). Após uma rolagem rápida (roda, teclas, Home / End), a parte visível é preenchida em ~1-2 s: essas camadas começam primeiro, mais agentes entram (até 8 acima do plano) e as tarefas são executadas mais rápido. O que sai da viewport é finalizado imediatamente (veja Proteção).
fast	6x	Mesmo que scroll, duas vezes mais rápido.
tour (apenas depuração)	1x	Rolagem automática como no vídeo de referência: ~camadas/7 segundos, a câmera segue a frente de trabalho, termina no fundo com o anel de cursores. Para gravações e verificações lado a lado. ?rebuild-speed=6 dá o antigo "rápido" (uma rolagem automática 6x, ~9 s na demonstração). A rolagem manual transfere o controle para o visitante; o botão Tour da barra retoma.

Após a construção, os enxames se reúnem ao redor do elemento de foco e a sobreposição desaparece após autoExit segundos (3 s; com o add-on de depuração 6 s, nunca no modo tour).

Movimento

Todo ele é sutil por padrão e configurado com motion (veja Configurar); ?rebuild-motion=arc:0,... desliga partes para testes A/B (add-on de depuração).

• Elemento de foco (focus): a abertura e o final se agrupam ao redor dele. Pergunte ao desenvolvedor (passo 1). Em cada fase, o primeiro destes que estiver pelo menos metade na viewport é usado: o(s) elemento(s) configurado(s), [data-swarm-focus], h1, um botão principal (a.btn, .button, .cta, button[type=submit] ...), o logotipo; então a maior imagem na viewport; então um ponto na viewport. Assim, um foco distante na página (por exemplo, uma chamada para ação no final) serve ao final, e a abertura usa o título principal.
• Enxames: agentes livres voam em 2-4 enxames de tamanhos claramente diferentes (telefones: 2). Cada agente é puxado por uma mola amortecida para seu lugar em seu enxame; os centros dos enxames se movem em uma elipse ao redor do elemento de foco cujo raio respira e cujo ritmo muda, então os agentes aceleram e desaceleram por conta própria e nunca correm em um círculo perfeito. A abertura já começa em enxames (dura bem menos de um segundo para visitantes).
• Agentes em repouso (durante a construção, um agente sem trabalho): ele deixa seu enxame por seu próprio ponto na viewport, a pelo menos 72 px de cada outro agente em repouso (nunca um aglomerado de cursores sobrepostos), deriva lentamente e desaparece após 1,4 s; ele aparece onde repousa quando recebe sua próxima tarefa. No final, todos eles voltam e se reúnem em enxames ao redor do foco. Medido: no máximo 2 cursores em repouso sobrepostos em 99,6-100 % dos quadros (1.2: uma mediana de 6 e até 20 na demonstração).
• Final: uma mola rígida subamortecida (amortecimento 0,63, motion.spring) puxa cada agente para o foco: mais rápido no início, cerca de 5-20 % além de seu lugar, depois de volta; após ~1 s a mola amolece e os enxames circulam lentamente.
• Mouse (abertura e final, apenas desktop; nunca em toque, nunca com movimento reduzido): um agente perto do ponteiro se move para fora de seu caminho (mais difícil quando o ponteiro vem rápido); até 3 agentes curiosos então o seguem em um pequeno círculo, 1,3-2 s quando repousa, mais curto quanto mais rápido se afasta (o interesse diminui a (1 + velocidade / 220 px/s) vezes a taxa base). Nunca mais perto que 36 px (um limite rígido, então os ícones nunca se sobrepõem); a sobreposição ignora eventos de ponteiro, então cliques nunca são perturbados.
• Gravidade: um agente carrega o elemento em que trabalha, então seu caminho até lá (e uma cópia clone carregada) se curva para baixo: curvatura = 0,2 x distância horizontal x peso x horizontalidade², peso = sqrt(área) / 320 px limitado a 0,2..1, no máximo 56 px e um quinto da distância horizontal. Um movimento vertical dificilmente se curva. O caminho para uma tarefa também começa com a velocidade atual do agente (curva cúbica de Hermite), então não há paradas ou curvas repentinas.
• Dificuldade: o trabalho de cada tarefa (não o caminho até lá) é dimensionado por uma dificuldade da área do elemento (para digitação: a caixa onde se digita): perto da média da página, 2x a área ~ 1,6-1,8x o tempo, comprimido (tanh) para que a tarefa mais difícil leve no máximo ~4x a mais fácil. É normalizado (ponderado pelo comprimento da tarefa e dificuldade, porque tarefas paralelas fazem as longas definirem o ritmo) para que toda a construção leve o mesmo tempo de antes; apenas a divisão entre pequenas e grandes muda.
• Lite (motion.lite: 'auto'): em telefones, 2 enxames e nenhuma interação com mouse; quando a taxa de quadros fica abaixo de 38 fps por dois segundos durante a construção, também um fantasma de rastro em vez de três.

Idiomas e direções de escrita

O módulo não assume nenhum idioma. A digitação segue caracteres percebidos pelo usuário (clusters de grafemas, Intl.Segmenter, com um fallback que une marcas combinantes, sequências ZWJ, tons de pele, seletores de variação e pares de bandeiras): uma letra acentuada, uma família de emojis, uma bandeira ou uma letra com marcas Árabes / Hebraicas nunca é dividida. Texto não digitado permanece no lugar como texto oculto, e os navegadores modelam através desse limite, então letras Árabes mantêm suas formas conectadas e nada reflui. Elementos da direita para a esquerda (direction: rtl, por exemplo, <html dir="rtl">): quadros crescem da borda direita, linhas são desenhadas da direita para a esquerda, o agente digita no lado esquerdo e o cursor fica à esquerda da última letra digitada; uma sequência da esquerda para a direita dentro de texto da direita para a esquerda (um número, um endereço de e-mail, um nome latino) é digitada como um todo, como uma palavra colada. Texto CJK (sem espaços) e palavras longas quebram exatamente como na página. A sobreposição em si é sempre disposta da esquerda para a direita (direction: ltr em sua raiz) para que uma página da direita para a esquerda nunca a espelhe. Números em qualquer script (\p{Nd}) contam como números. Páginas de teste: tests/pages/lang-hu (ő / ű, palavras muito longas), lang-ar (direita para a esquerda, dígitos Arábico-Índicos, uma citação Hebraica), lang-ja (Japonês), lang-emoji. Limitação conhecida: modos de escrita vertical (writing-mode: vertical-rl) são digitados, mas os quadros ainda crescem da esquerda para a direita.

Desempenho, mecanismos de busca, acessibilidade

• Tamanho (o que um visitante baixa; o add-on de depuração nunca): módulo 70 KB minificado / 27,5 KB gzip, folha de estilo 6 KB / 1,6 KB; orçamento 30 KB + 2 KB gzip (node scripts/build-min.cjs --check). Reconstrua os arquivos .min após cada alteração no módulo (--modules <pasta com terser e csso>).

• Lighthouse (scripts/perf.cjs, mediana de 3, predefinições mobile / desktop, a máquina de teste sem GPU):

  página	LCP ms off -> on	CLS off -> on	TBT ms off -> on	Speed Index ms off -> on	pontuação perf
  demo, mobile	2106 -> 2207	0 -> 0	12 -> 10	968 -> 1669	99 -> 99
  demo, desktop	483 -> 573	0 -> 0	0 -> 0	266 -> 681	100 -> 100
  dental, mobile	1956 -> 2035	0 -> 0	0 -> 0	754 -> 1763	99 -> 99
  dental, desktop	442 -> 490	0 -> 0	0 -> 0	201 -> 767	100 -> 100
  law (fontes web), mobile	2094 -> 2222	0.030 -> 0	0 -> 0	1895 -> 2386	98 -> 97
  accounting (página longa), mobile	1707 -> 1973	0 -> 0	0 -> 0	1652 -> 1697	99 -> 98

  Sem tempo de bloqueio e sem deslocamento de layout (o próprio deslocamento de troca de fonte da página law é até oculto). LCP cresce em 50-270 ms e Speed Index em até ~1 s: a primeira viewport é construída na frente do visitante, então está visualmente completa mais tarde - isso é o próprio efeito. Apenas visitantes de primeira viagem (uma vez por sessão) pagam por isso; visitantes que retornam e rastreadores obtêm a página imediatamente. As pontuações de acessibilidade / SEO movem-se em um ponto para um lado ou outro apenas porque o Lighthouse vê menos da página enquanto está oculta.

• Mecanismos de busca e prévias de links: rastreadores (user agent com bot / crawl / spider, Googlebot, Bingbot, facebookexternalhit, prévias de links ...) nunca recebem o efeito, nem no trecho do cabeçalho nem no módulo: eles veem a página finalizada com o DOM idêntico (a11y check). Sem JavaScript, a página nunca é oculta, e o efeito nunca remove conteúdo (usa apenas visibility).

• Acessibilidade: [...] (truncado para tradução)