From e22e98fd45fdd2041ab5e9d74644d51f38f48d02 Mon Sep 17 00:00:00 2001
From: yanhenrique-dev <yanhenrique-dev@users.noreply.github.com>
Date: Sun, 27 Sep 2026 00:33:05 -0300
Subject: [PATCH 1/6] fix(a11y): fecha contraste do success e o foco dos
 switches
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A3 — `--v2-state-fg-success` era green-800 (#198b43) a 3,97:1 sobre o
bg-success, em texto de 11px (tag "Em dia") e 13px (.status-line): falha
WCAG 1.4.3. green-900 (#1d783c) mede 5,03:1 no bg e 4,93:1 em layer-02,
então o token também segura se a tag renderizar sobre superfície neutra.

A1 — a regra de foco do switch era
`[data-component="switch"] [data-slot="switch-control"]:focus-visible`, e o
span filho não é focalizável: a regra nunca casava e os três switches
(Detecção automática, Modo, Backup) estavam sem indicador de foco, falha
WCAG 2.4.7. A regra vai para o <button>, que é o alvo real.

A4 — `--v2-border-border-focus` era blue-500 (#7698fd) nos dois temas:
2,73:1 em #fff, 2,62:1 em layer-01, 2,44:1 em layer-02. Fica blue-700 no
light (6,27/6,01/5,60) e blue-300 no dark (12,20/10,46). O anel é
desenhado com outline-offset, ou seja fora do fill — o fundo que importa é
o da superfície, não o do botão contrast, que é o que faz blue-700
funcionar no light apesar de o bg-contrast ser escuro.

M6 — o viewport do scroll-view é focalizável (é a única forma de rolar a
região, já que a scrollbar nativa está escondida) mas tinha `outline: none`
sem reposição. WCAG 2.4.7.

Robustez — `--v2-grey-600` usava a keyword `gray`, alias de `grey`:
virou hex explícito, sem mudar o valor resolvido.

STYLEGUIDE: a tabela de tokens estava divergindo do código em cinco
pontos (faint, warning, success, focus e a ordem de carga) e mandava usar
script inline para o tema, o que a CSP proíbe. Registra os desvios
conscientes da fonte original, com a razão e a medição de cada um.
---
 STYLEGUIDE.md         | 53 +++++++++++++++++++++++++++++++++++--------
 static/components.css | 17 +++++++++++++-
 static/tokens.css     | 22 ++++++++++++------
 3 files changed, 74 insertions(+), 18 deletions(-)

diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md
index b926c69..e3a2632 100644
--- a/STYLEGUIDE.md
+++ b/STYLEGUIDE.md
@@ -13,9 +13,11 @@ Nenhum valor foi inventado. Se não está no CSS-fonte, não está aqui.
 | `static/tokens.css` | Rampas, alfa, cores de estado, semânticos light/dark, elevação, raios, tipografia, movimento |
 | `static/components.css` | Primitives com `data-component` / `data-slot` |
 | `static/shell.css` | Grid do app, sidebar, header, page shell, as três telas |
+| `static/theme.js` | Aplica o tema antes da primeira pintura (bloqueante, por causa da CSP) |
+| `static/index.html` | Markup das três telas e a ordem de carga |
 | `STYLEGUIDE.md` | Este documento |
 
-Ordem de carga no HTML: `tokens.css` → `components.css` → `shell.css`.
+Ordem de carga no HTML: `theme.js` → `tokens.css` → `components.css` → `shell.css`.
 
 ## Convenção de atributos
 
@@ -52,25 +54,49 @@ Estados de interação são dirigidos por `:hover` **e** por `[data-state=…]`,
 | `--v2-background-bg-accent` | `#3b5cf6` | `#3b5cf6` |
 | `--v2-text-text-base` | `#161616` | `#fafafa` |
 | `--v2-text-text-muted` | `#5c5c5c` | `#aeaeae` |
-| `--v2-text-text-faint` | `#808080` | `#808080` |
+| `--v2-text-text-faint` | `#6b6b6b` | `#999999` |
 | `--v2-text-text-accent` | `#3b5cf6` | `#a2bcff` |
 | `--v2-icon-icon-base` | `#3a3a3a` | `#dbdbdb` |
 | `--v2-icon-icon-muted` | `#808080` | `#808080` |
 | `--v2-border-border-muted` | `rgba(0,0,0,.08)` | `rgba(255,255,255,.08)` |
 | `--v2-border-border-base` | `rgba(0,0,0,.10)` | `rgba(255,255,255,.10)` |
 | `--v2-border-border-strong` | `rgba(0,0,0,.20)` | `rgba(255,255,255,.20)` |
-| `--v2-border-border-focus` | `#7698fd` | `#7698fd` |
+| `--v2-border-border-focus` | `#3250df` | `#c3d4fd` |
 | `--v2-overlay-simple-overlay-hover` | `rgba(0,0,0,.04)` | `rgba(255,255,255,.06)` |
 | `--v2-overlay-simple-overlay-pressed` | `rgba(0,0,0,.08)` | `rgba(255,255,255,.10)` |
 | `--v2-overlay-simple-overlay-scrim` | `rgba(0,0,0,.4)` | `rgba(0,0,0,.6)` |
-| `--v2-state-bg-success` / `fg` | `#e7f9ea` / `#198b43` | `#14361d` / `#6bd586` |
-| `--v2-state-bg-warning` / `fg` | `#fefaec` / `#cb9f34` | `#4b4025` / `#f2cf76` |
+| `--v2-state-bg-success` / `fg` | `#e7f9ea` / `#1d783c` | `#14361d` / `#6bd586` |
+| `--v2-state-bg-warning` / `fg` | `#fefaec` / `#68552b` | `#4b4025` / `#f2cf76` |
 | `--v2-state-bg-danger` / `fg` | `#fceceb` / `#b82d35` | `#461516` / `#f17471` |
 | `--v2-state-bg-info` / `fg` | `#ecf1fe` / `#2c47c8` | `#1b2852` / `#7698fd` |
 
-O tema vive em `[data-color-scheme="light" | "dark"]` no `<html>`. Um script inline
-antes da primeira pintura lê `localStorage["alldown.theme"]` e cai para
-`prefers-color-scheme` — não há flash.
+O tema vive em `[data-color-scheme="light" | "dark"]` no `<html>`. O arquivo
+`static/theme.js` roda **externo e bloqueante** no `<head>` (sem `defer`), antes da
+primeira pintura: lê `localStorage["alldown.theme"]` e cai para `prefers-color-scheme`
+— não há flash.
+
+> **Não mova isso para um `<script>` inline.** A CSP (`app.py`) é
+> `script-src 'self'` sem `unsafe-inline`; um script inline é bloqueado e o tema passa
+> a depender de `prefers-color-scheme`, ruining a escolha persistida. É a razão de
+> `theme.js` ser um arquivo separado.
+
+### Três desvios conscientes da fonte
+
+Os tokens abaixo **não** são os valores do console original. Cada um foi alterado
+para fechar contraste (WCAG 1.4.3 texto, 1.4.11 não-texto) e o valor medido está
+registrado aqui — a fonte original **não** é a autoridade para estes:
+
+| Token | Origem |light | dark | Razão |
+|---|---|---|---|---|
+| `--v2-text-text-faint` | `#808080` | `#6b6b6b` | `#999999` | origem passava em 3.6:1 como texto |
+| `--v2-state-fg-warning` | `#cb9f34` | `#68552b` | — | origem a 2.35:1 no bg |
+| `--v2-state-fg-success` | `#198b43` | `#1d783c` | — | origem a 3.97:1 na tag de 11px |
+| `--v2-border-border-focus` | `#7698fd` | `#3250df` | `#c3d4fd` | origem a 2,7:1 em toda superfície clara |
+
+O anel de foco é desenhado com `outline-offset`, ou seja **fora** do preenchimento do
+elemento. O fundo que importa é o da superfície onde o anel cai, não o do botão
+`contrast` — por isso `blue-700` funciona no light despite de o `bg-contrast` ser
+escuro.
 
 ## Elevação
 
@@ -206,8 +232,15 @@ O console esconde a scrollbar nativa e desenha a dele. O mesmo vale aqui
 11. Toda tabela numérica alinhada à direita com `tabular-nums`.
 12. Zero estilo inline, zero `any`, só tokens nos valores.
 
-`@media (forced-colors: active)` é a única exceção à regra 3: troca as bordas de 1px porque
-o Windows High Contrast descarta sombras.
+Duas exceções nomeadas, ambas funcionais:
+
+- **Regra 3** — `@media (forced-colors: active)`: troca as bordas de 1px porque o
+  Windows High Contrast descarta sombras.
+- **Regra 12** — o thumb do scroll decorativo (`app.js`, `initScrollThumb`) escreve
+  `style.height` e `style.transform`inline. São valores de geometria que só o JS
+  conhece depois do layout; não são tema.
+
+Toda outra superfície de cor e tamanho deve continuar vindo de token.
 
 ## Verificação
 
diff --git a/static/components.css b/static/components.css
index 2871f99..6c88ab7 100644
--- a/static/components.css
+++ b/static/components.css
@@ -651,7 +651,14 @@ body {
 [data-component="switch"][data-checked] [data-slot="switch-control"] { background: var(--v2-background-bg-accent); box-shadow: var(--v2-elevation-switch-on); }
 [data-component="switch"][data-checked] [data-slot="switch-thumb"] { transform: translate(12px); }
 [data-component="switch"][data-checked]:hover:not([data-disabled], [data-readonly]) [data-slot="switch-thumb"] { transform: translate(11px); }
-[data-component="switch"] [data-slot="switch-control"]:focus-visible { outline: 2px solid var(--v2-border-border-focus); outline-offset: 2.5px; }
+/* O alvo de foco é o <button>, não o <span data-slot="switch-control"> filho:
+   o span não é focalizável, então a regra antiga nunca casava :focus-visible e os
+   três switches ficavam sem indicador de foco (WCAG 2.4.7). */
+[data-component="switch"]:is(:focus-visible, [data-state="focus"]):not([data-disabled], [data-readonly]) {
+  outline: 2px solid var(--v2-border-border-focus);
+  outline-offset: 2.5px;
+  border-radius: var(--v2-radius-pill);
+}
 [data-component="switch"]:where([data-disabled]) { opacity: 0.5; cursor: not-allowed; }
 
 [data-component="switch"] [data-slot="switch-label"] {
@@ -1134,6 +1141,14 @@ body {
   outline: none;
   overscroll-behavior: contain;
 }
+/* O viewport é focalizável (permite rolar por teclado) — mas `outline: none`
+   acima o deixava sem indicador, e a scrollbar nativa está escondida: era a
+   única forma de percorrer a região, invisível para quem navega por teclado.
+   WCAG 2.4.7. */
+[data-component="scroll-view"] [data-slot="scroll-view-viewport"]:focus-visible {
+  outline: 2px solid var(--v2-border-border-focus);
+  outline-offset: -2px;
+}
 [data-component="scroll-view"] [data-slot="scroll-view-viewport"]::-webkit-scrollbar { display: none; }
 
 [data-component="scroll-view"] [data-slot="scroll-view-thumb"] {
diff --git a/static/tokens.css b/static/tokens.css
index 422c952..18a0d21 100644
--- a/static/tokens.css
+++ b/static/tokens.css
@@ -46,7 +46,8 @@
   --v2-grey-300: #eee;
   --v2-grey-400: #dbdbdb;
   --v2-grey-500: #aeaeae;
-  --v2-grey-600: gray;
+  /* Hex explícito: `gray` é alias de `grey` e depende de resolução de keyword. */
+  --v2-grey-600: #808080;
   --v2-grey-700: #5c5c5c;
   --v2-grey-800: #3a3a3a;
   --v2-grey-900: #2e2e2e;
@@ -293,7 +294,7 @@
 
   --v2-text-text-base: var(--v2-grey-1100);
   --v2-text-text-muted: var(--v2-grey-700);
-  /* faint ajustado para #6b6b6b (era grey-600): contraste ≥4.5 em superfícies claras. */
+  /* faint: #6b6b6b em vez de grey-600 — contraste ≥4.5:1 em superfícies claras (axe). */
   --v2-text-text-faint: #6b6b6b;
   --v2-text-text-inverse: var(--v2-grey-50);
   --v2-text-text-contrast: var(--v2-grey-50);
@@ -312,7 +313,11 @@
   --v2-border-border-base: var(--v2-alpha-dark-10);
   --v2-border-border-strong: var(--v2-alpha-dark-20);
   --v2-border-border-inverse: var(--v2-grey-1000);
-  --v2-border-border-focus: var(--v2-blue-500);
+  /* focus: blue-700 em vez de blue-500 (2.73:1) — ≥3:1 em toda superfície clara
+     (6.27:1 em #fff, 6.01:1 em layer-01, 5.60:1 em layer-02). O anel é desenhado
+     com outline-offset, ou seja, fora do fill do elemento: o fundo relevante é o da
+     superfície, não o do botão contrast. */
+  --v2-border-border-focus: var(--v2-blue-700);
 
   --v2-overlay-simple-overlay-hover: var(--v2-alpha-dark-4);
   --v2-overlay-simple-overlay-pressed: var(--v2-alpha-dark-8);
@@ -324,10 +329,12 @@
   --v2-overlay-gradient-depth-bot: var(--v2-alpha-light-0);
 
   --v2-state-bg-success: var(--v2-green-100);
-  --v2-state-fg-success: var(--v2-green-800);
+  /* fg-success: green-900 em vez de green-800 (3.97:1) — contraste ≥4.5:1 no light.
+     A tag "Em dia" (11px) e a .status-line de sucesso (13px) usam este token. */
+  --v2-state-fg-success: var(--v2-green-900);
   --v2-state-border-success: var(--v2-green-300);
   --v2-state-bg-warning: var(--v2-yellow-100);
-  /* fg-warning ajustado para yellow-1100 (era yellow-800, 2.35:1 no bg): contraste ≥4.5. */
+  /* fg-warning: yellow-1100 em vez de yellow-800 (2.35:1) — contraste ≥4.5:1 no light. */
   --v2-state-fg-warning: var(--v2-yellow-1100);
   --v2-state-border-warning: var(--v2-yellow-300);
   --v2-state-bg-danger: var(--v2-red-100);
@@ -390,7 +397,7 @@
 
   --v2-text-text-base: var(--v2-grey-100);
   --v2-text-text-muted: var(--v2-grey-500);
-  /* faint ajustado para #999 (era grey-600): contraste ≥4.5 em layer-01 no dark. */
+  /* faint: #999 em vez de grey-600 — contraste ≥4.5:1 em layer-01 no dark. */
   --v2-text-text-faint: #999999;
   --v2-text-text-inverse: var(--v2-grey-1100);
   --v2-text-text-contrast: var(--v2-grey-50);
@@ -409,7 +416,8 @@
   --v2-border-border-base: var(--v2-alpha-light-10);
   --v2-border-border-strong: var(--v2-alpha-light-20);
   --v2-border-border-inverse: var(--v2-grey-100);
-  --v2-border-border-focus: var(--v2-blue-500);
+  /* focus no dark: blue-300 — 12.20:1 em #161616, 10.46:1 em #242424. */
+  --v2-border-border-focus: var(--v2-blue-300);
 
   --v2-overlay-simple-overlay-hover: var(--v2-alpha-light-6);
   --v2-overlay-simple-overlay-pressed: var(--v2-alpha-light-10);

From dd8beb0e32b8cf3164824fce5fad083085f8a49b Mon Sep 17 00:00:00 2001
From: yanhenrique-dev <yanhenrique-dev@users.noreply.github.com>
Date: Sun, 27 Sep 2026 00:33:18 -0300
Subject: [PATCH 2/6] fix(a11y): uma unica regiao viva e o rascunho de
 mapeamento sobrevive ao render
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A2 — o unico live region da app era #status, que mora dentro de
#library-view; setView() faz libraryView.hidden = true, entao em Atividade
e Preferencias nada era anunciado — inclusive as mensagens dos switches e
os erros de operacao. Agora #live-status (sr-only) vive fora das <section
hidden>, dentro de <main>, e say() espelha la. announce() limpa e reescreve
no frame seguinte, senao "Acao cancelada." duas vezes seguidas so falaria
uma.

M2 — sobravam quatro live regions concorrentes (.connection-card,
#sync-state e as tres tags de switch), todas interrompindo o leitor varias
vezes numa operacao. Removidas: o app passa a ter uma regiao viva so.
O switch nao perde nada — role="switch" + aria-checked ja anunciam a
mudanca de estado nativamente. #status continua visual, sem aria-live,
senao anunciaria em duplicidade na view Biblioteca.

M3 — a validacao do caminho rodava no blur, quando o foco ja tinha saido do
campo: o erro aparecia exatamente no caso que o leitor de tela nao alcanca.
Agora valida no input, com #path-error como role="alert". O blur ficou so
para o autofill do navegador, que nao dispara input, e sem reanunciar.

A5 — render() trocava o innerHTML do <tbody> inteiro e destruia o <input>
de URL junto com o que o usuario tinha digitado, com o foco caindo no
<body> e o Tab recomecando do topo. Disparava em digitar na busca (debounce
de 150 ms), trocar filtro, setBusy e update. O beforeunload que existe para
avisar texto nao salvo so cobre unload, nao re-render — a protecao nao
cobria o caso real. captureUrlDrafts/restoreUrlDrafts chaveiam o rascunho
pelo row.name, nao pelo indice: indexado, um filtro que reordene a tabela
jogaria a URL digitada na linha errada e "Salvar" gravaria no repo errado.

M8 — no modo em lote cada doUpdate pintava 3x, e cada pintura reescrevia as
N linhas (60 repos = ~180 reconstrucoes, com a rolagem pulando e o botao
"Atualizar pendentes" perdendo o foco a cada passo). O render do meio foi
eliminado — era seguido imediatamente pelo do finally, sem nada visivel no
meio — e o caminho quiet passou a trocar so o <tr> da linha, com queda para
o render completo quando a linha nao esta na vista.

M9 — countRows() rodava 5 .filter() completos sobre state.rows todo render,
e o resultado era jogado fora por quem so precisa dos totais. Agora e um
passe so.

Testes: o shim nao fazia parse de HTML, entao innerHTML nao criava elements
e nao dava para testar o que o render faz. O harness agora recria os inputs
[data-url-input] a partir do html e conta reconstrucoes do <tbody> — e
passou a ser ele quem pega a regressao. requestAnimationFrame tambem foi
adicionado ao shim. Os testes novos falham sem as correcoes: verifiquei
desligando cada fix.
---
 static/app.js            | 169 ++++++++++++++++++++++++++++++++++-----
 static/index.html        |  22 +++--
 tests/js/load-app.mjs    |  80 +++++++++++++++++-
 tests/js/render.test.mjs | 144 +++++++++++++++++++++++++++++++++
 4 files changed, 386 insertions(+), 29 deletions(-)

diff --git a/static/app.js b/static/app.js
index 94d5ad4..fb8f4d8 100644
--- a/static/app.js
+++ b/static/app.js
@@ -22,6 +22,7 @@ const dom = {
   count: $("count"),
   status: $("status"),
   statusText: $("status-text"),
+  liveStatus: $("live-status"),
   statusIcon: $("status").querySelector("use"),
   statusProgress: $("status-progress"),
   log: $("log"),
@@ -83,7 +84,7 @@ const REDUCED_MOTION =
 
 const TONE_ICON = { success: "check", warning: "alert", danger: "alert", info: "activity" };
 
-if (!dom.repoList || !dom.pathInput || !dom.status || !dom.pathError || !dom.themeColor) {
+if (!dom.repoList || !dom.pathInput || !dom.status || !dom.pathError || !dom.themeColor || !dom.liveStatus) {
   throw new Error("RepoRefresh: interface não carregada");
 }
 
@@ -167,13 +168,15 @@ function artifactLabel(row) {
 }
 
 function countRows() {
-  const counts = {
-    all: state.rows.length,
-    behind: state.rows.filter((row) => row.behind === true).length,
-    ready: state.rows.filter((row) => row.behind === false).length,
-    unmapped: state.rows.filter((row) => !row.mapped).length,
-    error: state.rows.filter((row) => Boolean(row.error)).length,
-  };
+  // Um passe só. Antes eram 5 .filter() completos sobre state.rows, todo render,
+  // e o resultado era jogado fora por quem só precisa dos totais.
+  const counts = { all: state.rows.length, behind: 0, ready: 0, unmapped: 0, error: 0 };
+  for (const row of state.rows) {
+    if (row.behind === true) counts.behind += 1;
+    else if (row.behind === false) counts.ready += 1;
+    if (!row.mapped) counts.unmapped += 1;
+    if (row.error) counts.error += 1;
+  }
   $("nav-count").textContent = String(counts.all);
   $("c-all").textContent = String(counts.all);
   $("c-behind").textContent = String(counts.behind);
@@ -353,8 +356,98 @@ function restoreRepoFocus(focus) {
   if (target) target.focus({ preventScroll: true });
 }
 
+/**
+ * Rascunhos do formulário de mapeamento sobrevivem ao re-render.
+ *
+ * `render()` troca o innerHTML do <tbody> inteiro, o que destruía o <input> de URL
+ * junto com o que o usuário tinha digitado — e o foco ia para o <body>, de modo que
+ * o Tab recomeçava do topo. Qualquer evento dispava isso: digitar na busca (debounce
+ * de 150 ms), trocar filtro, setBusy, update. O beforeunload que existe para avisar
+ * "você tem texto não salvo" só cobre unload, não re-render — a proteção não cobria
+ * o caso real. Chaveado por row.name, não por índice: o índice é a posição em
+ * state.rows e muda quando a busca ou o filtro reordenam a tabela.
+ */
+function captureUrlDrafts() {
+  const drafts = new Map();
+  let focused = null;
+  dom.repoList.querySelectorAll("[data-url-input]").forEach((input) => {
+    const row = state.rows[Number(input.dataset.urlInput)];
+    if (!row) return;
+    if (input.value) drafts.set(row.name, input.value);
+    if (input === document.activeElement) {
+      focused = {
+        index: Number(input.dataset.urlInput),
+        start: input.selectionStart,
+        end: input.selectionEnd,
+      };
+    }
+  });
+  return { drafts, focused };
+}
+
+function restoreUrlDrafts(saved) {
+  if (!saved) return;
+  if (saved.drafts.size) {
+    dom.repoList.querySelectorAll("[data-url-input]").forEach((input) => {
+      const row = state.rows[Number(input.dataset.urlInput)];
+      if (!row) return;
+      const draft = saved.drafts.get(row.name);
+      if (draft !== undefined) input.value = draft;
+    });
+  }
+  if (!saved.focused) return;
+  const input = dom.repoList.querySelector(`[data-url-input="${saved.focused.index}"]`);
+  if (!input) return;
+  input.focus({ preventScroll: true });
+  // `type="url"` suporta seleção; se o valor não bater, o navegador ajusta sozinho.
+  if (saved.focused.start !== null && input.setSelectionRange) {
+    try {
+      input.setSelectionRange(saved.focused.start, saved.focused.end);
+    } catch {
+      /* input sem seleção suportada: o foco já está restaurado */
+    }
+  }
+}
+
+/**
+ * Atualiza só o <tr> de uma linha, sem reconstruir o <tbody> inteiro.
+ *
+ * No modo em lote (`updateAll`) cada `doUpdate` chamava `render()` três vezes, e
+ * cada `render()` reescrevia as N linhas: 60 repositórios viravam ~180
+ * reconstruções completas do <tbody>, com a barra de rolagem da tabela pulando e
+ * o botão "Atualizar pendentes" perdendo e retomando o foco a cada passo.
+ *
+ * Só é usado no caminho `quiet`, em que todas as linhas do lote já estão
+ * mapeadas — portanto não há <tr class="map-row"> para remover, e o formulário de
+ * mapeamento das outras linhas fica intocado. Devolve false quando não dá para
+ * fazer de forma cirúrgica, e o chamador cai no render() completo.
+ */
+function renderRowInPlace(row, index) {
+  const current = dom.repoList.querySelector(`tr[data-row-index="${index}"]`);
+  if (!current || typeof current.replaceWith !== "function") return false;
+  const holder = document.createElement("tbody");
+  holder.innerHTML = renderRow(row, index);
+  const next = holder.firstElementChild;
+  if (!next) return false;
+  // a linha trocada leva junto os botões; se o foco estava nela, volta para ela
+  const hadFocus =
+    document.activeElement && current.contains && current.contains(document.activeElement);
+  current.replaceWith(next);
+  if (hadFocus) {
+    const same = next.querySelector(`[data-action][data-index="${index}"]`);
+    if (same) same.focus({ preventScroll: true });
+  }
+  return true;
+}
+
+/** render cirúrgico no caminho quiet, com queda para o render completo */
+function renderProgress(row, index) {
+  if (!renderRowInPlace(row, index)) render();
+}
+
 function render() {
   const focus = focusedRepoAction();
+  const drafts = captureUrlDrafts();
   const rows = visibleRows();
   const counts = countRows();
   const order = new Map();
@@ -383,6 +476,7 @@ function render() {
 
   dom.repoList.innerHTML = html;
   restoreRepoFocus(focus);
+  restoreUrlDrafts(drafts);
 
   dom.btnAll.disabled = state.busy || !state.base || counts.behind === 0;
 }
@@ -482,10 +576,27 @@ function clearPathError() {
   dom.pathInput.closest("[data-component=text-input-v2]").removeAttribute("data-invalid");
 }
 
+function announce(message) {
+  // Espelha em #live-status (região viva permanente, fora das <section hidden>).
+  // Limpar e reescrever no frame seguinte é o que faz o leitor de tela reanunciar
+  // quando a mesma mensagem se repete — sem isso, "Ação cancelada." duas vezes
+  // seguidas só falaria uma.
+  dom.liveStatus.textContent = "";
+  const text = String(message);
+  if (REDUCED_MOTION.matches) {
+    dom.liveStatus.textContent = text;
+  } else {
+    requestAnimationFrame(() => {
+      dom.liveStatus.textContent = text;
+    });
+  }
+}
+
 function say(message, tone = "info", showToast = false) {
   dom.status.dataset.tone = tone;
   dom.statusText.textContent = message;
   dom.statusIcon.setAttribute("href", `#i-${TONE_ICON[tone] || "check"}`);
+  announce(message);
   if (showToast) toast(message, tone);
 }
 
@@ -674,7 +785,7 @@ async function doScan(options = {}) {
     if (state.auto && mapped) await doCheck(true);
   } catch (error) {
     state.lastScanFailed = true;
-    // A falha não pode pisar no que o usuário já digitou depois desta tentativa.
+    // Não sobrescreve o que o usuário digitou após esta tentativa falhar.
     if (dom.pathInput.value.trim() === path) {
       dom.pathInput.value = state.base || "";
       storeSet("alldown.path", state.base || "");
@@ -731,9 +842,11 @@ async function doUpdate(name, quiet = false) {
   if (state.busy && !quiet) return false;
   const row = state.rows.find((item) => item.name === name);
   if (!row || !row.mapped || (!quiet && row.behind !== true)) return false;
+  const index = state.rows.indexOf(row);
+  const paint = () => (quiet ? renderProgress(row, index) : render());
   if (!quiet) setBusy(true);
   row.busy = true;
-  render();
+  paint();
   say(`Atualizando ${name}…`, "info");
   try {
     const result = await api("/api/update", {
@@ -747,7 +860,6 @@ async function doUpdate(name, quiet = false) {
     row.can_rollback = Boolean(result.backup);
     if (result.zip_only) row.zip_path = result.path;
     else row.local_dir = result.path;
-    render();
     const transfer = `${formatSize(result.download_bytes)} · ${formatSpeed(result.speed_bps)}`;
     const packageSize = `${formatSize(result.old_bytes)} → ${formatSize(result.new_bytes)}`;
     say(`${name} atualizado. ${transfer}. ${packageSize}.`, "success", true);
@@ -762,18 +874,18 @@ async function doUpdate(name, quiet = false) {
         row.local_sha = row.remote_sha;
         row.behind = false;
         row.error = null;
-        render();
+        paint();
         say(`${name} foi atualizado, mas a resposta se perdeu. O estado em disco confere.`, "success", true);
         return true;
       }
       if (verdict.known) {
         row.error = verdict.reason;
-        render();
+        paint();
         say(`Falha em ${name}: ${verdict.reason}`, "danger", true);
         return false;
       }
       row.error = error.message;
-      render();
+      paint();
       say(
         `${name}: deu tempo esgotado e não deu para confirmar o estado. Reexecute o check antes de tentar de novo.`,
         "warning",
@@ -785,8 +897,11 @@ async function doUpdate(name, quiet = false) {
     say(`Falha em ${name}: ${error.message}`, "danger", true);
     return false;
   } finally {
+    // O `finally` é quem faz o último paint: nos caminhos de sucesso e de erro
+    // removemos o render() do try/catch, que era seguido imediatamente por este
+    // aqui sem nada visível no meio — metade das reconstruções do <tbody>.
     row.busy = false;
-    render();
+    paint();
     if (!quiet) {
       setBusy(false);
       refreshLog();
@@ -1158,9 +1273,26 @@ dom.btnBackup.addEventListener("click", () => {
   });
 });
 
+function validatePathInput() {
+  // Valida no `input`, não no `blur`: no blur o foco já saiu do campo, então o
+  // erro aparecia exatamente no caso que o leitor de tela não consegue anunciar
+  // (WCAG 3.3.1 / 4.1.3). Aqui o foco ainda está no input.
+  const value = dom.pathInput.value.trim();
+  if (!value || looksLikePath(value)) {
+    clearPathError();
+    return true;
+  }
+  setPathError("O caminho deve começar com / ou ~");
+  return false;
+}
+
 dom.pathInput.addEventListener("input", () => {
-  clearPathError();
+  const valid = validatePathInput();
   const value = dom.pathInput.value.trim();
+  if (!valid) {
+    say("Caminho inválido: deve começar com / ou ~", "warning", true);
+    return;
+  }
   if (!state.auto || !looksLikePath(value)) return;
   if (value === state.base && !state.lastScanFailed) return;
   window.clearTimeout(state.pathTimer);
@@ -1168,10 +1300,11 @@ dom.pathInput.addEventListener("input", () => {
 });
 
 dom.pathInput.addEventListener("blur", () => {
+  // Só cobre autofill do navegador, que não dispara `input`. Não anuncia de novo:
+  // se o erro já está visível, `role="alert"` já o comunicou.
   const value = dom.pathInput.value.trim();
-  if (!value || looksLikePath(value)) return;
+  if (!value || looksLikePath(value) || !dom.pathError.hidden) return;
   setPathError("O caminho deve começar com / ou ~");
-  say("Caminho inválido: deve começar com / ou ~", "warning", true);
 });
 
 dom.repoList.addEventListener("click", (event) => {
diff --git a/static/index.html b/static/index.html
index be7d8d3..2d7ffe7 100644
--- a/static/index.html
+++ b/static/index.html
@@ -72,7 +72,7 @@
 
     <div class="sidebar__spacer"></div>
 
-    <button class="connection-card" type="button" data-action="refresh-token" aria-live="polite" aria-label="GitHub API — revalidar cota" title="Revalidar cota da API">
+    <button class="connection-card" type="button" data-action="refresh-token" aria-label="GitHub API — revalidar cota" title="Revalidar cota da API">
       <span class="status-dot" id="token-dot" data-tone="warn"></span>
       <span class="connection-card__copy">
         <small>GitHub API</small>
@@ -113,7 +113,7 @@
       </nav>
 
       <div class="topbar__actions">
-        <span class="sync-state" id="sync-state" title="Status da operação" aria-live="polite">
+        <span class="sync-state" id="sync-state" title="Status da operação">
           <span class="status-dot" id="sync-dot" data-tone="ok"></span>
           <span id="sync-label">pronto</span>
         </span>
@@ -137,6 +137,12 @@
     <main class="page-shell" id="conteudo" data-component="scroll-view" tabindex="-1">
       <div class="page-shell__inner" data-slot="scroll-view-viewport" tabindex="0" aria-label="Conteúdo da página">
 
+        <!-- Região viva permanente: precisa existir ANTES do texto e ficar FORA das
+             <section hidden>, senão nada é anunciado em Atividade e Preferências
+             (WCAG 4.1.3). say() espelha a #status — que é só a linha visível da
+             Biblioteca — aqui. aria-atomic evita anúncio parcial. -->
+        <p class="sr-only" id="live-status" role="status" aria-live="polite" aria-atomic="true"></p>
+
         <!-- ============================ BIBLIOTECA ============================ -->
         <section class="page" data-page="library" id="library-view">
 
@@ -173,7 +179,7 @@ <h1 class="page-header__title">Biblioteca</h1>
                   <span>Escanear</span>
                 </button>
               </div>
-              <p class="field-error" id="path-error" hidden></p>
+              <p class="field-error" id="path-error" role="alert" hidden></p>
               <div class="scan-form__actions">
                 <button class="button-v2" data-component="button-v2" data-variant="neutral" data-size="small" type="button" id="btn-check" data-icon>
                   <svg class="icon" data-slot="icon" data-size="small" aria-hidden="true" focusable="false"><use href="#i-check"></use></svg>
@@ -187,7 +193,9 @@ <h1 class="page-header__title">Biblioteca</h1>
             </form>
           </section>
 
-          <div class="status-line" id="status" data-tone="info" role="status" aria-live="polite">
+          <!-- Anúncio vai para #live-status (permanente, fora das views hidden).
+               aria-live aqui causaria anúncio duplo na view Biblioteca. -->
+          <div class="status-line" id="status" data-tone="info">
             <svg class="icon" data-size="small" aria-hidden="true" focusable="false"><use href="#i-check"></use></svg>
             <span id="status-text">Cole uma pasta para começar.</span>
             <span class="status-line__progress" data-component="progress-bar" data-state="indeterminate" id="status-progress" hidden><span data-slot="progress-bar-fill"></span></span>
@@ -288,7 +296,7 @@ <h1 class="page-header__title">Preferências</h1>
                   <button data-component="switch" data-console-toggle-size="md" data-checked type="button" id="btn-auto" role="switch" aria-checked="true" aria-label="Detecção automática">
                     <span data-slot="switch-control"><span data-slot="switch-thumb"></span></span>
                   </button>
-                  <span data-component="tag" id="label-auto" aria-live="polite">Ativa</span>
+                  <span data-component="tag" id="label-auto">Ativa</span>
                 </div>
               </div>
 
@@ -301,7 +309,7 @@ <h1 class="page-header__title">Preferências</h1>
                   <button data-component="switch" data-console-toggle-size="md" type="button" id="btn-mode" role="switch" aria-checked="false" aria-label="Modo somente ZIP">
                     <span data-slot="switch-control"><span data-slot="switch-thumb"></span></span>
                   </button>
-                  <span data-component="tag" id="label-mode" aria-live="polite">Pastas</span>
+                  <span data-component="tag" id="label-mode">Pastas</span>
                 </div>
               </div>
 
@@ -314,7 +322,7 @@ <h1 class="page-header__title">Preferências</h1>
                   <button data-component="switch" data-console-toggle-size="md" data-checked type="button" id="btn-backup" role="switch" aria-checked="true" aria-label="Backup antes de trocar">
                     <span data-slot="switch-control"><span data-slot="switch-thumb"></span></span>
                   </button>
-                  <span data-component="tag" id="label-backup" aria-live="polite">Ativo</span>
+                  <span data-component="tag" id="label-backup">Ativo</span>
                 </div>
               </div>
             </div>
diff --git a/tests/js/load-app.mjs b/tests/js/load-app.mjs
index 457df20..6dc208e 100644
--- a/tests/js/load-app.mjs
+++ b/tests/js/load-app.mjs
@@ -34,7 +34,6 @@ function makeEl(tag = "div", id = "") {
     scrollTop: 0,
     scrollHeight: 0,
     clientHeight: 0,
-    firstElementChild: null,
     setAttribute(k, v) { this.attrs[k] = String(v); },
     getAttribute(k) { return this.attrs[k] ?? null; },
     removeAttribute(k) { delete this.attrs[k]; },
@@ -46,12 +45,32 @@ function makeEl(tag = "div", id = "") {
     blur() {},
     click() {},
     scrollTo() {},
-    appendChild(c) { this.children.push(c); return c; },
-    remove() { this.children = this.children.filter((x) => x !== this); },
+    appendChild(c) {
+      this.children.push(c);
+      c.parentNode = this;
+      return c;
+    },
+    // remove() precisa desparentar: filtrar os proprios filhos nao muda nada no
+    // pai, e o prune de toasts (app.js) virava laco infinito.
+    remove() {
+      if (!this.parentNode) return;
+      this.parentNode.children = this.parentNode.children.filter((x) => x !== this);
+      this.parentNode = null;
+    },
+    contains(node) {
+      if (node === this) return true;
+      return this.children.some((c) => c === node || (c.contains && c.contains(node)));
+    },
     closest: () => null,
     querySelector: () => null,
     querySelectorAll: () => [],
   };
+  // firstElementChild precisa acompanhar children: o prune de toasts
+  // (app.js) faz `dom.toastRegion.firstElementChild.remove()` e crashava com null.
+  Object.defineProperty(el, "firstElementChild", {
+    get: () => el.children[0] ?? null,
+    configurable: true,
+  });
   return el;
 }
 
@@ -90,6 +109,54 @@ export function loadApp(opts = {}) {
   mainEl.scrollTo = () => {};
 
   const repoList = byId.get("repo-list");
+
+  /* O shim nao faz parse de HTML, entao `innerHTML = html` nao cria elements.
+     Para o que importa do render, modelamos o essencial: cada atribuicao a
+     innerHTML DESTRUI os inputs velhos e recria os que o html declara — que e
+     exatamente o bug do A5. O input recem-criado tem value="" e sem foco, como
+     no DOM real, e carrega o nome da linha no aria-label para o teste poder
+     conferir que o rascunho voltou para a linha certa. */
+  repoList.__inputs = [];
+  repoList.__renders = 0; // quantas vezes o <tbody> foi reconstruido por inteiro
+  let __html = "";
+  const makeUrlInput = (index, label) => ({
+    dataset: { urlInput: index },
+    label,
+    value: "",
+    selectionStart: null,
+    selectionEnd: null,
+    focused: 0,
+    focus() {
+      this.focused += 1;
+    },
+    setSelectionRange(a, b) {
+      this.selectionStart = a;
+      this.selectionEnd = b;
+    },
+  });
+  Object.defineProperty(repoList, "innerHTML", {
+    get: () => __html,
+    set(value) {
+      __html = String(value);
+      repoList.__renders += 1;
+      repoList.__inputs = [];
+      for (const m of __html.matchAll(
+        /<input[^>]*\bdata-url-input="(\d+)"[^>]*\baria-label="([^"]*)"/g
+      )) {
+        repoList.__inputs.push(makeUrlInput(m[1], m[2].replace(/^URL do GitHub para /, "")));
+      }
+    },
+    configurable: true,
+  });
+  repoList.querySelectorAll = (sel) => (sel === "[data-url-input]" ? repoList.__inputs : []);
+  repoList.querySelector = (sel) => {
+    const m = /^\[data-url-input="(\d+)"\]$/.exec(sel);
+    if (!m) return null;
+    return repoList.__inputs.find((el) => el.dataset.urlInput === m[1]) ?? null;
+  };
+  // os inputs do formulario moram "dentro" do <tbody> para efeitos de contains()
+  repoList.contains = (node) => repoList.__inputs.includes(node) || makeEl.prototype.contains.call(repoList, node);
+
   const timers = [];
   const matchMedia = () => ({ matches: false, addEventListener() {}, addListener() {} });
 
@@ -98,6 +165,7 @@ export function loadApp(opts = {}) {
     document: {
       documentElement: makeEl("html"),
       body: makeEl("body"),
+      activeElement: null,
       getElementById: (id) => byId.get(id) ?? null,
       querySelector: (sel) => {
         if (sel === ".mobile-scrim") return makeEl("button");
@@ -128,6 +196,10 @@ export function loadApp(opts = {}) {
     AbortController,
     setTimeout: (fn) => { timers.push(fn); return timers.length; },
     clearTimeout() {},
+    // rAF enfileira no mesmo bucket de timers: o announce() e o initScrollThumb()
+    // dependem dele, e setImmediate no settle() dá a chance de rodar.
+    requestAnimationFrame: (fn) => { timers.push(fn); return timers.length; },
+    cancelAnimationFrame() {},
     setInterval: () => 0,
     URLSearchParams,
     fetch: fetchImpl ?? (async (url) => {
@@ -139,7 +211,7 @@ export function loadApp(opts = {}) {
       }
       return { ok: true, status: 200, json: async () => ({ lines: [] }) };
     }),
-    window: { addEventListener() {}, setTimeout: (fn) => { timers.push(fn); return timers.length; }, clearTimeout() {}, matchMedia },
+    window: { addEventListener() {}, setTimeout: (fn) => { timers.push(fn); return timers.length; }, clearTimeout() {}, requestAnimationFrame: (fn) => { timers.push(fn); return timers.length; }, cancelAnimationFrame() {}, matchMedia },
   };
   sandbox.globalThis = sandbox;
   sandbox.self = sandbox;
diff --git a/tests/js/render.test.mjs b/tests/js/render.test.mjs
index c2037ea..e7c8f69 100644
--- a/tests/js/render.test.mjs
+++ b/tests/js/render.test.mjs
@@ -128,6 +128,150 @@ test("branch e nome com aspas não quebram os atributos", () => {
   assert.match(html, /&quot;/);
 });
 
+/* --------------------------------------------- rascunho sobrevive ao re-render */
+/** payload de scan com uma linha sem dono, que e quem recebe o formulario de mapear */
+function scanComSemDono(nomes = ["aaa", "bbb"]) {
+  return {
+    path: "/base",
+    items: nomes.map((n) =>
+      item({ name: n, mapped: false, owner: null, repo: null, github_url: null })
+    ),
+    zip_only: false,
+    backup: true,
+  };
+}
+
+test("o que foi digitado no formulário de mapeamento sobrevive ao re-render", async () => {
+  const { sandbox: s, repoList, settle } = loadApp({
+    scan: scanComSemDono(["aaa"]),
+    path: "/base",
+    autoScan: true,
+  });
+  await settle();
+
+  const input = repoList.__inputs[0];
+  assert.ok(input, `premissa: o scan sem dono tem que renderizar o formulário:\n${repoList.innerHTML.slice(0, 300)}`);
+
+  // o usuário digita a URL e continua com o cursor no meio dela
+  const digitado = "https://github.com/acme/widget";
+  input.value = digitado;
+  input.selectionStart = 7;
+  input.selectionEnd = 7;
+  s.document.activeElement = input;
+
+  s.render(); // qualquer evento dispara isto: busca, filtro, setBusy, update
+
+  const depois = repoList.__inputs[0];
+  assert.equal(depois.value, digitado, "o texto digitado foi apagado pelo re-render");
+  assert.equal(depois.focused, 1, "o foco não voltou para o input");
+  assert.equal(depois.selectionStart, 7, "o cursor não voltou ao lugar");
+  assert.equal(depois.selectionEnd, 7);
+});
+
+test("o rascunho acompanha a LINHA, não a posição", async () => {
+  // Se o rascunho fosse chaveado pelo índice, digitar em "aaa" e depois filtrar
+  // para "bbb" jogaria a URL na linha errada — o pior tipo de bug aqui, porque
+  // "Salvar" gravaria o repositório na pessoa errada.
+  const { sandbox: s, repoList, settle } = loadApp({
+    scan: scanComSemDono(["aaa", "bbb"]),
+    path: "/base",
+    autoScan: true,
+  });
+  await settle();
+
+  const primeiro = repoList.__inputs.find((el) => el.label === "aaa");
+  assert.ok(primeiro, `premissa: as duas linhas têm formulário:\n${repoList.innerHTML.slice(0, 300)}`);
+  primeiro.value = "https://github.com/acme/aaa";
+  s.document.activeElement = primeiro;
+
+  s.setFilter("all"); // força re-render com as duas linhas visíveis
+
+  const deNovo = repoList.__inputs;
+  assert.equal(deNovo.find((el) => el.label === "aaa").value, "https://github.com/acme/aaa");
+  assert.equal(deNovo.find((el) => el.label === "bbb").value, "", "o rascunho vazou para a linha errada");
+});
+
+test("re-render repetido não duplica nem degrada o rascunho", async () => {
+  const { sandbox: s, repoList, settle } = loadApp({
+    scan: scanComSemDono(["aaa"]),
+    path: "/base",
+    autoScan: true,
+  });
+  await settle();
+  repoList.__inputs[0].value = "https://github.com/acme/widget";
+
+  for (let i = 0; i < 5; i++) s.render();
+
+  assert.equal(repoList.__inputs.length, 1, "o re-render duplicou inputs");
+  assert.equal(repoList.__inputs[0].value, "https://github.com/acme/widget");
+});
+
+/* ------------------------------------------- o lote nao reconstroi a tabela toda */
+/** scan + check de N repos pendentes: e o unico jeito de `behind` ser true
+ *  (o ScannedItem do contrato nao tem `behind` — so o CheckItem tem). */
+function cenarioLote(n = 4) {
+  const nomes = Array.from({ length: n }, (_, i) => `repo${i}`);
+  return {
+    scan: {
+      path: "/base",
+      items: nomes.map((name) => item({ name, local_sha: "1111111", remote_sha: "2222222" })),
+      zip_only: false,
+      backup: true,
+    },
+    check: nomes.map((name) =>
+      item({ name, behind: true, local_sha: "1111111", remote_sha: "2222222" })
+    ),
+  };
+}
+
+test("o lote nao reconstroi o <tbody> tres vezes por repo", async () => {
+  // Antes: cada doUpdate pintava 3x (busy, sucesso, finally) e cada pintura
+  // reescrevia as N linhas. O render do meio — seguido imediatamente pelo do
+  // finally, sem nada visível no meio — foi eliminado.
+  const { scan, check } = cenarioLote(4);
+  const { sandbox: s, repoList, settle } = loadApp({ scan, check, path: "/base", autoScan: true });
+  await settle();
+
+  const base = repoList.__renders;
+  await s.updateAll();
+  // Overhead fixo do lote: os dois renders de setBusy (abre e fecha o busy).
+  const overhead = 2;
+  const porRepo = (repoList.__renders - base - overhead) / 4;
+
+  assert.ok(
+    porRepo <= 2,
+    `o lote ainda pinta o <tbody> ${porRepo.toFixed(1)}x por repo dentro do loop ` +
+      `(${repoList.__renders - base} reconstrucoes no total; o alvo e 2, o anterior era 3)`
+  );
+});
+
+test("depois do lote, o DOM e identico ao que um render completo produziria", async () => {
+  // Este e o invariante que importa para o render cirúrgico: se a linha foi
+  // corrigida na mao e algum campo ficou defasado, o HTML final diverge do que
+  // render() produziria com o mesmo estado. O lote termina com setBusy(false),
+  // que faz o render completo — entao a comparacao tem de fechar.
+  const { scan, check } = cenarioLote(3);
+  const { sandbox: s, repoList, settle } = loadApp({ scan, check, path: "/base", autoScan: true });
+  await settle();
+
+  await s.updateAll();
+  const depoisDoLote = repoList.innerHTML;
+  s.render();
+  assert.equal(
+    repoList.innerHTML,
+    depoisDoLote,
+    "o DOM ficou defasado em relacao ao render completo — totals/summary nao foram repintados"
+  );
+});
+
+test("renderRowInPlace devolve false quando a linha nao esta na vista", () => {
+  // A queda para o render() completo e o que mantem o lote correto quando o
+  // cirúrgico nao se aplica (linha filtrada, tbody vazio, sem replaceWith).
+  const { sandbox: s } = loadApp({});
+  assert.equal(s.renderRowInPlace(item({ name: "nao-existe" }), 99), false);
+});
+
+
 /* --------------------------------------------------------- empty states */
 test("sem pasta escolhida, o empty state oferece escolher a pasta", () => {
   const { sandbox: s } = loadApp({});

From 804b8dbaddb805df35ccc545fb7b6c676867a7f5 Mon Sep 17 00:00:00 2001
From: yanhenrique-dev <yanhenrique-dev@users.noreply.github.com>
Date: Wed, 30 Sep 2026 00:08:12 -0300
Subject: [PATCH 3/6] fix(a11y): atalhos com opt-out, roving tabindex, foco da
 tabela e sidebar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A6 — atalhos E/C agora respeitam Preferências (switch "Atalhos de teclado"
persistido em alldown.shortcuts), ignoram isContentEditable e event.repeat,
e exigem que o opt-out esteja ligado. WCAG 2.1.4.

M1 — filtros como radiogroup com roving tabindex (um único tab stop, os
demais tabindex=-1), Home/End + ArrowLeft/Right. syncFilterTabIndex
chamado a cada render.

M4 — sidebar off-canvas move foco ao abrir, devolve ao gatilho ao fechar,
reseta data-open ao voltar para desktop e usa z-index 45 para não ficar
atrás do scrim.

M5/M6 — .table-scroll focalizável (tabindex+role=region) com outline em
:focus-visible; scroll-thumb com rAF e coalescing para não forçar layout a
cada mutação.

B1/B2 — stat-card usa tokens (--v2-text-stat-*) e log usa 60dvh.
B13 — aria-busy na tabela durante setBusy.
M10 — storeSet da busca dentro do debounce.

Co-authored-by: internal-model
---
 static/app.js     | 113 ++++++++++++++++++++++++++++++++++++++--------
 static/index.html |  28 +++++++++---
 static/shell.css  |  10 ++--
 static/tokens.css |   5 ++
 4 files changed, 128 insertions(+), 28 deletions(-)

diff --git a/static/app.js b/static/app.js
index fb8f4d8..71f8553 100644
--- a/static/app.js
+++ b/static/app.js
@@ -42,6 +42,8 @@ const dom = {
   btnAuto: $("btn-auto"),
   btnMode: $("btn-mode"),
   btnBackup: $("btn-backup"),
+  btnShortcuts: $("btn-shortcuts"),
+  labelShortcuts: $("label-shortcuts"),
   labelAuto: $("label-auto"),
   labelMode: $("label-mode"),
   labelBackup: $("label-backup"),
@@ -62,6 +64,7 @@ const state = {
   lastScanFailed: false,
   confirmRollback: null,
   confirmUpdate: null,
+  shortcuts: true,
   theme: "dark",
   pathTimer: null,
 };
@@ -464,6 +467,7 @@ function render() {
     button.toggleAttribute("data-pressed", active);
     button.setAttribute("aria-checked", active ? "true" : "false");
   });
+  syncFilterTabIndex();
 
   let html;
   if (state.busy && !state.rows.length && state.scanning) {
@@ -632,6 +636,10 @@ function setBusy(value) {
   dom.syncDot.dataset.tone = value ? "busy" : "ok";
   dom.syncLabel.textContent = value ? "processando" : "pronto";
   dom.statusProgress.hidden = !value;
+  // aria-busy: esqueleto é só visual, sem isso leitor de tela não sabe que a tabela
+  // está carregando (WCAG 4.1.3). data-busy só baixa opacidade e bloqueia ponteiro.
+  const table = document.getElementById("repo-table");
+  if (table) table.setAttribute("aria-busy", value ? "true" : "false");
   // O render precisa acompanhar a virada de busy: sem isso nao aparece o
   // esqueleto durante a espera da rede (/api/scan tem timeout de 900 s) e,
   // pior, um scan que volte vazio deixa a tabela presa no skeleton.
@@ -1019,6 +1027,7 @@ function paintSwitches() {
   paint(dom.btnAuto, dom.labelAuto, state.auto, "Ativa", "Pausada");
   paint(dom.btnMode, dom.labelMode, state.zipOnly, "Só ZIP", "Pastas");
   paint(dom.btnBackup, dom.labelBackup, state.backup, "Ativo", "Desligado");
+  paint(dom.btnShortcuts, dom.labelShortcuts, state.shortcuts, "Ligados", "Desligados");
 }
 
 async function postFlag(endpoint, payload, apply) {
@@ -1050,28 +1059,49 @@ async function postFlag(endpoint, payload, apply) {
 function syncSidebarAccessibility() {
   const mobile = window.matchMedia ? window.matchMedia("(max-width: 767px)").matches : false;
   const open = dom.sidebar.dataset.open === "true";
+  // Em desktop o off-canvas não existe: um data-open="true" herdado de antes do
+  // resize faria o menu reaparecer aberto, cobrindo o conteúdo, ao voltar a mobile.
+  if (!mobile && open) {
+    dom.sidebar.dataset.open = "false";
+    dom.scrim.dataset.visible = "false";
+    sidebarMenuButton()?.setAttribute("aria-expanded", "false");
+    sidebarMenuButton()?.setAttribute("aria-label", "Abrir menu");
+    return;
+  }
   dom.sidebar.inert = Boolean(mobile && !open);
   dom.sidebar.setAttribute("aria-hidden", mobile && !open ? "true" : "false");
 }
 
+function sidebarMenuButton() {
+  return document.querySelector(".topbar__menu");
+}
+
 function toggleSidebar() {
   const open = dom.sidebar.dataset.open !== "true";
   dom.sidebar.dataset.open = open ? "true" : "false";
   dom.scrim.dataset.visible = open ? "true" : "false";
-  const menu = document.querySelector(".topbar__menu");
+  const menu = sidebarMenuButton();
   menu?.setAttribute("aria-expanded", open ? "true" : "false");
   menu?.setAttribute("aria-label", open ? "Fechar menu" : "Abrir menu");
   syncSidebarAccessibility();
+  // O drawer é um off-canvas: sem mover o foco para dentro, o Tab continua no
+  // conteúdo coberto e o leitor de tela nem sinaliza que o menu abriu.
+  if (open) {
+    const first = dom.sidebar.querySelector("button, a[href]");
+    if (first) first.focus();
+  }
 }
 
-function closeSidebar() {
+function closeSidebar(options = {}) {
   if (dom.sidebar.dataset.open !== "true") return;
   dom.sidebar.dataset.open = "false";
   dom.scrim.dataset.visible = "false";
-  const menu = document.querySelector(".topbar__menu");
+  const menu = sidebarMenuButton();
   menu?.setAttribute("aria-expanded", "false");
   menu?.setAttribute("aria-label", "Abrir menu");
   syncSidebarAccessibility();
+  // Devolve o foco ao gatilho — sem isso o foco fica num elemento que sumiu.
+  if (options.returnFocus !== false) menu?.focus();
 }
 
 function focusScan() {
@@ -1085,20 +1115,32 @@ function initScrollThumb() {
   const thumb = dom.pageThumb;
   if (!viewport || !thumb) return;
 
+  let pending = false;
+  let lastState = { top: -1, height: -1, visible: "" };
   const sync = () => {
-    const { scrollTop, scrollHeight, clientHeight } = viewport;
-    const scrollable = scrollHeight - clientHeight;
-    if (scrollable <= 2) {
-      thumb.dataset.visible = "false";
-      thumb.style.height = "0px";
-      return;
-    }
-    const ratio = clientHeight / scrollHeight;
-    const height = Math.max(24, Math.round(clientHeight * ratio));
-    const offset = Math.round((scrollTop / scrollable) * (clientHeight - height));
-    thumb.dataset.visible = "true";
-    thumb.style.height = `${height}px`;
-    thumb.style.transform = `translateY(${offset}px)`;
+    if (pending) return;
+    pending = true;
+    requestAnimationFrame(() => {
+      pending = false;
+      const { scrollTop, scrollHeight, clientHeight } = viewport;
+      const scrollable = scrollHeight - clientHeight;
+      if (scrollable <= 2) {
+        if (lastState.visible !== "false") {
+          thumb.dataset.visible = "false";
+          thumb.style.height = "0px";
+          lastState = { top: -1, height: -1, visible: "false" };
+        }
+        return;
+      }
+      const ratio = clientHeight / scrollHeight;
+      const height = Math.max(24, Math.round(clientHeight * ratio));
+      const offset = Math.round((scrollTop / scrollable) * (clientHeight - height));
+      if (lastState.height === height && lastState.top === offset && lastState.visible === "true") return;
+      lastState = { top: offset, height, visible: "true" };
+      thumb.dataset.visible = "true";
+      thumb.style.height = `${height}px`;
+      thumb.style.transform = `translateY(${offset}px)`;
+    });
   };
 
   viewport.addEventListener("scroll", sync, { passive: true });
@@ -1188,6 +1230,7 @@ function init() {
 
   applyTheme(storeGet("alldown.theme") || dom.root.dataset.colorScheme || "dark", false);
   state.auto = storeGet("alldown.auto") !== "0";
+  state.shortcuts = storeGet("alldown.shortcuts") !== "0";
   dom.pathInput.value = storeGet("alldown.path") || "";
 
   paintSwitches();
@@ -1221,9 +1264,9 @@ $("form-path").addEventListener("submit", (event) => {
 let searchTimer = null;
 dom.search.addEventListener("input", (event) => {
   state.query = event.target.value;
-  storeSet("alldown.query", state.query);
   window.clearTimeout(searchTimer);
   searchTimer = window.setTimeout(() => {
+    storeSet("alldown.query", state.query);
     render();
     writeHashState();
   }, 150);
@@ -1234,13 +1277,26 @@ dom.filters.addEventListener("click", (event) => {
   if (button) setFilter(button.dataset.filter);
 });
 
+/* Roving tabindex: o APG exige UM tab stop no radiogroup, não cinco. Só o filtro
+   marcado é tabbável; as setas movem foco e seleção, como manda o padrão. */
+function syncFilterTabIndex() {
+  dom.filters.querySelectorAll("[data-filter]").forEach((button) => {
+    const checked = button.getAttribute("aria-checked") === "true";
+    button.setAttribute("tabindex", checked ? "0" : "-1");
+  });
+}
+
 dom.filters.addEventListener("keydown", (event) => {
-  if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
+  const keys = ["ArrowLeft", "ArrowRight", "Home", "End"];
+  if (!keys.includes(event.key)) return;
   const buttons = Array.from(dom.filters.querySelectorAll("[data-filter]"));
   const current = buttons.indexOf(document.activeElement);
   if (current === -1) return;
   event.preventDefault();
-  const next = (current + (event.key === "ArrowRight" ? 1 : -1) + buttons.length) % buttons.length;
+  let next;
+  if (event.key === "Home") next = 0;
+  else if (event.key === "End") next = buttons.length - 1;
+  else next = (current + (event.key === "ArrowRight" ? 1 : -1) + buttons.length) % buttons.length;
   buttons[next].focus();
   setFilter(buttons[next].dataset.filter);
 });
@@ -1273,6 +1329,21 @@ dom.btnBackup.addEventListener("click", () => {
   });
 });
 
+// Preferência só do cliente: não vai ao servidor (WCAG 2.1.4 exige forma de
+// desativar atalho de tecla única).
+dom.btnShortcuts.addEventListener("click", () => {
+  state.shortcuts = !state.shortcuts;
+  storeSet("alldown.shortcuts", state.shortcuts ? "1" : "0");
+  paintSwitches();
+  say(
+    state.shortcuts
+      ? "Atalhos de teclado ligados: E escaneia, C checa."
+      : "Atalhos de teclado desligados.",
+    "info",
+    true
+  );
+});
+
 function validatePathInput() {
   // Valida no `input`, não no `blur`: no blur o foco já saiu do campo, então o
   // erro aparecia exatamente no caso que o leitor de tela não consegue anunciar
@@ -1355,8 +1426,12 @@ document.addEventListener("keydown", (event) => {
     return;
   }
   if (event.metaKey || event.ctrlKey || event.altKey) return;
+  if (event.shiftKey) return;
+  if (!state.shortcuts) return;
+  if (event.repeat) return; // segurar a tecla nao deve repetir a operacao
   const tag = event.target?.tagName || "";
   if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return;
+  if (event.target?.isContentEditable) return;
   const key = event.key.toLowerCase();
   if (key === "e") {
     event.preventDefault();
diff --git a/static/index.html b/static/index.html
index 2d7ffe7..759b001 100644
--- a/static/index.html
+++ b/static/index.html
@@ -225,17 +225,20 @@ <h1 class="page-header__title">Biblioteca</h1>
               </label>
 
               <div data-component="segmented-control-v2" id="filters" role="radiogroup" aria-label="Filtrar repositórios">
-                <button type="button" role="radio" aria-checked="true" data-filter="all" data-pressed data-slot="segmented-control-v2-item"><span data-slot="segmented-control-v2-item-label"><span data-slot="segmented-control-v2-item-text">Todos</span><span data-slot="segmented-control-v2-item-count" id="c-all">0</span></span></button>
-                <button type="button" role="radio" aria-checked="false" data-filter="behind" data-slot="segmented-control-v2-item"><span data-slot="segmented-control-v2-item-label"><span data-slot="segmented-control-v2-item-text">Atualizar</span><span data-slot="segmented-control-v2-item-count" id="c-behind">0</span></span></button>
-                <button type="button" role="radio" aria-checked="false" data-filter="ready" data-slot="segmented-control-v2-item"><span data-slot="segmented-control-v2-item-label"><span data-slot="segmented-control-v2-item-text">Em dia</span><span data-slot="segmented-control-v2-item-count" id="c-ok">0</span></span></button>
-                <button type="button" role="radio" aria-checked="false" data-filter="unmapped" data-slot="segmented-control-v2-item"><span data-slot="segmented-control-v2-item-label"><span data-slot="segmented-control-v2-item-text">Sem dono</span><span data-slot="segmented-control-v2-item-count" id="c-unmapped">0</span></span></button>
-                <button type="button" role="radio" aria-checked="false" data-filter="error" data-slot="segmented-control-v2-item"><span data-slot="segmented-control-v2-item-label"><span data-slot="segmented-control-v2-item-text">Erros</span><span data-slot="segmented-control-v2-item-count" id="c-error">0</span></span></button>
+                <button type="button" role="radio" aria-checked="true" data-filter="all" tabindex="0" data-pressed data-slot="segmented-control-v2-item"><span data-slot="segmented-control-v2-item-label"><span data-slot="segmented-control-v2-item-text">Todos</span><span data-slot="segmented-control-v2-item-count" id="c-all">0</span></span></button>
+                <button type="button" role="radio" aria-checked="false" data-filter="behind" tabindex="-1" data-slot="segmented-control-v2-item"><span data-slot="segmented-control-v2-item-label"><span data-slot="segmented-control-v2-item-text">Atualizar</span><span data-slot="segmented-control-v2-item-count" id="c-behind">0</span></span></button>
+                <button type="button" role="radio" aria-checked="false" data-filter="ready" tabindex="-1" data-slot="segmented-control-v2-item"><span data-slot="segmented-control-v2-item-label"><span data-slot="segmented-control-v2-item-text">Em dia</span><span data-slot="segmented-control-v2-item-count" id="c-ok">0</span></span></button>
+                <button type="button" role="radio" aria-checked="false" data-filter="unmapped" tabindex="-1" data-slot="segmented-control-v2-item"><span data-slot="segmented-control-v2-item-label"><span data-slot="segmented-control-v2-item-text">Sem dono</span><span data-slot="segmented-control-v2-item-count" id="c-unmapped">0</span></span></button>
+                <button type="button" role="radio" aria-checked="false" data-filter="error" tabindex="-1" data-slot="segmented-control-v2-item"><span data-slot="segmented-control-v2-item-label"><span data-slot="segmented-control-v2-item-text">Erros</span><span data-slot="segmented-control-v2-item-count" id="c-error">0</span></span></button>
               </div>
             </div>
 
             <div data-component="divider-v2"></div>
 
-            <div class="table-scroll">
+            <!-- tabindex + role=region: sem isso a tabela de 7 colunas só rola
+                 horizontalmente por mouse (WCAG 2.1.1). O app já faz o mesmo em
+                 #page-shell__inner e no <pre id="log">. -->
+            <div class="table-scroll" tabindex="0" role="region" aria-label="Tabela de repositórios, rolagem horizontal">
               <table data-component="data-table" id="repo-table">
                 <caption class="sr-only">Repositórios detectados na pasta em serviço</caption>
                 <thead>
@@ -325,6 +328,19 @@ <h1 class="page-header__title">Preferências</h1>
                   <span data-component="tag" id="label-backup">Ativo</span>
                 </div>
               </div>
+
+              <div class="setting-row">
+                <div class="setting-row__copy">
+                  <span class="setting-row__title">Atalhos de teclado</span>
+                  <span class="setting-row__body">Teclas <code>E</code> (escanear) e <code>C</code> (checar) sem modificador. Desligue se preferir não acionar operações pelo teclado.</span>
+                </div>
+                <div class="setting-row__control">
+                  <button data-component="switch" data-console-toggle-size="md" data-checked type="button" id="btn-shortcuts" role="switch" aria-checked="true" aria-label="Atalhos de teclado">
+                    <span data-slot="switch-control"><span data-slot="switch-thumb"></span></span>
+                  </button>
+                  <span data-component="tag" id="label-shortcuts">Ligados</span>
+                </div>
+              </div>
             </div>
           </section>
 
diff --git a/static/shell.css b/static/shell.css
index 504233f..3f9b417 100644
--- a/static/shell.css
+++ b/static/shell.css
@@ -199,7 +199,9 @@
 .topbar {
   position: sticky;
   top: 0;
-  z-index: 20;
+  /* Acima do .mobile-scrim (40) para que o botão de fechar o menu não fique
+     atrás do overlay com o menu aberto — e abaixo da .sidebar (50). */
+  z-index: 45;
   display: flex;
   align-items: center;
   gap: 8px;
@@ -358,7 +360,7 @@
   box-shadow: var(--v2-elevation-raised);
 }
 .stat-card__label { display: flex; align-items: center; gap: 6px; color: var(--v2-text-text-muted); font-size: var(--v2-text-label-size); font-weight: var(--v2-weight-medium); line-height: var(--v2-text-label-line); letter-spacing: var(--v2-text-label-tracking); }
-.stat-card__value { color: var(--v2-text-text-base); font-size: 24px; font-weight: var(--v2-weight-emphasis); line-height: 28px; letter-spacing: -0.4px; font-variant-numeric: tabular-nums; }
+.stat-card__value { color: var(--v2-text-text-base); font-size: var(--v2-text-stat-size); font-weight: var(--v2-weight-emphasis); line-height: var(--v2-text-stat-line); letter-spacing: var(--v2-text-stat-spacing); font-variant-numeric: tabular-nums; }
 .stat-card__hint { color: var(--v2-text-text-faint); font-size: var(--v2-text-micro-size); line-height: 1; letter-spacing: var(--v2-text-micro-tracking); }
 .stat-card[data-tone="success"] .stat-card__value { color: var(--v2-state-fg-success); }
 .stat-card[data-tone="warning"] .stat-card__value { color: var(--v2-state-fg-warning); }
@@ -379,6 +381,8 @@
 .library-toolbar [data-component="segmented-control-v2"]::-webkit-scrollbar { display: none; }
 
 .table-scroll { max-width: 100%; overflow-x: auto; scrollbar-width: thin; scrollbar-color: var(--v2-border-border-muted) transparent; }
+/* Focalizável (tabindex no HTML) precisa de indicador de foco — WCAG 2.4.7. */
+.table-scroll:focus-visible { outline: 2px solid var(--v2-border-border-focus); outline-offset: -2px; }
 
 /* Pilha de conteúdo dentro de uma célula (identidade + nota). */
 .cell-stack { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
@@ -410,7 +414,7 @@
    Atividade
    -------------------------------------------------------------------------- */
 .log-panel { display: flex; flex-direction: column; min-height: 0; gap: 12px; }
-.log-viewport { max-height: min(60vh, 520px); overflow: auto; scrollbar-width: thin; scrollbar-color: var(--v2-border-border-muted) transparent; }
+.log-viewport { max-height: min(60dvh, 520px); overflow: auto; scrollbar-width: thin; scrollbar-color: var(--v2-border-border-muted) transparent; }
 .log-viewport pre { margin: 0; padding: 12px; border-radius: var(--v2-radius-control); background: var(--v2-background-bg-layer-02); color: var(--v2-text-text-muted); font-family: var(--v2-font-family-mono); font-size: var(--v2-text-micro-size); line-height: 16px; letter-spacing: 0; white-space: pre-wrap; overflow-wrap: anywhere; }
 
 /* --------------------------------------------------------------------------
diff --git a/static/tokens.css b/static/tokens.css
index 18a0d21..f570663 100644
--- a/static/tokens.css
+++ b/static/tokens.css
@@ -268,6 +268,11 @@
   --v2-motion-toast: 280ms cubic-bezier(0.2, 0, 0, 1);
   --v2-motion-toast-opacity: 160ms ease-out;
 
+  /* Stat card — valores literais movidos para tokens (regra: só tokens nos valores). */
+  --v2-text-stat-size: 24px;
+  --v2-text-stat-line: 28px;
+  --v2-text-stat-spacing: -0.4px;
+
   /* Geometria do shell (§3 do enunciado) */
   --v2-header-height: 48px;
   --v2-sidebar-width: 232px;

From 42a4c5bf94927b84fd048a792417149add685b23 Mon Sep 17 00:00:00 2001
From: yanhenrique-dev <yanhenrique-dev@users.noreply.github.com>
Date: Wed, 30 Sep 2026 00:33:53 -0300
Subject: [PATCH 4/6] feat(frontend): reforma visual, arquitetural e de
 performance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Visual/UX:
- stat-cards viram botões que filtram a lista (data-filter-link + data-active)
- steps 01/02/03 refletem o progresso real (paintSteps: pasta, check, tudo em dia)
- thead sticky com fundo da camada; breadcrumb com aria-current
- map-form em <form>: Enter salva, submit delegado (antes só o clique)
- forced-colors: foco via Highlight, status-dot sem ajuste forçado

Código (app.js, sem build, mesmo contrato):
- handleAction (cadeia de ifs) vira tabela ACTIONS + helpers + try/catch
- todos os listeners em registerEvents() chamado pelo init (B5)
- despachante único de clique com guarda barata (B8/B9: 1× closest)
- cancelPendingScan() em todos os gatilhos de scan (B10)
- focusScan via rAF, sem setTimeout frágil (B12)
- render() com error boundary (I5); FILTER_INFO sem label duplicado (B4)

Performance/serving (app.py):
- GZipMiddleware (minimum 500B): ~100KB CSS+47KB JS -> ~15KB
- CSP completa (object-src/base-uri/frame-ancestors/form-action none/self)
  + Permissions-Policy; Cache-Control immutable para ?v=
- ?v= unificado em v3 nos 5 assets (B16)
- components-optional.css: textarea/select/checkbox/tooltip/drawer/dialog/menu
  fora do crítico (~7KB gzip poupados, B6); tokens duplicados removidos (B3)
- stat-card em tokens, log em dvh, aria-busy na tabela (B1/B2/B13)

Gate: 169 pytest + 38 node --test + node --check + ruff + pyright verdes.
---
 README.md                      |   5 +-
 STYLEGUIDE.md                  |  20 +-
 app.py                         |  20 +-
 static/app.js                  | 527 +++++++++++++++++++--------------
 static/components-optional.css | 383 ++++++++++++++++++++++++
 static/components.css          | 379 +-----------------------
 static/index.html              |  26 +-
 static/shell.css               |  17 +-
 static/tokens.css              |  15 +-
 9 files changed, 757 insertions(+), 635 deletions(-)
 create mode 100644 static/components-optional.css

diff --git a/README.md b/README.md
index b438738..3d39ded 100644
--- a/README.md
+++ b/README.md
@@ -93,7 +93,8 @@ Abra **http://127.0.0.1:8000**, cole a pasta dos repos — a detecção é autom
 │   ├── updater.py    # download, troca, backup, rollback
 │   └── state.py      # mapping / state / config por pasta (.alldown/)
 ├── static/           # front vanilla: index.html, tokens.css, components.css,
-│                     #   shell.css, app.js, theme.js, contract/openapi.json
+│                     #   components-optional.css (fora do crítico), shell.css,
+│                     #   app.js, theme.js, contract/openapi.json
 ├── tests/js/         # testes do frontend (node --test, sem build)
 ├── pyproject.toml    # lint e pytest
 └── requirements.txt
@@ -109,7 +110,7 @@ Execute estes comandos antes de abrir pull request:
 
 ```bash
 .venv/bin/python -m pytest tests/ -q          # 169 testes (backend + contrato)
-node --test tests/js/*.test.mjs                # 23 testes do frontend
+node --test tests/js/*.test.mjs                # 38 testes do frontend
 node --check static/app.js
 uvx --from ruff==0.16.8 ruff check app.py core tray.py tests/
 uvx --from pyright==1.1.414 pyright --pythonpath .venv/bin/python app.py core tray.py
diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md
index e3a2632..d834ffa 100644
--- a/STYLEGUIDE.md
+++ b/STYLEGUIDE.md
@@ -11,13 +11,16 @@ Nenhum valor foi inventado. Se não está no CSS-fonte, não está aqui.
 | Arquivo | Conteúdo |
 |---|---|
 | `static/tokens.css` | Rampas, alfa, cores de estado, semânticos light/dark, elevação, raios, tipografia, movimento |
-| `static/components.css` | Primitives com `data-component` / `data-slot` |
+| `static/components.css` | Primitives em uso no caminho crítico (`button`, `input`, `switch`, `tag`, `segmented`, `avatar`, `card`, `toast`, `data-table`, `scroll-view`, …) |
+| `static/components-optional.css` | Primitives fora do caminho crítico (`textarea`, `select`, `checkbox`, `tooltip`, `drawer`, `dialog`, `menu`) — **não** carregado por padrão, ~7KB gzip poupados |
 | `static/shell.css` | Grid do app, sidebar, header, page shell, as três telas |
 | `static/theme.js` | Aplica o tema antes da primeira pintura (bloqueante, por causa da CSP) |
 | `static/index.html` | Markup das três telas e a ordem de carga |
 | `STYLEGUIDE.md` | Este documento |
 
 Ordem de carga no HTML: `theme.js` → `tokens.css` → `components.css` → `shell.css`.
+Versão única `?v=3` nos quatro assets + `theme.js` (antes `?v=1`/`?v=2`/sem versão,
+sempre inconsistente). `Cache-Control: immutable` no servidor para `?v=`.
 
 ## Convenção de atributos
 
@@ -151,24 +154,24 @@ neste sistema. Monospace: `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas
 | `button-v2` | `small` 24 · `normal` 28 · `large` 32 | `neutral` `contrast` `outline` `ghost` `ghost-muted` `danger` `warning` `loading` |
 | `icon-button-v2` | `small` 20 · `normal` 24 · `large` 28 | `neutral` `contrast` `ghost` `ghost-muted` |
 | `text-input-v2` | 28 (32 `large`) | — + `data-invalid` `data-disabled` `data-numeric` `data-leading-icon` |
-| `textarea-v2` | `min-height: 80px`, `resize: vertical` | idem |
-| `select-v2` | 28 | idem |
-| `checkbox-v2` | `16×16`, raio `4px` | `data-checked` `data-invalid` `data-disabled` |
+| `textarea-v2` | `min-height: 80px`, `resize: vertical` | idem | **opcional** |
+| `select-v2` | 28 | idem | **opcional** |
+| `checkbox-v2` | `16×16`, raio `4px` | `data-checked` `data-invalid` `data-disabled` | **opcional** |
 | `switch` | `data-console-toggle-size="md"` → 32×20, thumb 16 | `data-checked` |
 | `tag` | `16px`, raio `2px` | `accent` `success` `warning` `danger` `info` `mono` + `data-high-contrast` |
 | `segmented-control-v2` | 28, `box-shadow: 0 0 0 .5px` | `data-pressed` no item |
 | `avatar-v2` | 16 / 20 / 24 / 28 | `data-tone` = 10 cores + `data-kind="org"` |
-| `tooltip-v2` | `5px 6px`, raio `4px`, 11/12 | — |
+| `tooltip-v2` | `5px 6px`, raio `4px`, 11/12 | — | **opcional** |
 | `toast-v2` | 320px, raio `8px`, grid `1fr 20px` | `data-tone` |
-| `drawer` | `min(100vw, 40rem)` | `data-closed` no painel |
-| `dialog-v2` | 480 (`large` 640), raio `12px` | `data-size` |
+| `drawer` | `min(100vw, 40rem)` | `data-closed` no painel | **opcional** |
+| `dialog-v2` | 480 (`large` 640), raio `12px` | `data-size` | **opcional** |
 | `data-table` | header 32 · row 40 | `data-align="end"` + `tabular-nums` |
 | `card` | padding 16 (`large` 20) | `data-interactive` |
 | `scroll-view` | thumb 4px, trilho 12px | `data-visible` |
 | `progress-bar` | 4px | `data-variant` `data-state="indeterminate"` |
 | `empty-state` / `skeleton` | — | `data-shape` no skeleton |
 | `divider-v2` | `1px` com `scaleY(.5)` | `data-orientation` |
-| `menu-v2-content` / `menu-v2-item` | item 28, raio `4px` | `data-checked` `data-highlighted` |
+| `menu-v2-content` / `menu-v2-item` | item 28, raio `4px` | `data-checked` `data-highlighted` | **opcional** |
 | `field-v2` / `inline-input-v2` / `loader-v2` | — | — |
 
 ## Movimento
@@ -246,6 +249,7 @@ Toda outra superfície de cor e tamanho deve continuar vindo de token.
 
 ```bash
 node --check static/app.js        # sintaxe
+node --test tests/js/*.test.mjs   # 38 testes do frontend
 .venv/bin/python -m pytest tests/ -q
 uvx --from ruff==0.16.8 ruff check app.py core tray.py
 ```
diff --git a/app.py b/app.py
index 297c7a3..47aa83d 100644
--- a/app.py
+++ b/app.py
@@ -14,6 +14,7 @@
 
 from dotenv import load_dotenv
 from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.gzip import GZipMiddleware
 from fastapi.responses import FileResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel, Field
@@ -99,6 +100,9 @@ async def lifespan(_: FastAPI):
 
 
 app = FastAPI(title="RepoRefresh", lifespan=lifespan)
+# M11: /static puro transfere ~100KB de CSS + 47KB de JS sem compressão.
+# GZip reduz o cold load para ~15KB sem tocar em rota ou contrato.
+app.add_middleware(GZipMiddleware, minimum_size=500)
 app.mount("/static", StaticFiles(directory="static"), name="static")
 
 
@@ -154,10 +158,24 @@ async def local_only(request: Request, call_next):
     response.headers["X-Content-Type-Options"] = "nosniff"
     response.headers["X-Frame-Options"] = "DENY"
     response.headers["Referrer-Policy"] = "no-referrer"
+    response.headers["Permissions-Policy"] = "geolocation=(), camera=(), microphone=()"
+    # M12: blindagem sem unsafe-inline (theme.js é arquivo separado por isso).
+    # object-src/base-uri/frame-ancestors fecham injeção de plugin, <base> e
+    # embed; form-action trava o <form action="#"> da Biblioteca.
     response.headers["Content-Security-Policy"] = (
-        "default-src 'self'; script-src 'self'; style-src 'self'; "
+        "default-src 'self'; object-src 'none'; base-uri 'none'; "
+        "frame-ancestors 'none'; form-action 'self'; "
+        "script-src 'self'; style-src 'self'; "
         "img-src 'self' data:; font-src 'self'; connect-src 'self'"
     )
+    # Assets versionados (?v=) são imutáveis; o resto do /static revalida em 1h.
+    # StaticFiles já trata etag/304 — isto só corta o cold load repetido.
+    if request.url.path.startswith("/static/"):
+        query = request.url.query or ""
+        if "v=" in query:
+            response.headers["Cache-Control"] = "public, max-age=31536000, immutable"
+        elif "Cache-Control" not in response.headers:
+            response.headers["Cache-Control"] = "public, max-age=3600"
     return response
 
 
diff --git a/static/app.js b/static/app.js
index 71f8553..c2d3c96 100644
--- a/static/app.js
+++ b/static/app.js
@@ -70,11 +70,12 @@ const state = {
 };
 
 const FILTER_INFO = {
-  all: { label: "Todos", test: () => true },
-  behind: { label: "Atualizar", test: (row) => row.behind === true },
-  ready: { label: "Em dia", test: (row) => row.behind === false },
-  unmapped: { label: "Sem dono", test: (row) => !row.mapped },
-  error: { label: "Erros", test: (row) => Boolean(row.error) },
+  // B4: sem `label` — o texto do filtro vive no HTML (index.html), fonte única.
+  all: { test: () => true },
+  behind: { test: (row) => row.behind === true },
+  ready: { test: (row) => row.behind === false },
+  unmapped: { test: (row) => !row.mapped },
+  error: { test: (row) => Boolean(row.error) },
 };
 
 const VIEWS = ["library", "activity", "settings"];
@@ -244,19 +245,19 @@ function renderMapForm(row, index) {
       ? `<span class="repo-note">${icon("search", "small")} ${esc(row.tried.join(" · "))}</span>`
       : "";
   return `<tr class="map-row" data-map-index="${index}"><td colspan="7">
-      <div class="map-form">
+      <form class="map-form" data-map-form="${index}">
         <label class="text-input-v2" data-component="text-input-v2" for="url-${index}">
           <span data-slot="text-input-v2-value">
             <input id="url-${index}" data-url-input="${index}" type="url" inputmode="url" autocomplete="off" spellcheck="false" placeholder="https://github.com/dono/repo…" aria-label="URL do GitHub para ${esc(row.name)}" data-slot="text-input-v2-input">
           </span>
         </label>
-        <button class="button-v2" data-component="button-v2" data-variant="contrast" data-size="normal" type="button" data-action="save-map" data-index="${index}" data-icon>
+        <button class="button-v2" data-component="button-v2" data-variant="contrast" data-size="normal" type="submit" data-action="save-map" data-index="${index}" data-icon>
           ${icon("check")}<span>Salvar</span>
         </button>
         <button class="button-v2" data-component="button-v2" data-variant="neutral" data-size="normal" type="button" data-action="suggest" data-index="${index}" data-icon>
           ${icon("spark")}<span>Sugerir</span>
         </button>
-      </div>
+      </form>
       ${tried ? `<div class="map-suggestions">${tried}</div>` : ""}
       ${suggestions}
     </td></tr>`;
@@ -449,6 +450,30 @@ function renderProgress(row, index) {
 }
 
 function render() {
+  // I5: error boundary — um row com formato inesperado do servidor derrubava
+  // a app inteira sem feedback. Agora a falha vira mensagem, não tela morta.
+  try {
+    renderUnsafe();
+  } catch (error) {
+    say(`Falha ao desenhar a lista: ${error.message}`, "danger", true);
+  }
+}
+
+function paintSteps(counts) {
+  // As 3 etapas do topo refletem o progresso real, não são decorativas.
+  const locate = $("step-locate");
+  const compare = $("step-compare");
+  const swap = $("step-swap");
+  if (locate) locate.dataset.done = state.base ? "true" : "false";
+  const checked = state.rows.some((row) => row.behind !== undefined && row.behind !== null || row.error);
+  if (compare) compare.dataset.done = checked ? "true" : "false";
+  if (swap) swap.dataset.done = state.base && counts.behind === 0 && counts.all > 0 ? "true" : "false";
+  document.querySelectorAll("[data-filter-link]").forEach((card) => {
+    card.dataset.active = card.dataset.filterLink === state.filter ? "true" : "false";
+  });
+}
+
+function renderUnsafe() {
   const focus = focusedRepoAction();
   const drafts = captureUrlDrafts();
   const rows = visibleRows();
@@ -468,6 +493,7 @@ function render() {
     button.setAttribute("aria-checked", active ? "true" : "false");
   });
   syncFilterTabIndex();
+  paintSteps(counts);
 
   let html;
   if (state.busy && !state.rows.length && state.scanning) {
@@ -770,6 +796,7 @@ async function doScan(options = {}) {
     return;
   }
   if (state.busy && options.allowBusy !== true) return;
+  cancelPendingScan();
   state.scanning = true;
   state.confirmRollback = null;
   state.confirmUpdate = null;
@@ -1105,8 +1132,13 @@ function closeSidebar(options = {}) {
 }
 
 function focusScan() {
+  // B12: sem setTimeout(40) frágil — o foco acontece no próximo frame,
+  // depois que setView tirou o hidden da Biblioteca.
   setView("library");
-  window.setTimeout(() => dom.pathInput.focus(), 40);
+  cancelPendingScan();
+  const focus = () => dom.pathInput.focus({ preventScroll: false });
+  if (typeof window.requestAnimationFrame === "function") window.requestAnimationFrame(focus);
+  else focus();
 }
 
 /* ------------------------------------------------------------ scroll thumb */
@@ -1152,69 +1184,102 @@ function initScrollThumb() {
 /* ------------------------------------------------------------------ ações */
 const BUSY_ACTIONS = new Set(["check-row", "update-row", "rollback-row", "save-map", "suggest", "pick-suggestion", "refresh", "refresh-log"]);
 
-function handleAction(action, element) {
-  const index = Number(element.dataset.index);
-  if (state.busy && BUSY_ACTIONS.has(action)) return;
-  if (action !== "update-row" && state.confirmUpdate) {
-    state.confirmUpdate = null;
-    render();
+// B10: o timer de auto-scan (700ms) ficava pendente quando outro gatilho
+// disparava o scan (submit, atalho E, switch auto) — dois scans em sequência.
+function cancelPendingScan() {
+  if (state.pathTimer) {
+    window.clearTimeout(state.pathTimer);
+    state.pathTimer = null;
   }
+}
 
-  if (action === "toggle-sidebar") toggleSidebar();
-  if (action === "close-sidebar") closeSidebar();
-  if (action === "toggle-theme") applyTheme(state.theme === "dark" ? "light" : "dark");
-  if (action === "focus-scan") focusScan();
-  if (action === "refresh-token") refreshToken();
-  if (action === "refresh-log") refreshLog();
-  if (action === "reset-filter") {
-    state.filter = "all";
-    state.query = "";
-    storeSet("alldown.filter", "all");
-    storeSet("alldown.query", "");
-    render();
-    writeHashState();
-  }
-  if (action === "refresh" || action === "check-row") {
-    if (state.base) doCheck();
-    else focusScan();
-  }
-  if (action === "update-row") {
-    const row = state.rows[index];
-    if (row?.behind === true) {
-      if (state.confirmUpdate !== row.name) {
-        state.confirmUpdate = row.name;
-        state.confirmRollback = null;
-        render();
-        say(`Confirme a atualização de ${row.name}: clique no botão de novo.`, "warning", true);
-        return;
-      }
-      state.confirmUpdate = null;
-      doUpdate(row.name);
-    } else {
-      doCheck();
-    }
-  }
-  if (action === "rollback-row") {
-    const name = state.rows[index]?.name;
-    if (!name) return;
-    if (state.confirmRollback !== name) {
-      state.confirmRollback = name;
-      state.confirmUpdate = null;
+function resetFilterAndQuery() {
+  state.filter = "all";
+  state.query = "";
+  storeSet("alldown.filter", "all");
+  storeSet("alldown.query", "");
+  render();
+  writeHashState();
+}
+
+function refreshOrFocus() {
+  if (state.base) doCheck();
+  else focusScan();
+}
+
+function confirmUpdateRow(index) {
+  const row = state.rows[index];
+  if (row?.behind === true) {
+    if (state.confirmUpdate !== row.name) {
+      state.confirmUpdate = row.name;
+      state.confirmRollback = null;
       render();
-      say(`Confirme a reversão de ${name}: clique no botão de novo.`, "warning", true);
+      say(`Confirme a atualização de ${row.name}: clique no botão de novo.`, "warning", true);
       return;
     }
-    state.confirmRollback = null;
-    doRollback(name);
+    state.confirmUpdate = null;
+    doUpdate(row.name);
+  } else {
+    doCheck();
   }
-  if (action === "save-map") {
-    const input = dom.repoList.querySelector(`[data-url-input="${index}"]`);
-    mapRepo(index, input?.value);
+}
+
+function confirmRollbackRow(index) {
+  const name = state.rows[index]?.name;
+  if (!name) return;
+  if (state.confirmRollback !== name) {
+    state.confirmRollback = name;
+    state.confirmUpdate = null;
+    render();
+    say(`Confirme a reversão de ${name}: clique no botão de novo.`, "warning", true);
+    return;
+  }
+  state.confirmRollback = null;
+  doRollback(name);
+}
+
+function saveMapFrom(index) {
+  const input = dom.repoList.querySelector(`[data-url-input="${index}"]`);
+  mapRepo(index, input?.value);
+}
+
+function pickSuggestion(index, element) {
+  const suggestion = state.rows[index]?.suggestions?.[Number(element.dataset.suggestion)];
+  if (suggestion) mapRepo(index, suggestion.url);
+}
+
+// B7: tabela em vez de cadeia de ifs — adicionar ação = adicionar entrada,
+// sem tocar no meio do despachante. Ações desconhecidas são ignoradas.
+const ACTIONS = {
+  "toggle-sidebar": () => toggleSidebar(),
+  "close-sidebar": () => closeSidebar(),
+  "toggle-theme": () => applyTheme(state.theme === "dark" ? "light" : "dark"),
+  "focus-scan": () => focusScan(),
+  "refresh-token": () => refreshToken(),
+  "refresh-log": () => refreshLog(),
+  "reset-filter": () => resetFilterAndQuery(),
+  "refresh": () => refreshOrFocus(),
+  "check-row": () => refreshOrFocus(),
+  "update-row": (index) => confirmUpdateRow(index),
+  "rollback-row": (index) => confirmRollbackRow(index),
+  "save-map": (index) => saveMapFrom(index),
+  "suggest": (index) => suggestRepo(index),
+  "pick-suggestion": (index, element) => pickSuggestion(index, element),
+};
+
+function handleAction(action, element) {
+  const handler = ACTIONS[action];
+  if (!handler) return;
+  const index = Number(element.dataset.index);
+  if (state.busy && BUSY_ACTIONS.has(action)) return;
+  if (action !== "update-row" && state.confirmUpdate) {
+    state.confirmUpdate = null;
+    render();
   }
-  if (action === "suggest") suggestRepo(index);
-  if (action === "pick-suggestion") {
-    const suggestion = state.rows[index]?.suggestions?.[Number(element.dataset.suggestion)];
-    if (suggestion) mapRepo(index, suggestion.url);
+  try {
+    handler(index, element);
+  } catch (error) {
+    say(`Falha na ação: ${error.message}`, "danger", true);
   }
 }
 
@@ -1238,6 +1303,7 @@ function init() {
   setBusy(false);
   setView(state.view);
   syncSidebarAccessibility();
+  registerEvents();
   initScrollThumb();
   refreshToken();
   refreshLog();
@@ -1255,27 +1321,6 @@ function init() {
   if (state.auto && looksLikePath(dom.pathInput.value.trim())) window.setTimeout(doScan, 120);
 }
 
-$("form-path").addEventListener("submit", (event) => {
-  event.preventDefault();
-  window.clearTimeout(state.pathTimer);
-  doScan();
-});
-
-let searchTimer = null;
-dom.search.addEventListener("input", (event) => {
-  state.query = event.target.value;
-  window.clearTimeout(searchTimer);
-  searchTimer = window.setTimeout(() => {
-    storeSet("alldown.query", state.query);
-    render();
-    writeHashState();
-  }, 150);
-});
-
-dom.filters.addEventListener("click", (event) => {
-  const button = event.target.closest("[data-filter]");
-  if (button) setFilter(button.dataset.filter);
-});
 
 /* Roving tabindex: o APG exige UM tab stop no radiogroup, não cinco. Só o filtro
    marcado é tabbável; as setas movem foco e seleção, como manda o padrão. */
@@ -1286,64 +1331,6 @@ function syncFilterTabIndex() {
   });
 }
 
-dom.filters.addEventListener("keydown", (event) => {
-  const keys = ["ArrowLeft", "ArrowRight", "Home", "End"];
-  if (!keys.includes(event.key)) return;
-  const buttons = Array.from(dom.filters.querySelectorAll("[data-filter]"));
-  const current = buttons.indexOf(document.activeElement);
-  if (current === -1) return;
-  event.preventDefault();
-  let next;
-  if (event.key === "Home") next = 0;
-  else if (event.key === "End") next = buttons.length - 1;
-  else next = (current + (event.key === "ArrowRight" ? 1 : -1) + buttons.length) % buttons.length;
-  buttons[next].focus();
-  setFilter(buttons[next].dataset.filter);
-});
-
-dom.btnCheck.addEventListener("click", () => doCheck());
-dom.btnAll.addEventListener("click", updateAll);
-
-dom.btnAuto.addEventListener("click", () => {
-  state.auto = !state.auto;
-  storeSet("alldown.auto", state.auto ? "1" : "0");
-  paintSwitches();
-  say(state.auto ? "Detecção automática ativada." : "Detecção automática pausada.", "info", true);
-  const value = dom.pathInput.value.trim();
-  if (state.auto && looksLikePath(value) && value !== state.base) doScan();
-});
-
-dom.btnMode.addEventListener("click", () => {
-  const next = !state.zipOnly;
-  postFlag("/api/mode", { zip_only: next }, (result) => {
-    state.zipOnly = Boolean(result.zip_only);
-    say(state.zipOnly ? "Modo somente ZIP ativado." : "Modo pasta ativado.", "success", true);
-  });
-});
-
-dom.btnBackup.addEventListener("click", () => {
-  const next = !state.backup;
-  postFlag("/api/backup", { backup: next }, (result) => {
-    state.backup = Boolean(result.backup);
-    say(state.backup ? "Backup ativado." : "Backup desligado.", "success", true);
-  });
-});
-
-// Preferência só do cliente: não vai ao servidor (WCAG 2.1.4 exige forma de
-// desativar atalho de tecla única).
-dom.btnShortcuts.addEventListener("click", () => {
-  state.shortcuts = !state.shortcuts;
-  storeSet("alldown.shortcuts", state.shortcuts ? "1" : "0");
-  paintSwitches();
-  say(
-    state.shortcuts
-      ? "Atalhos de teclado ligados: E escaneia, C checa."
-      : "Atalhos de teclado desligados.",
-    "info",
-    true
-  );
-});
-
 function validatePathInput() {
   // Valida no `input`, não no `blur`: no blur o foco já saiu do campo, então o
   // erro aparecia exatamente no caso que o leitor de tela não consegue anunciar
@@ -1357,90 +1344,186 @@ function validatePathInput() {
   return false;
 }
 
-dom.pathInput.addEventListener("input", () => {
-  const valid = validatePathInput();
-  const value = dom.pathInput.value.trim();
-  if (!valid) {
-    say("Caminho inválido: deve começar com / ou ~", "warning", true);
-    return;
-  }
-  if (!state.auto || !looksLikePath(value)) return;
-  if (value === state.base && !state.lastScanFailed) return;
-  window.clearTimeout(state.pathTimer);
-  state.pathTimer = window.setTimeout(doScan, 700);
-});
-
-dom.pathInput.addEventListener("blur", () => {
-  // Só cobre autofill do navegador, que não dispara `input`. Não anuncia de novo:
-  // se o erro já está visível, `role="alert"` já o comunicou.
-  const value = dom.pathInput.value.trim();
-  if (!value || looksLikePath(value) || !dom.pathError.hidden) return;
-  setPathError("O caminho deve começar com / ou ~");
-});
-
-dom.repoList.addEventListener("click", (event) => {
-  const element = event.target.closest("[data-action]");
-  if (!element) return;
-  event.stopPropagation();
-  handleAction(element.dataset.action, element);
-});
-
-document.addEventListener("click", (event) => {
-  const viewButton = event.target.closest("[data-view]");
-  if (viewButton) {
-    setView(viewButton.dataset.view);
-    return;
-  }
-  const actionButton = event.target.closest("[data-action]");
-  if (actionButton && !dom.repoList.contains(actionButton)) handleAction(actionButton.dataset.action, actionButton);
-});
-
-window.addEventListener("resize", syncSidebarAccessibility);
-window.addEventListener("hashchange", applyHashState);
+/* B5: todos os listeners nascem em registerEvents(), não espalhados no topo
+   do módulo. Antes metade era registrada fora de init() — inicialização
+   partida em dois lugares. */
+let searchTimer = null;
 
-document.querySelector(".skip-link")?.addEventListener("click", (event) => {
-  event.preventDefault();
-  const viewport = dom.main.querySelector("[data-slot=scroll-view-viewport]");
-  viewport?.scrollTo({ top: 0 });
-  dom.main.focus({ preventScroll: true });
-});
-window.addEventListener("beforeunload", (event) => {
-  const dirty = Array.from(dom.repoList.querySelectorAll("[data-url-input]")).some(
-    (input) => String(input.value || "").trim() !== ""
-  );
-  if (dirty) {
+function registerEvents() {
+  $("form-path").addEventListener("submit", (event) => {
     event.preventDefault();
-    event.returnValue = "";
-  }
-});
+    doScan();
+  });
 
-document.addEventListener("keydown", (event) => {
-  if (event.key === "Escape") {
-    if (state.confirmRollback || state.confirmUpdate) {
-      state.confirmRollback = null;
-      state.confirmUpdate = null;
+  dom.search.addEventListener("input", (event) => {
+    state.query = event.target.value;
+    window.clearTimeout(searchTimer);
+    searchTimer = window.setTimeout(() => {
+      storeSet("alldown.query", state.query);
       render();
-      say("Ação cancelada.", "info");
+      writeHashState();
+    }, 150);
+  });
+
+  dom.filters.addEventListener("click", (event) => {
+    const button = event.target.closest("[data-filter]");
+    if (button) setFilter(button.dataset.filter);
+  });
+
+  dom.filters.addEventListener("keydown", (event) => {
+    const keys = ["ArrowLeft", "ArrowRight", "Home", "End"];
+    if (!keys.includes(event.key)) return;
+    const buttons = Array.from(dom.filters.querySelectorAll("[data-filter]"));
+    const current = buttons.indexOf(document.activeElement);
+    if (current === -1) return;
+    event.preventDefault();
+    let next;
+    if (event.key === "Home") next = 0;
+    else if (event.key === "End") next = buttons.length - 1;
+    else next = (current + (event.key === "ArrowRight" ? 1 : -1) + buttons.length) % buttons.length;
+    buttons[next].focus();
+    setFilter(buttons[next].dataset.filter);
+  });
+
+  dom.btnCheck.addEventListener("click", () => doCheck());
+  dom.btnAll.addEventListener("click", updateAll);
+
+  dom.btnAuto.addEventListener("click", () => {
+    state.auto = !state.auto;
+    storeSet("alldown.auto", state.auto ? "1" : "0");
+    paintSwitches();
+    say(state.auto ? "Detecção automática ativada." : "Detecção automática pausada.", "info", true);
+    const value = dom.pathInput.value.trim();
+    if (state.auto && looksLikePath(value) && value !== state.base) doScan();
+  });
+
+  dom.btnMode.addEventListener("click", () => {
+    const next = !state.zipOnly;
+    postFlag("/api/mode", { zip_only: next }, (result) => {
+      state.zipOnly = Boolean(result.zip_only);
+      say(state.zipOnly ? "Modo somente ZIP ativado." : "Modo pasta ativado.", "success", true);
+    });
+  });
+
+  dom.btnBackup.addEventListener("click", () => {
+    const next = !state.backup;
+    postFlag("/api/backup", { backup: next }, (result) => {
+      state.backup = Boolean(result.backup);
+      say(state.backup ? "Backup ativado." : "Backup desligado.", "success", true);
+    });
+  });
+
+  // Preferência só do cliente: não vai ao servidor (WCAG 2.1.4 exige forma de
+  // desativar atalho de tecla única).
+  dom.btnShortcuts.addEventListener("click", () => {
+    state.shortcuts = !state.shortcuts;
+    storeSet("alldown.shortcuts", state.shortcuts ? "1" : "0");
+    paintSwitches();
+    say(
+      state.shortcuts
+        ? "Atalhos de teclado ligados: E escaneia, C checa."
+        : "Atalhos de teclado desligados.",
+      "info",
+      true
+    );
+  });
+
+  dom.pathInput.addEventListener("input", () => {
+    const valid = validatePathInput();
+    const value = dom.pathInput.value.trim();
+    if (!valid) {
+      say("Caminho inválido: deve começar com / ou ~", "warning", true);
+      return;
     }
-    closeSidebar();
-    return;
-  }
-  if (event.metaKey || event.ctrlKey || event.altKey) return;
-  if (event.shiftKey) return;
-  if (!state.shortcuts) return;
-  if (event.repeat) return; // segurar a tecla nao deve repetir a operacao
-  const tag = event.target?.tagName || "";
-  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return;
-  if (event.target?.isContentEditable) return;
-  const key = event.key.toLowerCase();
-  if (key === "e") {
+    if (!state.auto || !looksLikePath(value)) return;
+    if (value === state.base && !state.lastScanFailed) return;
+    window.clearTimeout(state.pathTimer);
+    state.pathTimer = window.setTimeout(doScan, 700);
+  });
+
+  dom.pathInput.addEventListener("blur", () => {
+    // Só cobre autofill do navegador, que não dispara `input`. Não anuncia de novo:
+    // se o erro já está visível, `role="alert"` já o comunicou.
+    const value = dom.pathInput.value.trim();
+    if (!value || looksLikePath(value) || !dom.pathError.hidden) return;
+    setPathError("O caminho deve começar com / ou ~");
+  });
+
+  // B8/B9: um único despachante de clique. Antes havia stopPropagation no
+  // repoList + contains() no global — redundância que mascarava bugs — e o
+  // listener global fazia 2× closest() em todo clique da página. Agora: guarda
+  // barata por alvo, um closest() para view/action/filter-link.
+  document.addEventListener("click", (event) => {
+    if (!(event.target instanceof Element)) return;
+    const target = event.target.closest("[data-view],[data-action],[data-filter-link]");
+    if (!target) return;
+    if (target.dataset.view) {
+      setView(target.dataset.view);
+      return;
+    }
+    if (target.dataset.filterLink) {
+      setFilter(target.dataset.filterLink);
+      return;
+    }
+    if (target.dataset.action) handleAction(target.dataset.action, target);
+  });
+
+  // Enter no formulário de mapeamento salva (antes só o clique em Salvar).
+  // O submit é delegado: as linhas são recriadas a cada render.
+  dom.repoList.addEventListener("submit", (event) => {
+    const form = event.target.closest?.("[data-map-form]");
+    if (!form || !dom.repoList.contains(form)) return;
     event.preventDefault();
-    doScan();
-  }
-  if (key === "c") {
+    saveMapFrom(Number(form.dataset.mapForm));
+  });
+
+  window.addEventListener("resize", syncSidebarAccessibility);
+  window.addEventListener("hashchange", applyHashState);
+
+  document.querySelector(".skip-link")?.addEventListener("click", (event) => {
     event.preventDefault();
-    doCheck();
-  }
-});
+    const viewport = dom.main.querySelector("[data-slot=scroll-view-viewport]");
+    viewport?.scrollTo({ top: 0 });
+    dom.main.focus({ preventScroll: true });
+  });
+  window.addEventListener("beforeunload", (event) => {
+    const dirty = Array.from(dom.repoList.querySelectorAll("[data-url-input]")).some(
+      (input) => String(input.value || "").trim() !== ""
+    );
+    if (dirty) {
+      event.preventDefault();
+      event.returnValue = "";
+    }
+  });
+
+  document.addEventListener("keydown", (event) => {
+    if (event.key === "Escape") {
+      if (state.confirmRollback || state.confirmUpdate) {
+        state.confirmRollback = null;
+        state.confirmUpdate = null;
+        render();
+        say("Ação cancelada.", "info");
+      }
+      closeSidebar();
+      return;
+    }
+    if (event.metaKey || event.ctrlKey || event.altKey) return;
+    if (event.shiftKey) return;
+    if (!state.shortcuts) return;
+    if (event.repeat) return; // segurar a tecla nao deve repetir a operacao
+    const tag = event.target?.tagName || "";
+    if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return;
+    if (event.target?.isContentEditable) return;
+    const key = event.key.toLowerCase();
+    if (key === "e") {
+      event.preventDefault();
+      doScan();
+    }
+    if (key === "c") {
+      event.preventDefault();
+      doCheck();
+    }
+  });
+}
 
 init();
diff --git a/static/components-optional.css b/static/components-optional.css
new file mode 100644
index 0000000..3ab7f70
--- /dev/null
+++ b/static/components-optional.css
@@ -0,0 +1,383 @@
+/* ==========================================================================
+   RepoRefresh — COMPONENTES OPCIONAIS (fora do caminho crítico)
+   Primitives não usados pela Biblioteca/Atividade/Preferências: textarea,
+   select, checkbox, tooltip, drawer, dialog, menu (~7KB gzip).
+   Para usar, adicione <link rel="stylesheet" href="/static/components-optional.css?v=3">
+   depois de components.css. Mantido para a biblioteca completa do STYLEGUIDE.
+   ========================================================================== */
+
+/* --------------------------------------------------------------------------
+   2.3 Textarea
+   -------------------------------------------------------------------------- */
+[data-component="textarea-v2"] {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  width: 280px;
+  max-width: 100%;
+  min-height: 80px;
+  border: 0;
+  padding: 0 2px 2px 0;
+  border-radius: var(--v2-radius-input);
+  outline: 1px solid transparent;
+  outline-offset: 0;
+  background: linear-gradient(180deg, var(--v2-alpha-light-2) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
+  box-shadow: var(--v2-elevation-button-neutral);
+  align-self: stretch;
+  transition: background var(--v2-motion-control), outline-color var(--v2-motion-control), box-shadow var(--v2-motion-control);
+}
+
+[data-component="textarea-v2"]:where(:hover):not([data-disabled], [data-invalid]):not(:focus-within) {
+  background: linear-gradient(0deg, var(--v2-overlay-simple-overlay-hover), var(--v2-overlay-simple-overlay-hover)), linear-gradient(180deg, var(--v2-alpha-light-2) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
+}
+
+[data-component="textarea-v2"]:where(:focus-within):not([data-disabled], [data-invalid]) { outline-color: var(--v2-border-border-focus); box-shadow: none; }
+[data-component="textarea-v2"]:where([data-invalid]):not([data-disabled]) { outline-color: var(--v2-state-fg-danger); box-shadow: none; }
+[data-component="textarea-v2"]:where([data-disabled]) { opacity: 0.5; cursor: not-allowed; }
+
+[data-component="textarea-v2"] [data-slot="textarea-v2-textarea"] {
+  display: block;
+  width: 100%;
+  min-width: 0;
+  min-height: 80px;
+  height: 100%;
+  padding: 8px;
+  margin: 0;
+  border: 0;
+  background: transparent;
+  outline: none;
+  resize: vertical;
+  font-family: inherit;
+  font-style: normal;
+  font-weight: var(--v2-weight-regular);
+  font-size: var(--v2-text-control-size);
+  line-height: 1.35;
+  letter-spacing: var(--v2-text-control-tracking);
+  color: var(--v2-text-text-base);
+}
+
+[data-component="textarea-v2"] [data-slot="textarea-v2-textarea"]::placeholder { color: var(--v2-text-text-faint); }
+
+/* --------------------------------------------------------------------------
+   2.3 Select
+   -------------------------------------------------------------------------- */
+[data-component="select-v2"] {
+  position: relative;
+  display: flex;
+  flex-direction: row;
+  align-items: stretch;
+  gap: 8px;
+  width: 280px;
+  max-width: 100%;
+  height: 28px;
+  border: 0;
+  padding-block: 0;
+  padding-inline: 0 6px;
+  border-radius: var(--v2-radius-input);
+  outline: 1px solid transparent;
+  outline-offset: 0;
+  background: linear-gradient(180deg, var(--v2-alpha-light-2) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
+  box-shadow: var(--v2-elevation-button-neutral);
+  align-self: stretch;
+  -webkit-user-select: none;
+  user-select: none;
+  transition: background var(--v2-motion-control), outline-color var(--v2-motion-control), box-shadow var(--v2-motion-control);
+}
+
+[data-component="select-v2"][data-width="full"] { width: 100%; }
+[data-component="select-v2"]:where(:hover):not([data-disabled]):not(:focus-within) {
+  background: linear-gradient(0deg, var(--v2-overlay-simple-overlay-hover), var(--v2-overlay-simple-overlay-hover)), linear-gradient(180deg, var(--v2-alpha-light-2) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
+}
+[data-component="select-v2"]:where(:focus-within):not([data-disabled]) { outline-color: var(--v2-border-border-focus); box-shadow: none; }
+[data-component="select-v2"]:where([data-disabled]) { opacity: 0.5; cursor: not-allowed; }
+
+[data-component="select-v2"] select {
+  display: block;
+  width: 100%;
+  min-width: 0;
+  height: 100%;
+  padding: 0 24px 0 8px;
+  margin: 0;
+  border: 0;
+  background: transparent;
+  outline: none;
+  -webkit-appearance: none;
+  appearance: none;
+  font-family: inherit;
+  font-weight: var(--v2-weight-regular);
+  font-size: var(--v2-text-control-size);
+  line-height: var(--v2-text-control-line);
+  letter-spacing: var(--v2-text-control-tracking);
+  color: var(--v2-text-text-base);
+  cursor: default;
+}
+
+[data-component="select-v2"] [data-slot="select-v2-chevron"] {
+  position: absolute;
+  right: 5px;
+  top: 50%;
+  transform: translateY(-50%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  color: var(--v2-icon-icon-muted);
+  pointer-events: none;
+}
+
+[data-component="select-v2"] [data-slot="select-v2-chevron"] .icon { transform: rotate(180deg); transform-origin: 50% 50%; }
+
+/* --------------------------------------------------------------------------
+   2.4 Checkbox
+   -------------------------------------------------------------------------- */
+[data-component="checkbox-v2"] { display: flex; flex-direction: column; gap: 6px; cursor: default; }
+[data-component="checkbox-v2"]:where([data-disabled]) { cursor: not-allowed; }
+[data-component="checkbox-v2"] [data-slot="checkbox-v2-row"] { position: relative; display: flex; flex-direction: row; align-items: flex-start; gap: 8px; }
+
+[data-component="checkbox-v2"] [data-slot="checkbox-v2-input"] {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+[data-component="checkbox-v2"] [data-slot="checkbox-v2-control"] {
+  box-sizing: border-box;
+  position: relative;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  margin-top: 2px;
+  border: 0;
+  border-radius: var(--v2-radius-control);
+  box-shadow: inset 0 0 0 0.5px var(--v2-border-border-strong);
+  background: linear-gradient(180deg, var(--v2-alpha-light-6) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
+  transition: background var(--v2-motion-check), opacity var(--v2-motion-check), outline-color var(--v2-motion-check);
+}
+
+[data-component="checkbox-v2"] [data-slot="checkbox-v2-indicator"] { position: absolute; inset: 0; display: block; color: var(--v2-text-text-contrast); pointer-events: none; }
+[data-component="checkbox-v2"] [data-slot="checkbox-v2-indicator"] .icon { display: none; }
+[data-component="checkbox-v2"]:where([data-checked]) [data-slot="checkbox-v2-indicator"] .icon { display: block; }
+
+[data-component="checkbox-v2"] [data-slot="checkbox-v2-label"] { display: inline-flex; -webkit-user-select: none; user-select: none; }
+[data-component="checkbox-v2"] [data-slot="checkbox-v2-label-text"] {
+  display: inline-flex;
+  align-items: center;
+  color: var(--v2-text-text-base);
+  font-size: var(--v2-text-label-size);
+  font-weight: var(--v2-weight-regular);
+  line-height: var(--v2-text-label-line);
+  letter-spacing: var(--v2-text-label-tracking);
+}
+[data-component="checkbox-v2"] [data-slot="checkbox-v2-description"] {
+  display: block;
+  color: var(--v2-text-text-muted);
+  font-size: var(--v2-text-micro-size);
+  font-weight: var(--v2-weight-regular);
+  line-height: 1;
+  letter-spacing: var(--v2-text-micro-tracking);
+}
+
+[data-component="checkbox-v2"]:where(:not([data-readonly])) [data-slot="checkbox-v2-input"]:focus-visible ~ [data-slot="checkbox-v2-control"] {
+  outline: 2px solid var(--v2-border-border-focus);
+  outline-offset: 1px;
+}
+
+[data-component="checkbox-v2"]:where(:hover):where(:not([data-disabled], [data-readonly], [data-invalid])):where(:not([data-checked])) [data-slot="checkbox-v2-control"] {
+  background: linear-gradient(0deg, var(--v2-overlay-simple-overlay-hover), var(--v2-overlay-simple-overlay-hover)), linear-gradient(180deg, var(--v2-alpha-light-6) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
+}
+
+[data-component="checkbox-v2"]:where([data-checked]) [data-slot="checkbox-v2-control"] {
+  background: linear-gradient(180deg, var(--v2-alpha-light-20) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-accent);
+}
+
+[data-component="checkbox-v2"]:where([data-checked]):where(:hover):where(:not([data-disabled], [data-readonly])) [data-slot="checkbox-v2-control"] {
+  background: linear-gradient(0deg, var(--v2-overlay-simple-overlay-contrast-hover), var(--v2-overlay-simple-overlay-contrast-hover)), linear-gradient(180deg, var(--v2-alpha-light-20) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-accent);
+}
+
+[data-component="checkbox-v2"]:where([data-invalid]):where(:not([data-checked])) [data-slot="checkbox-v2-control"] {
+  background: var(--v2-state-bg-danger);
+  box-shadow: inset 0 0 0 0.5px var(--v2-state-border-danger);
+}
+
+[data-component="checkbox-v2"]:where([data-disabled]) [data-slot="checkbox-v2-control"] { opacity: 0.5; }
+[data-component="checkbox-v2"]:where([data-disabled]) [data-slot="checkbox-v2-label"],
+[data-component="checkbox-v2"]:where([data-disabled]) [data-slot="checkbox-v2-description"] { opacity: 0.5; }
+
+/* --------------------------------------------------------------------------
+   2.8 Tooltip
+   -------------------------------------------------------------------------- */
+[data-component="tooltip-v2"] {
+  z-index: 1000;
+  box-sizing: border-box;
+  display: inline-flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 6px;
+  max-width: 280px;
+  padding: 5px 6px;
+  border-radius: var(--v2-radius-control);
+  background: var(--v2-background-bg-layer-01);
+  box-shadow: var(--v2-elevation-floating);
+  font-style: normal;
+  font-weight: var(--v2-weight-medium);
+  font-size: var(--v2-text-micro-size);
+  line-height: 12px;
+  letter-spacing: var(--v2-text-micro-tracking);
+  font-variant-numeric: tabular-nums;
+  color: var(--v2-text-text-base);
+  -webkit-user-select: none;
+  user-select: none;
+  pointer-events: none;
+  animation: v2-tooltip-in var(--v2-motion-tooltip);
+}
+
+[data-component="tooltip-v2"][data-closed] { animation: v2-tooltip-out 80ms ease-in forwards; }
+
+@keyframes v2-tooltip-in { from { opacity: 0; transform: translateY(2px); } to { opacity: 1; transform: translateY(0); } }
+@keyframes v2-tooltip-out { from { opacity: 1; } to { opacity: 0; } }
+
+/* --------------------------------------------------------------------------
+   2.9 Drawer
+   -------------------------------------------------------------------------- */
+[data-component="drawer-overlay"] {
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  background-color: var(--v2-overlay-simple-overlay-scrim);
+  animation: v2-fade-in var(--v2-motion-overlay);
+}
+
+[data-component="drawer-overlay"][data-closed] { animation: v2-fade-out var(--v2-motion-drawer-out) forwards; }
+
+[data-component="drawer"] { position: fixed; inset: 0; z-index: 50; display: flex; justify-content: flex-end; pointer-events: none; }
+
+[data-component="drawer"] [data-slot="drawer-panel"] {
+  display: flex;
+  flex-direction: column;
+  width: min(100vw, 40rem);
+  height: 100%;
+  background: var(--v2-background-bg-layer-01);
+  box-shadow: var(--v2-elevation-overlay);
+  pointer-events: auto;
+  outline: none;
+  animation: v2-drawer-in var(--v2-motion-drawer-in);
+}
+
+[data-component="drawer"] [data-slot="drawer-panel"][data-closed] { animation: v2-drawer-out var(--v2-motion-drawer-out) forwards; }
+
+@keyframes v2-drawer-in { from { transform: translateX(16px); opacity: 0; } to { transform: translateX(0); opacity: 1; } }
+@keyframes v2-drawer-out { from { transform: translateX(0); opacity: 1; } to { transform: translateX(16px); opacity: 0; } }
+@keyframes v2-fade-in { from { opacity: 0; } to { opacity: 1; } }
+@keyframes v2-fade-out { from { opacity: 1; } to { opacity: 0; } }
+
+/* --------------------------------------------------------------------------
+   2.10 Dialog
+   -------------------------------------------------------------------------- */
+[data-component="dialog-overlay"] { position: fixed; inset: 0; z-index: 50; background-color: var(--v2-overlay-simple-overlay-scrim); animation: v2-fade-in var(--v2-motion-overlay); }
+
+[data-component="dialog-v2"] { position: fixed; inset: 0; z-index: 50; display: flex; align-items: center; justify-content: center; padding: 16px; pointer-events: none; }
+
+[data-component="dialog-v2"] [data-slot="dialog-container"] {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  width: 480px;
+  max-width: calc(100vw - 32px);
+  max-height: calc(100dvh - 32px);
+  border-radius: var(--v2-radius-overlay);
+  background: var(--v2-background-bg-base);
+  box-shadow: var(--v2-elevation-overlay);
+  overflow: hidden;
+  pointer-events: auto;
+  animation: v2-dialog-in var(--v2-motion-overlay);
+}
+
+[data-component="dialog-v2"][data-size="large"] [data-slot="dialog-container"] { width: 640px; }
+
+[data-component="dialog-v2"] [data-slot="dialog-content"] { display: flex; flex-direction: column; overflow: auto; scrollbar-width: none; }
+[data-component="dialog-v2"] [data-slot="dialog-content"]::-webkit-scrollbar { display: none; }
+
+[data-component="dialog-v2"] [data-slot="dialog-header"] { display: flex; flex-direction: column; align-items: flex-start; gap: 4px; padding: 24px 24px 0; flex-shrink: 0; }
+[data-component="dialog-v2"] [data-slot="dialog-title"] {
+  margin: 0;
+  color: var(--v2-text-text-base);
+  font-weight: var(--v2-weight-medium);
+  font-size: var(--v2-text-title-size);
+  line-height: var(--v2-text-title-line);
+  letter-spacing: var(--v2-text-title-tracking);
+}
+[data-component="dialog-v2"] [data-slot="dialog-description"] {
+  margin: 0;
+  color: var(--v2-text-text-muted);
+  font-weight: var(--v2-weight-regular);
+  font-size: var(--v2-text-body-size);
+  line-height: var(--v2-text-body-line);
+  letter-spacing: var(--v2-text-body-tracking);
+}
+[data-component="dialog-v2"] [data-slot="dialog-body"] { padding: 16px 24px; }
+[data-component="dialog-v2"] [data-slot="dialog-footer"] { display: flex; flex-direction: row; justify-content: flex-end; align-items: center; gap: 8px; padding: 16px 24px 24px; flex-shrink: 0; }
+
+@keyframes v2-dialog-in { from { opacity: 0; transform: scale(0.98); } to { opacity: 1; transform: scale(1); } }
+
+/* --------------------------------------------------------------------------
+   2.7 Menu
+   -------------------------------------------------------------------------- */
+[data-component="menu-v2-content"] {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  min-width: 160px;
+  padding: 2px;
+  z-index: 60;
+  pointer-events: auto;
+  border-radius: var(--v2-radius-input);
+  background: var(--v2-background-bg-layer-01);
+  box-shadow: var(--v2-elevation-floating);
+  outline: none;
+  animation: v2-menu-in var(--v2-motion-tooltip);
+}
+
+@keyframes v2-menu-in { from { opacity: 0; transform: scale(0.98); } to { opacity: 1; transform: scale(1); } }
+
+[data-component="menu-v2-item"] {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 8px;
+  height: 28px;
+  padding: 0 12px;
+  border: 0;
+  border-radius: var(--v2-radius-control);
+  background: transparent;
+  font-family: inherit;
+  outline: none;
+  color: var(--v2-text-text-base);
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+[data-component="menu-v2-item"] [data-slot="menu-v2-item-content"] {
+  display: flex;
+  flex: 1 1 auto;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+  font-size: var(--v2-text-label-size);
+  font-weight: var(--v2-weight-regular);
+  line-height: 100%;
+  letter-spacing: var(--v2-text-label-tracking);
+}
+[data-component="menu-v2-item"] [data-slot="menu-v2-item-shortcut"] { flex: none; color: var(--v2-text-text-faint); font-size: var(--v2-text-micro-size); font-weight: var(--v2-weight-medium); line-height: 100%; letter-spacing: var(--v2-text-micro-tracking); }
+[data-component="menu-v2-item"]:is(:hover, [data-highlighted]) { background: var(--v2-overlay-simple-overlay-hover); }
+[data-component="menu-v2-item"][data-checked] [data-slot="menu-v2-item-content"] { font-weight: var(--v2-weight-medium); color: var(--v2-text-text-accent); }
+[data-component="menu-v2-item"][data-disabled] { pointer-events: none; opacity: 0.5; }
+
diff --git a/static/components.css b/static/components.css
index 6c88ab7..b799c1a 100644
--- a/static/components.css
+++ b/static/components.css
@@ -412,210 +412,6 @@ body {
 
 [data-component="text-input-v2"][data-numeric] [data-slot="text-input-v2-input"] { font-variant-numeric: tabular-nums; }
 
-/* --------------------------------------------------------------------------
-   2.3 Textarea
-   -------------------------------------------------------------------------- */
-[data-component="textarea-v2"] {
-  display: flex;
-  flex-direction: column;
-  align-items: stretch;
-  width: 280px;
-  max-width: 100%;
-  min-height: 80px;
-  border: 0;
-  padding: 0 2px 2px 0;
-  border-radius: var(--v2-radius-input);
-  outline: 1px solid transparent;
-  outline-offset: 0;
-  background: linear-gradient(180deg, var(--v2-alpha-light-2) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
-  box-shadow: var(--v2-elevation-button-neutral);
-  align-self: stretch;
-  transition: background var(--v2-motion-control), outline-color var(--v2-motion-control), box-shadow var(--v2-motion-control);
-}
-
-[data-component="textarea-v2"]:where(:hover):not([data-disabled], [data-invalid]):not(:focus-within) {
-  background: linear-gradient(0deg, var(--v2-overlay-simple-overlay-hover), var(--v2-overlay-simple-overlay-hover)), linear-gradient(180deg, var(--v2-alpha-light-2) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
-}
-
-[data-component="textarea-v2"]:where(:focus-within):not([data-disabled], [data-invalid]) { outline-color: var(--v2-border-border-focus); box-shadow: none; }
-[data-component="textarea-v2"]:where([data-invalid]):not([data-disabled]) { outline-color: var(--v2-state-fg-danger); box-shadow: none; }
-[data-component="textarea-v2"]:where([data-disabled]) { opacity: 0.5; cursor: not-allowed; }
-
-[data-component="textarea-v2"] [data-slot="textarea-v2-textarea"] {
-  display: block;
-  width: 100%;
-  min-width: 0;
-  min-height: 80px;
-  height: 100%;
-  padding: 8px;
-  margin: 0;
-  border: 0;
-  background: transparent;
-  outline: none;
-  resize: vertical;
-  font-family: inherit;
-  font-style: normal;
-  font-weight: var(--v2-weight-regular);
-  font-size: var(--v2-text-control-size);
-  line-height: 1.35;
-  letter-spacing: var(--v2-text-control-tracking);
-  color: var(--v2-text-text-base);
-}
-
-[data-component="textarea-v2"] [data-slot="textarea-v2-textarea"]::placeholder { color: var(--v2-text-text-faint); }
-
-/* --------------------------------------------------------------------------
-   2.3 Select
-   -------------------------------------------------------------------------- */
-[data-component="select-v2"] {
-  position: relative;
-  display: flex;
-  flex-direction: row;
-  align-items: stretch;
-  gap: 8px;
-  width: 280px;
-  max-width: 100%;
-  height: 28px;
-  border: 0;
-  padding-block: 0;
-  padding-inline: 0 6px;
-  border-radius: var(--v2-radius-input);
-  outline: 1px solid transparent;
-  outline-offset: 0;
-  background: linear-gradient(180deg, var(--v2-alpha-light-2) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
-  box-shadow: var(--v2-elevation-button-neutral);
-  align-self: stretch;
-  -webkit-user-select: none;
-  user-select: none;
-  transition: background var(--v2-motion-control), outline-color var(--v2-motion-control), box-shadow var(--v2-motion-control);
-}
-
-[data-component="select-v2"][data-width="full"] { width: 100%; }
-[data-component="select-v2"]:where(:hover):not([data-disabled]):not(:focus-within) {
-  background: linear-gradient(0deg, var(--v2-overlay-simple-overlay-hover), var(--v2-overlay-simple-overlay-hover)), linear-gradient(180deg, var(--v2-alpha-light-2) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
-}
-[data-component="select-v2"]:where(:focus-within):not([data-disabled]) { outline-color: var(--v2-border-border-focus); box-shadow: none; }
-[data-component="select-v2"]:where([data-disabled]) { opacity: 0.5; cursor: not-allowed; }
-
-[data-component="select-v2"] select {
-  display: block;
-  width: 100%;
-  min-width: 0;
-  height: 100%;
-  padding: 0 24px 0 8px;
-  margin: 0;
-  border: 0;
-  background: transparent;
-  outline: none;
-  -webkit-appearance: none;
-  appearance: none;
-  font-family: inherit;
-  font-weight: var(--v2-weight-regular);
-  font-size: var(--v2-text-control-size);
-  line-height: var(--v2-text-control-line);
-  letter-spacing: var(--v2-text-control-tracking);
-  color: var(--v2-text-text-base);
-  cursor: default;
-}
-
-[data-component="select-v2"] [data-slot="select-v2-chevron"] {
-  position: absolute;
-  right: 5px;
-  top: 50%;
-  transform: translateY(-50%);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 20px;
-  height: 20px;
-  color: var(--v2-icon-icon-muted);
-  pointer-events: none;
-}
-
-[data-component="select-v2"] [data-slot="select-v2-chevron"] .icon { transform: rotate(180deg); transform-origin: 50% 50%; }
-
-/* --------------------------------------------------------------------------
-   2.4 Checkbox
-   -------------------------------------------------------------------------- */
-[data-component="checkbox-v2"] { display: flex; flex-direction: column; gap: 6px; cursor: default; }
-[data-component="checkbox-v2"]:where([data-disabled]) { cursor: not-allowed; }
-[data-component="checkbox-v2"] [data-slot="checkbox-v2-row"] { position: relative; display: flex; flex-direction: row; align-items: flex-start; gap: 8px; }
-
-[data-component="checkbox-v2"] [data-slot="checkbox-v2-input"] {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  padding: 0;
-  margin: -1px;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border-width: 0;
-}
-
-[data-component="checkbox-v2"] [data-slot="checkbox-v2-control"] {
-  box-sizing: border-box;
-  position: relative;
-  flex: none;
-  width: 16px;
-  height: 16px;
-  margin-top: 2px;
-  border: 0;
-  border-radius: var(--v2-radius-control);
-  box-shadow: inset 0 0 0 0.5px var(--v2-border-border-strong);
-  background: linear-gradient(180deg, var(--v2-alpha-light-6) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
-  transition: background var(--v2-motion-check), opacity var(--v2-motion-check), outline-color var(--v2-motion-check);
-}
-
-[data-component="checkbox-v2"] [data-slot="checkbox-v2-indicator"] { position: absolute; inset: 0; display: block; color: var(--v2-text-text-contrast); pointer-events: none; }
-[data-component="checkbox-v2"] [data-slot="checkbox-v2-indicator"] .icon { display: none; }
-[data-component="checkbox-v2"]:where([data-checked]) [data-slot="checkbox-v2-indicator"] .icon { display: block; }
-
-[data-component="checkbox-v2"] [data-slot="checkbox-v2-label"] { display: inline-flex; -webkit-user-select: none; user-select: none; }
-[data-component="checkbox-v2"] [data-slot="checkbox-v2-label-text"] {
-  display: inline-flex;
-  align-items: center;
-  color: var(--v2-text-text-base);
-  font-size: var(--v2-text-label-size);
-  font-weight: var(--v2-weight-regular);
-  line-height: var(--v2-text-label-line);
-  letter-spacing: var(--v2-text-label-tracking);
-}
-[data-component="checkbox-v2"] [data-slot="checkbox-v2-description"] {
-  display: block;
-  color: var(--v2-text-text-muted);
-  font-size: var(--v2-text-micro-size);
-  font-weight: var(--v2-weight-regular);
-  line-height: 1;
-  letter-spacing: var(--v2-text-micro-tracking);
-}
-
-[data-component="checkbox-v2"]:where(:not([data-readonly])) [data-slot="checkbox-v2-input"]:focus-visible ~ [data-slot="checkbox-v2-control"] {
-  outline: 2px solid var(--v2-border-border-focus);
-  outline-offset: 1px;
-}
-
-[data-component="checkbox-v2"]:where(:hover):where(:not([data-disabled], [data-readonly], [data-invalid])):where(:not([data-checked])) [data-slot="checkbox-v2-control"] {
-  background: linear-gradient(0deg, var(--v2-overlay-simple-overlay-hover), var(--v2-overlay-simple-overlay-hover)), linear-gradient(180deg, var(--v2-alpha-light-6) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-base);
-}
-
-[data-component="checkbox-v2"]:where([data-checked]) [data-slot="checkbox-v2-control"] {
-  background: linear-gradient(180deg, var(--v2-alpha-light-20) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-accent);
-}
-
-[data-component="checkbox-v2"]:where([data-checked]):where(:hover):where(:not([data-disabled], [data-readonly])) [data-slot="checkbox-v2-control"] {
-  background: linear-gradient(0deg, var(--v2-overlay-simple-overlay-contrast-hover), var(--v2-overlay-simple-overlay-contrast-hover)), linear-gradient(180deg, var(--v2-alpha-light-20) 0%, var(--v2-alpha-light-0) 100%), var(--v2-background-bg-accent);
-}
-
-[data-component="checkbox-v2"]:where([data-invalid]):where(:not([data-checked])) [data-slot="checkbox-v2-control"] {
-  background: var(--v2-state-bg-danger);
-  box-shadow: inset 0 0 0 0.5px var(--v2-state-border-danger);
-}
-
-[data-component="checkbox-v2"]:where([data-disabled]) [data-slot="checkbox-v2-control"] { opacity: 0.5; }
-[data-component="checkbox-v2"]:where([data-disabled]) [data-slot="checkbox-v2-label"],
-[data-component="checkbox-v2"]:where([data-disabled]) [data-slot="checkbox-v2-description"] { opacity: 0.5; }
-
 /* --------------------------------------------------------------------------
    2.4 Switch
    -------------------------------------------------------------------------- */
@@ -774,39 +570,6 @@ body {
 [data-component="segmented-control-v2"] [data-slot="segmented-control-v2-item-text"] { overflow: hidden; min-width: 0; text-overflow: ellipsis; white-space: nowrap; }
 [data-component="segmented-control-v2"] [data-slot="segmented-control-v2-item-count"] { flex: none; color: var(--v2-text-text-faint); }
 
-/* --------------------------------------------------------------------------
-   2.8 Tooltip
-   -------------------------------------------------------------------------- */
-[data-component="tooltip-v2"] {
-  z-index: 1000;
-  box-sizing: border-box;
-  display: inline-flex;
-  flex-direction: row;
-  align-items: center;
-  gap: 6px;
-  max-width: 280px;
-  padding: 5px 6px;
-  border-radius: var(--v2-radius-control);
-  background: var(--v2-background-bg-layer-01);
-  box-shadow: var(--v2-elevation-floating);
-  font-style: normal;
-  font-weight: var(--v2-weight-medium);
-  font-size: var(--v2-text-micro-size);
-  line-height: 12px;
-  letter-spacing: var(--v2-text-micro-tracking);
-  font-variant-numeric: tabular-nums;
-  color: var(--v2-text-text-base);
-  -webkit-user-select: none;
-  user-select: none;
-  pointer-events: none;
-  animation: v2-tooltip-in var(--v2-motion-tooltip);
-}
-
-[data-component="tooltip-v2"][data-closed] { animation: v2-tooltip-out 80ms ease-in forwards; }
-
-@keyframes v2-tooltip-in { from { opacity: 0; transform: translateY(2px); } to { opacity: 1; transform: translateY(0); } }
-@keyframes v2-tooltip-out { from { opacity: 1; } to { opacity: 0; } }
-
 /* --------------------------------------------------------------------------
    2.15 Avatar
    -------------------------------------------------------------------------- */
@@ -989,144 +752,6 @@ body {
 @keyframes v2-toast-in { from { opacity: 0; transform: translateY(8px) scale(0.98); } to { opacity: 1; transform: translateY(0) scale(1); } }
 @keyframes v2-toast-out { from { opacity: 1; transform: translateY(0); } to { opacity: 0; transform: translateY(8px); } }
 
-/* --------------------------------------------------------------------------
-   2.9 Drawer
-   -------------------------------------------------------------------------- */
-[data-component="drawer-overlay"] {
-  position: fixed;
-  inset: 0;
-  z-index: 50;
-  background-color: var(--v2-overlay-simple-overlay-scrim);
-  animation: v2-fade-in var(--v2-motion-overlay);
-}
-
-[data-component="drawer-overlay"][data-closed] { animation: v2-fade-out var(--v2-motion-drawer-out) forwards; }
-
-[data-component="drawer"] { position: fixed; inset: 0; z-index: 50; display: flex; justify-content: flex-end; pointer-events: none; }
-
-[data-component="drawer"] [data-slot="drawer-panel"] {
-  display: flex;
-  flex-direction: column;
-  width: min(100vw, 40rem);
-  height: 100%;
-  background: var(--v2-background-bg-layer-01);
-  box-shadow: var(--v2-elevation-overlay);
-  pointer-events: auto;
-  outline: none;
-  animation: v2-drawer-in var(--v2-motion-drawer-in);
-}
-
-[data-component="drawer"] [data-slot="drawer-panel"][data-closed] { animation: v2-drawer-out var(--v2-motion-drawer-out) forwards; }
-
-@keyframes v2-drawer-in { from { transform: translateX(16px); opacity: 0; } to { transform: translateX(0); opacity: 1; } }
-@keyframes v2-drawer-out { from { transform: translateX(0); opacity: 1; } to { transform: translateX(16px); opacity: 0; } }
-@keyframes v2-fade-in { from { opacity: 0; } to { opacity: 1; } }
-@keyframes v2-fade-out { from { opacity: 1; } to { opacity: 0; } }
-
-/* --------------------------------------------------------------------------
-   2.10 Dialog
-   -------------------------------------------------------------------------- */
-[data-component="dialog-overlay"] { position: fixed; inset: 0; z-index: 50; background-color: var(--v2-overlay-simple-overlay-scrim); animation: v2-fade-in var(--v2-motion-overlay); }
-
-[data-component="dialog-v2"] { position: fixed; inset: 0; z-index: 50; display: flex; align-items: center; justify-content: center; padding: 16px; pointer-events: none; }
-
-[data-component="dialog-v2"] [data-slot="dialog-container"] {
-  display: flex;
-  flex-direction: column;
-  align-items: stretch;
-  width: 480px;
-  max-width: calc(100vw - 32px);
-  max-height: calc(100dvh - 32px);
-  border-radius: var(--v2-radius-overlay);
-  background: var(--v2-background-bg-base);
-  box-shadow: var(--v2-elevation-overlay);
-  overflow: hidden;
-  pointer-events: auto;
-  animation: v2-dialog-in var(--v2-motion-overlay);
-}
-
-[data-component="dialog-v2"][data-size="large"] [data-slot="dialog-container"] { width: 640px; }
-
-[data-component="dialog-v2"] [data-slot="dialog-content"] { display: flex; flex-direction: column; overflow: auto; scrollbar-width: none; }
-[data-component="dialog-v2"] [data-slot="dialog-content"]::-webkit-scrollbar { display: none; }
-
-[data-component="dialog-v2"] [data-slot="dialog-header"] { display: flex; flex-direction: column; align-items: flex-start; gap: 4px; padding: 24px 24px 0; flex-shrink: 0; }
-[data-component="dialog-v2"] [data-slot="dialog-title"] {
-  margin: 0;
-  color: var(--v2-text-text-base);
-  font-weight: var(--v2-weight-medium);
-  font-size: var(--v2-text-title-size);
-  line-height: var(--v2-text-title-line);
-  letter-spacing: var(--v2-text-title-tracking);
-}
-[data-component="dialog-v2"] [data-slot="dialog-description"] {
-  margin: 0;
-  color: var(--v2-text-text-muted);
-  font-weight: var(--v2-weight-regular);
-  font-size: var(--v2-text-body-size);
-  line-height: var(--v2-text-body-line);
-  letter-spacing: var(--v2-text-body-tracking);
-}
-[data-component="dialog-v2"] [data-slot="dialog-body"] { padding: 16px 24px; }
-[data-component="dialog-v2"] [data-slot="dialog-footer"] { display: flex; flex-direction: row; justify-content: flex-end; align-items: center; gap: 8px; padding: 16px 24px 24px; flex-shrink: 0; }
-
-@keyframes v2-dialog-in { from { opacity: 0; transform: scale(0.98); } to { opacity: 1; transform: scale(1); } }
-
-/* --------------------------------------------------------------------------
-   2.7 Menu
-   -------------------------------------------------------------------------- */
-[data-component="menu-v2-content"] {
-  box-sizing: border-box;
-  display: flex;
-  flex-direction: column;
-  align-items: stretch;
-  min-width: 160px;
-  padding: 2px;
-  z-index: 60;
-  pointer-events: auto;
-  border-radius: var(--v2-radius-input);
-  background: var(--v2-background-bg-layer-01);
-  box-shadow: var(--v2-elevation-floating);
-  outline: none;
-  animation: v2-menu-in var(--v2-motion-tooltip);
-}
-
-@keyframes v2-menu-in { from { opacity: 0; transform: scale(0.98); } to { opacity: 1; transform: scale(1); } }
-
-[data-component="menu-v2-item"] {
-  box-sizing: border-box;
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-  gap: 8px;
-  height: 28px;
-  padding: 0 12px;
-  border: 0;
-  border-radius: var(--v2-radius-control);
-  background: transparent;
-  font-family: inherit;
-  outline: none;
-  color: var(--v2-text-text-base);
-  -webkit-user-select: none;
-  user-select: none;
-}
-
-[data-component="menu-v2-item"] [data-slot="menu-v2-item-content"] {
-  display: flex;
-  flex: 1 1 auto;
-  align-items: center;
-  gap: 8px;
-  min-width: 0;
-  font-size: var(--v2-text-label-size);
-  font-weight: var(--v2-weight-regular);
-  line-height: 100%;
-  letter-spacing: var(--v2-text-label-tracking);
-}
-[data-component="menu-v2-item"] [data-slot="menu-v2-item-shortcut"] { flex: none; color: var(--v2-text-text-faint); font-size: var(--v2-text-micro-size); font-weight: var(--v2-weight-medium); line-height: 100%; letter-spacing: var(--v2-text-micro-tracking); }
-[data-component="menu-v2-item"]:is(:hover, [data-highlighted]) { background: var(--v2-overlay-simple-overlay-hover); }
-[data-component="menu-v2-item"][data-checked] [data-slot="menu-v2-item-content"] { font-weight: var(--v2-weight-medium); color: var(--v2-text-text-accent); }
-[data-component="menu-v2-item"][data-disabled] { pointer-events: none; opacity: 0.5; }
-
 /* --------------------------------------------------------------------------
    2.16 ScrollView — o console esconde a scrollbar nativa e desenha a dele
    -------------------------------------------------------------------------- */
@@ -1185,9 +810,13 @@ body {
 [data-component="data-table"] { width: 100%; border-collapse: collapse; border-spacing: 0; }
 
 [data-component="data-table"] thead th {
+  position: sticky;
+  top: 0;
+  z-index: 1;
   height: 32px;
   padding: 0 12px;
   border-bottom: 0.5px solid var(--v2-border-border-muted);
+  background: var(--v2-background-bg-layer-01);
   color: var(--v2-text-text-faint);
   font-size: var(--v2-text-micro-size);
   font-weight: var(--v2-weight-medium);
diff --git a/static/index.html b/static/index.html
index 759b001..158d368 100644
--- a/static/index.html
+++ b/static/index.html
@@ -13,10 +13,10 @@
 <link rel="preload" href="/static/fonts/inter-400.woff2" as="font" type="font/woff2" crossorigin>
 <link rel="preload" href="/static/fonts/inter-500.woff2" as="font" type="font/woff2" crossorigin>
 <link rel="preload" href="/static/fonts/inter-600.woff2" as="font" type="font/woff2" crossorigin>
-<link rel="stylesheet" href="/static/tokens.css?v=1" fetchpriority="high">
-<link rel="stylesheet" href="/static/components.css?v=1" fetchpriority="high">
-<link rel="stylesheet" href="/static/shell.css?v=1">
-<script src="/static/theme.js"></script>
+<link rel="stylesheet" href="/static/tokens.css?v=3" fetchpriority="high">
+<link rel="stylesheet" href="/static/components.css?v=3" fetchpriority="high">
+<link rel="stylesheet" href="/static/shell.css?v=3">
+<script src="/static/theme.js?v=3"></script>
 </head>
 <body>
 <svg class="icon-sprite" aria-hidden="true" focusable="false">
@@ -109,7 +109,7 @@
       <nav class="breadcrumbs" aria-label="Trilha de navegação">
         <span translate="no">RepoRefresh</span>
         <svg class="icon" data-size="xs" aria-hidden="true" focusable="false"><use href="#i-chevron"></use></svg>
-        <strong id="view-title">Biblioteca</strong>
+        <strong id="view-title" aria-current="page">Biblioteca</strong>
       </nav>
 
       <div class="topbar__actions">
@@ -152,9 +152,9 @@ <h1 class="page-header__title">Biblioteca</h1>
           </header>
 
           <section class="steps" aria-label="Etapas da operação">
-            <div class="step"><span class="step__index">01</span><span class="step__title">Localizar</span><span class="step__body">pastas e arquivos ZIP</span></div>
-            <div class="step"><span class="step__index">02</span><span class="step__title">Comparar</span><span class="step__body">SHA local com remoto</span></div>
-            <div class="step"><span class="step__index">03</span><span class="step__title">Trocar</span><span class="step__body">com backup e reversão</span></div>
+            <div class="step" id="step-locate"><span class="step__index">01</span><span class="step__title">Localizar</span><span class="step__body">pastas e arquivos ZIP</span></div>
+            <div class="step" id="step-compare"><span class="step__index">02</span><span class="step__title">Comparar</span><span class="step__body">SHA local com remoto</span></div>
+            <div class="step" id="step-swap"><span class="step__index">03</span><span class="step__title">Trocar</span><span class="step__body">com backup e reversão</span></div>
           </section>
 
           <section data-component="card" data-padding="large" aria-labelledby="path-title">
@@ -202,10 +202,10 @@ <h1 class="page-header__title">Biblioteca</h1>
           </div>
 
           <section class="summary-grid" aria-label="Resumo da operação">
-            <div class="stat-card"><span class="stat-card__label">Itens detectados</span><span class="stat-card__value" id="sum-total">0</span><span class="stat-card__hint">pastas + arquivos ZIP</span></div>
-            <div class="stat-card" data-tone="success"><span class="stat-card__label">Sincronizados</span><span class="stat-card__value" id="sum-ready">0</span><span class="stat-card__hint">commit local verificado</span></div>
-            <div class="stat-card" data-tone="warning"><span class="stat-card__label">Para atualizar</span><span class="stat-card__value" id="sum-behind">0</span><span class="stat-card__hint">commits disponíveis</span></div>
-            <div class="stat-card" data-tone="info"><span class="stat-card__label">Revisão ou erro</span><span class="stat-card__value" id="sum-attention">0</span><span class="stat-card__hint">sem vínculo ou erro</span></div>
+            <button type="button" class="stat-card" data-filter-link="all" aria-label="Ver todos os itens"><span class="stat-card__label">Itens detectados</span><span class="stat-card__value" id="sum-total">0</span><span class="stat-card__hint">pastas + arquivos ZIP</span></button>
+            <button type="button" class="stat-card" data-tone="success" data-filter-link="ready" aria-label="Ver sincronizados"><span class="stat-card__label">Sincronizados</span><span class="stat-card__value" id="sum-ready">0</span><span class="stat-card__hint">commit local verificado</span></button>
+            <button type="button" class="stat-card" data-tone="warning" data-filter-link="behind" aria-label="Ver pendentes de atualização"><span class="stat-card__label">Para atualizar</span><span class="stat-card__value" id="sum-behind">0</span><span class="stat-card__hint">commits disponíveis</span></button>
+            <button type="button" class="stat-card" data-tone="info" data-filter-link="unmapped" aria-label="Ver itens para revisão"><span class="stat-card__label">Revisão ou erro</span><span class="stat-card__value" id="sum-attention">0</span><span class="stat-card__hint">sem vínculo ou erro</span></button>
           </section>
 
           <section data-component="card" aria-labelledby="library-title">
@@ -361,6 +361,6 @@ <h1 class="page-header__title">Preferências</h1>
 
 <div data-component="toast-region-v2" id="toast-region" role="region" aria-label="Notificações"></div>
 
-<script src="/static/app.js?v=2" defer></script>
+<script src="/static/app.js?v=3" defer></script>
 </body>
 </html>
diff --git a/static/shell.css b/static/shell.css
index 3f9b417..be4c4e8 100644
--- a/static/shell.css
+++ b/static/shell.css
@@ -274,10 +274,13 @@
 
 .page-header__actions { display: flex; align-items: center; gap: 8px; margin-top: 4px; }
 
-/* Etapas da operação — 3 passos, densidade alta */
+/* Etapas da operação — 3 passos, densidade alta. data-done reflete o progresso
+   real (pintado por paintSteps()): Localizar acende com pasta, Comparar com
+   check concluído, Trocar quando nada está pendente. */
 .steps { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px; }
 .step { display: flex; flex-direction: column; gap: 2px; padding: 12px; border-radius: var(--v2-radius-surface); background: var(--v2-background-bg-layer-01); box-shadow: var(--v2-elevation-raised); }
 .step__index { color: var(--v2-text-text-faint); font-family: var(--v2-font-family-mono); font-size: var(--v2-text-micro-size); line-height: 1; letter-spacing: 0; }
+.step[data-done="true"] .step__index { color: var(--v2-state-fg-success); }
 .step__title { font-size: var(--v2-text-label-size); font-weight: var(--v2-weight-medium); line-height: var(--v2-text-label-line); letter-spacing: var(--v2-text-label-tracking); }
 .step__body { color: var(--v2-text-text-muted); font-size: var(--v2-text-micro-size); line-height: 1; letter-spacing: var(--v2-text-micro-tracking); }
 
@@ -355,10 +358,18 @@
   gap: 2px;
   min-height: 88px;
   padding: 12px 16px;
+  border: 0;
   border-radius: var(--v2-radius-surface);
   background: var(--v2-background-bg-layer-01);
   box-shadow: var(--v2-elevation-raised);
+  font: inherit;
+  text-align: start;
+  cursor: pointer;
+  transition: box-shadow var(--v2-motion-control), transform var(--v2-motion-control);
 }
+.stat-card:hover { box-shadow: var(--v2-elevation-floating); }
+.stat-card:focus-visible { outline: 2px solid var(--v2-border-border-focus); outline-offset: 2.5px; }
+.stat-card[data-active="true"] { box-shadow: var(--v2-elevation-floating), 0 0 0 1px var(--v2-border-border-strong); }
 .stat-card__label { display: flex; align-items: center; gap: 6px; color: var(--v2-text-text-muted); font-size: var(--v2-text-label-size); font-weight: var(--v2-weight-medium); line-height: var(--v2-text-label-line); letter-spacing: var(--v2-text-label-tracking); }
 .stat-card__value { color: var(--v2-text-text-base); font-size: var(--v2-text-stat-size); font-weight: var(--v2-weight-emphasis); line-height: var(--v2-text-stat-line); letter-spacing: var(--v2-text-stat-spacing); font-variant-numeric: tabular-nums; }
 .stat-card__hint { color: var(--v2-text-text-faint); font-size: var(--v2-text-micro-size); line-height: 1; letter-spacing: var(--v2-text-micro-tracking); }
@@ -504,4 +515,8 @@
   .topbar,
   .sidebar,
   .setting-row { box-shadow: none; border-color: CanvasText; }
+  /* I3: o Windows HC descarta outline não-mapeado — sem isto o foco some. */
+  *:focus-visible { outline-color: Highlight; }
+  .status-dot { forced-color-adjust: none; }
+  .stat-card[data-active="true"] { outline: 2px solid Highlight; }
 }
diff --git a/static/tokens.css b/static/tokens.css
index f570663..9555d31 100644
--- a/static/tokens.css
+++ b/static/tokens.css
@@ -368,19 +368,8 @@
   --v2-avatar-border-pink: #c83d8b;
   --v2-avatar-bg-purple: #623be2;
   --v2-avatar-border-purple: #5230c2;
-
-  --v2-elevation-raised: 0px 2px 4px 0px var(--v2-alpha-dark-4), 0px 1px 2px -1px var(--v2-alpha-dark-8), 0px 0px 0px 0.5px var(--v2-alpha-dark-12);
-  --v2-elevation-floating: 0px 8px 16px 0px var(--v2-alpha-dark-4), 0px 4px 8px 0px var(--v2-alpha-dark-8), 0px 0px 0px 0.5px var(--v2-alpha-dark-12);
-  --v2-elevation-overlay: 0px 16px 32px 0px var(--v2-alpha-dark-4), 0px 8px 16px 0px var(--v2-alpha-dark-8), 0px 0px 0px 0.5px var(--v2-alpha-dark-12);
-  --v2-elevation-button-neutral: 0px 1px 1.5px 0px var(--v2-alpha-dark-10), 0px 0px 0px 0.5px var(--v2-alpha-dark-14);
-  --v2-elevation-button-contrast: 0px 1px 1.5px 0px var(--v2-alpha-dark-20), 0px 0px 0px 0.5px var(--v2-grey-800), inset 0px 1px 2px 0px var(--v2-alpha-light-14), inset 0px -1px 2px 0px var(--v2-alpha-dark-6);
-  --v2-elevation-elements: 0px 0.5px 0.5px 0px var(--v2-alpha-dark-40);
-  --v2-elevation-switch-off: inset 0px 1px 1px 0px var(--v2-alpha-dark-8), inset 0px 0.5px 0.5px 0px var(--v2-alpha-dark-8), inset 0px 0px 0px 0.5px var(--v2-alpha-dark-10);
-  --v2-elevation-switch-on: inset 0px 2px 2px 0px var(--v2-alpha-dark-10), inset 0px 1px 1px 0px var(--v2-alpha-dark-10), inset 0px 0px 0px 0.5px var(--v2-alpha-dark-20);
-
-  --v2-illustration-layer-01: var(--v2-grey-300);
-  --v2-illustration-layer-02: var(--v2-grey-400);
-  --v2-illustration-layer-03: var(--v2-grey-500);
+  /* B3: elevation/illustration do light são idênticos ao :root (linhas 202-214)
+     — herança já resolve, 12 linhas duplicadas removidas. */
 }
 
 /* --------------------------------------------------------------------------

From e95851e49792b3a080456a38b4dd32e77d3afdc5 Mon Sep 17 00:00:00 2001
From: yanhenrique-dev <yanhenrique-dev@users.noreply.github.com>
Date: Wed, 30 Sep 2026 00:38:23 -0300
Subject: [PATCH 5/6] feat(frontend): leva de skills ux-heuristics,
 refactoring-ui, microinteractions, high-perf-browser
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ux-heuristics (H4/H6, Krug #3):
- card "Revisão ou erro" somava 2 categorias mas linkava 1: link dinâmico
  (paintSteps aponta p/ sem-dono ou erros, conforme a não-vazia)
- branch explícita com title="Branch fixada no mapeamento" (H6)
- cabeçalhos com metade das palavras (Biblioteca/Atividade/Preferências)

refactoring-ui:
- toast com fio lateral no tone (hierarquia sem ler o ícone)
- map-row com fio de pertencimento à linha do repo

microinteractions:
- "Atualizar pendentes (N)": botão mostra o tamanho do lote
- toast pausa no hover, rearma 2s na saída (não some sob o mouse)

high-perf-browser:
- preload de app.js + color-scheme dark light
- fontes com ?v=3 (casam com o preload; caem no immutable do servidor)

Gate: 169 pytest + 38 node --test + node --check + ruff + pyright verdes.
---
 static/app.js         | 19 +++++++++++++++++--
 static/components.css |  4 ++++
 static/index.html     | 18 ++++++++++--------
 static/shell.css      |  1 +
 static/tokens.css     |  6 +++---
 5 files changed, 35 insertions(+), 13 deletions(-)

diff --git a/static/app.js b/static/app.js
index c2d3c96..154a70f 100644
--- a/static/app.js
+++ b/static/app.js
@@ -296,7 +296,7 @@ function renderRow(row, index) {
 
   return `<tr data-row-index="${index}"${row.busy ? ' data-busy="true"' : ""}>
       <td>${renderIdentityCell(row, index)}</td>
-      <td>${row.auto ? `<span data-component="tag">${esc(branch)}</span>` : `<span data-component="tag" data-high-contrast>${esc(branch)}</span>`}</td>
+      <td>${row.auto ? `<span data-component="tag">${esc(branch)}</span>` : `<span data-component="tag" title="Branch fixada no mapeamento" data-high-contrast>${esc(branch)}</span>`}</td>
       <td>${esc(artifactLabel(row))}</td>
       <td><code>${esc(shortSha(row.local_sha))}</code></td>
       <td><code>${esc(shortSha(row.remote_sha))}</code></td>
@@ -469,6 +469,13 @@ function paintSteps(counts) {
   if (compare) compare.dataset.done = checked ? "true" : "false";
   if (swap) swap.dataset.done = state.base && counts.behind === 0 && counts.all > 0 ? "true" : "false";
   document.querySelectorAll("[data-filter-link]").forEach((card) => {
+    if ("attentionCard" in card.dataset) {
+      // H4: o card soma sem-dono+erros; o link vai para a categoria não-vazia,
+      // senão o clique mostrava "Nenhum item neste filtro" com N > 0 no card.
+      const target = counts.unmapped > 0 ? "unmapped" : "error";
+      card.dataset.filterLink = target;
+      card.setAttribute("aria-label", target === "unmapped" ? "Ver itens sem dono" : "Ver itens com erro");
+    }
     card.dataset.active = card.dataset.filterLink === state.filter ? "true" : "false";
   });
 }
@@ -509,6 +516,8 @@ function renderUnsafe() {
   restoreUrlDrafts(drafts);
 
   dom.btnAll.disabled = state.busy || !state.base || counts.behind === 0;
+  const allLabel = $("btn-all-label");
+  if (allLabel) allLabel.textContent = counts.behind > 0 ? `Atualizar pendentes (${counts.behind})` : "Atualizar pendentes";
 }
 
 /* ------------------------------------------------------------------ theme */
@@ -651,7 +660,13 @@ function toast(message, tone = "info") {
   item.querySelector("[data-slot=toast-v2-close]").addEventListener("click", dismiss);
   dom.toastRegion.appendChild(item);
   while (dom.toastRegion.children.length > 4) dom.toastRegion.firstElementChild.remove();
-  window.setTimeout(dismiss, 4600);
+  // Não some sob o mouse: hover pausa, saída rearma com 2s.
+  let dismissTimer = window.setTimeout(dismiss, 4600);
+  item.addEventListener("mouseenter", () => window.clearTimeout(dismissTimer));
+  item.addEventListener("mouseleave", () => {
+    window.clearTimeout(dismissTimer);
+    dismissTimer = window.setTimeout(dismiss, 2000);
+  });
 }
 
 function setBusy(value) {
diff --git a/static/components.css b/static/components.css
index b799c1a..2d78979 100644
--- a/static/components.css
+++ b/static/components.css
@@ -748,6 +748,10 @@ body {
 [data-component="toast-v2"][data-tone="warning"] [data-slot="toast-v2-icon"] { color: var(--v2-state-fg-warning); }
 [data-component="toast-v2"][data-tone="danger"] [data-slot="toast-v2-icon"] { color: var(--v2-state-fg-danger); }
 [data-component="toast-v2"][data-tone="info"] [data-slot="toast-v2-icon"] { color: var(--v2-state-fg-info); }
+[data-component="toast-v2"][data-tone="success"] { box-shadow: var(--v2-elevation-floating), inset 2px 0 0 0 var(--v2-state-fg-success); }
+[data-component="toast-v2"][data-tone="warning"] { box-shadow: var(--v2-elevation-floating), inset 2px 0 0 0 var(--v2-state-fg-warning); }
+[data-component="toast-v2"][data-tone="danger"] { box-shadow: var(--v2-elevation-floating), inset 2px 0 0 0 var(--v2-state-fg-danger); }
+[data-component="toast-v2"][data-tone="info"] { box-shadow: var(--v2-elevation-floating), inset 2px 0 0 0 var(--v2-state-fg-info); }
 
 @keyframes v2-toast-in { from { opacity: 0; transform: translateY(8px) scale(0.98); } to { opacity: 1; transform: translateY(0) scale(1); } }
 @keyframes v2-toast-out { from { opacity: 1; transform: translateY(0); } to { opacity: 0; transform: translateY(8px); } }
diff --git a/static/index.html b/static/index.html
index 158d368..49851d5 100644
--- a/static/index.html
+++ b/static/index.html
@@ -5,14 +5,16 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta id="theme-color" name="theme-color" content="#161616">
 <meta name="description" content="RepoRefresh — bancada local para manter cópias GitHub fiéis ao commit certo.">
+<meta name="color-scheme" content="dark light">
 <title>RepoRefresh — bancada local</title>
 <link rel="icon" href="/static/favicon.ico" sizes="16x16 32x32">
 <link rel="icon" type="image/png" href="/static/icon-32.png" sizes="32x32">
 <link rel="icon" type="image/png" href="/static/icon-16.png" sizes="16x16">
 <link rel="apple-touch-icon" href="/static/icon-180.png">
-<link rel="preload" href="/static/fonts/inter-400.woff2" as="font" type="font/woff2" crossorigin>
-<link rel="preload" href="/static/fonts/inter-500.woff2" as="font" type="font/woff2" crossorigin>
-<link rel="preload" href="/static/fonts/inter-600.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="/static/fonts/inter-400.woff2?v=3" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="/static/fonts/inter-500.woff2?v=3" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="/static/fonts/inter-600.woff2?v=3" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="/static/app.js?v=3" as="script">
 <link rel="stylesheet" href="/static/tokens.css?v=3" fetchpriority="high">
 <link rel="stylesheet" href="/static/components.css?v=3" fetchpriority="high">
 <link rel="stylesheet" href="/static/shell.css?v=3">
@@ -148,7 +150,7 @@
 
           <header class="page-header">
             <h1 class="page-header__title">Biblioteca</h1>
-            <p class="page-header__description">Escolha uma pasta, confirme a identidade de cada repositório e troque apenas o conteúdo verificado — sempre com backup e reversão.</p>
+            <p class="page-header__description">Escolha uma pasta, confirme cada repositório e troque o conteúdo verificado — sempre com backup e reversão.</p>
           </header>
 
           <section class="steps" aria-label="Etapas da operação">
@@ -187,7 +189,7 @@ <h1 class="page-header__title">Biblioteca</h1>
                 </button>
                 <button class="button-v2" data-component="button-v2" data-variant="neutral" data-size="small" type="button" id="btn-all" data-icon>
                   <svg class="icon" data-slot="icon" data-size="small" aria-hidden="true" focusable="false"><use href="#i-cloud"></use></svg>
-                  <span>Atualizar pendentes</span>
+                  <span id="btn-all-label">Atualizar pendentes</span>
                 </button>
               </div>
             </form>
@@ -205,7 +207,7 @@ <h1 class="page-header__title">Biblioteca</h1>
             <button type="button" class="stat-card" data-filter-link="all" aria-label="Ver todos os itens"><span class="stat-card__label">Itens detectados</span><span class="stat-card__value" id="sum-total">0</span><span class="stat-card__hint">pastas + arquivos ZIP</span></button>
             <button type="button" class="stat-card" data-tone="success" data-filter-link="ready" aria-label="Ver sincronizados"><span class="stat-card__label">Sincronizados</span><span class="stat-card__value" id="sum-ready">0</span><span class="stat-card__hint">commit local verificado</span></button>
             <button type="button" class="stat-card" data-tone="warning" data-filter-link="behind" aria-label="Ver pendentes de atualização"><span class="stat-card__label">Para atualizar</span><span class="stat-card__value" id="sum-behind">0</span><span class="stat-card__hint">commits disponíveis</span></button>
-            <button type="button" class="stat-card" data-tone="info" data-filter-link="unmapped" aria-label="Ver itens para revisão"><span class="stat-card__label">Revisão ou erro</span><span class="stat-card__value" id="sum-attention">0</span><span class="stat-card__hint">sem vínculo ou erro</span></button>
+            <button type="button" class="stat-card" data-tone="info" data-filter-link="unmapped" data-attention-card aria-label="Ver itens para revisão"><span class="stat-card__label">Revisão ou erro</span><span class="stat-card__value" id="sum-attention">0</span><span class="stat-card__hint">sem vínculo ou erro</span></button>
           </section>
 
           <section data-component="card" aria-labelledby="library-title">
@@ -262,7 +264,7 @@ <h1 class="page-header__title">Biblioteca</h1>
         <section class="page" data-page="activity" id="activity-view" hidden>
           <header class="page-header">
             <h1 class="page-header__title">Atividade</h1>
-            <p class="page-header__description">Registro contínuo de scans, comparações, trocas e reversões executadas nesta máquina.</p>
+            <p class="page-header__description">Scans, comparações, trocas e reversões executadas nesta máquina.</p>
           </header>
 
           <section data-component="card" aria-labelledby="log-title">
@@ -285,7 +287,7 @@ <h1 class="page-header__title">Atividade</h1>
         <section class="page" data-page="settings" id="settings-view" hidden>
           <header class="page-header">
             <h1 class="page-header__title">Preferências</h1>
-            <p class="page-header__description">Defina como o RepoRefresh trata atualização, backup e verificação automática.</p>
+            <p class="page-header__description">Atualização, backup e verificação automática.</p>
           </header>
 
           <section data-component="card" aria-label="Ajustes da bancada">
diff --git a/static/shell.css b/static/shell.css
index be4c4e8..ebdd63b 100644
--- a/static/shell.css
+++ b/static/shell.css
@@ -406,6 +406,7 @@
 .repo-actions [data-component="icon-button-v2"]:hover { color: var(--v2-text-text-base); }
 
 .map-row > td { height: auto; padding: 0 12px 12px; background: color-mix(in oklab, var(--v2-background-bg-accent) 4%, transparent); }
+.map-row > td { box-shadow: inset 2px 0 0 0 var(--v2-background-bg-accent); }
 .map-form { display: flex; align-items: flex-start; gap: 8px; flex-wrap: wrap; }
 .map-form [data-component="text-input-v2"] { flex: 1 1 280px; width: auto; }
 .map-suggestions { display: flex; flex-direction: column; gap: 4px; width: 100%; margin-top: 8px; }
diff --git a/static/tokens.css b/static/tokens.css
index 9555d31..596608d 100644
--- a/static/tokens.css
+++ b/static/tokens.css
@@ -17,21 +17,21 @@
   font-style: normal;
   font-weight: 440;
   font-display: swap;
-  src: url("/static/fonts/inter-400.woff2") format("woff2");
+  src: url("/static/fonts/inter-400.woff2?v=3") format("woff2");
 }
 @font-face {
   font-family: "Inter";
   font-style: normal;
   font-weight: 530;
   font-display: swap;
-  src: url("/static/fonts/inter-500.woff2") format("woff2");
+  src: url("/static/fonts/inter-500.woff2?v=3") format("woff2");
 }
 @font-face {
   font-family: "Inter";
   font-style: normal;
   font-weight: 610;
   font-display: swap;
-  src: url("/static/fonts/inter-600.woff2") format("woff2");
+  src: url("/static/fonts/inter-600.woff2?v=3") format("woff2");
 }
 
 /* --------------------------------------------------------------------------

From 976cd94db905395ec50abb72329ab95e934f4589 Mon Sep 17 00:00:00 2001
From: yanhenrique-dev <yanhenrique-dev@users.noreply.github.com>
Date: Wed, 30 Sep 2026 00:41:08 -0300
Subject: [PATCH 6/6] =?UTF-8?q?feat(frontend):=20web-typography,=20cro=20e?=
 =?UTF-8?q?=20higiene=20de=20c=C3=B3digo?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

web-typography (diagnóstico 8/10):
- text-wrap: balance nos títulos de página e empty-state; pretty no corpo
- medida já em 68ch/32ch; payload 72KB < 200KB; swap + fallbacks ok
- exceção documentada: corpo 13px é densidade de ferramenta, não leitura

cro-methodology (O/CO no ponto de fricção):
- confirmação do update cita o backup ("Com backup para reversão."
  ou "Sem backup: sem reversão.") — o medo de perder arquivos
  responde-se onde nasce, não nas Preferências
- empty de pasta vazia ganha saída ("Escolher outra pasta")
- sugestão vazia indica o próximo passo ("Cole a URL manualmente.")

clean-code:
- tempos mágicos viram constantes (SEARCH_DEBOUNCE_MS,
  PATH_AUTO_SCAN_DELAY_MS, TOAST_LIFETIME_MS, TOAST_HOVER_LIFETIME_MS,
  LOG_POLL_MS, MAX_TOASTS) — zero mudança de comportamento

Gate: 169 pytest + 38 node --test + node --check + ruff + pyright verdes.
---
 static/app.js         | 28 ++++++++++++++++++++--------
 static/components.css |  4 ++--
 static/shell.css      |  1 +
 3 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/static/app.js b/static/app.js
index 154a70f..a804d17 100644
--- a/static/app.js
+++ b/static/app.js
@@ -88,6 +88,14 @@ const REDUCED_MOTION =
 
 const TONE_ICON = { success: "check", warning: "alert", danger: "alert", info: "activity" };
 
+/* Tempos de interação (ms). Nomeados para leitura: mudar debounce sem caçar literais. */
+const SEARCH_DEBOUNCE_MS = 150;
+const PATH_AUTO_SCAN_DELAY_MS = 700;
+const TOAST_LIFETIME_MS = 4600;
+const TOAST_HOVER_LIFETIME_MS = 2000;
+const LOG_POLL_MS = 8000;
+const MAX_TOASTS = 4;
+
 if (!dom.repoList || !dom.pathInput || !dom.status || !dom.pathError || !dom.themeColor || !dom.liveStatus) {
   throw new Error("RepoRefresh: interface não carregada");
 }
@@ -288,8 +296,9 @@ function renderRow(row, index) {
       ? "Atualizar para o commit remoto"
       : "Checar atualizações";
 
+  const backupNote = state.backup ? " Com backup para reversão." : " Sem backup: sem reversão.";
   const hint = updating
-    ? '<p class="rollback-hint">Atualizar baixa o commit remoto e substitui o conteúdo local. Clique de novo para confirmar.</p>'
+    ? `<p class="rollback-hint">Atualizar baixa o commit remoto e substitui o conteúdo local.${backupNote} Clique de novo para confirmar.</p>`
     : reverting
       ? '<p class="rollback-hint">Reverter troca o estado atual pelo backup. Clique de novo para confirmar.</p>'
       : "";
@@ -333,6 +342,9 @@ function renderEmpty() {
         <span data-slot="empty-state-icon">${icon("scan", "large")}</span>
         <p data-slot="empty-state-title">Nenhum repositório encontrado</p>
         <p data-slot="empty-state-body">Confira o caminho escolhido. A pasta pode estar vazia ou sem permissão de leitura.</p>
+        <div data-slot="empty-state-actions">
+          <button class="button-v2" data-component="button-v2" data-variant="neutral" data-size="normal" type="button" data-action="focus-scan" data-icon>${icon("folder")}<span>Escolher outra pasta</span></button>
+        </div>
       </div>`;
   } else {
     body = `<div data-component="empty-state">
@@ -659,13 +671,13 @@ function toast(message, tone = "info") {
 
   item.querySelector("[data-slot=toast-v2-close]").addEventListener("click", dismiss);
   dom.toastRegion.appendChild(item);
-  while (dom.toastRegion.children.length > 4) dom.toastRegion.firstElementChild.remove();
+  while (dom.toastRegion.children.length > MAX_TOASTS) dom.toastRegion.firstElementChild.remove();
   // Não some sob o mouse: hover pausa, saída rearma com 2s.
-  let dismissTimer = window.setTimeout(dismiss, 4600);
+  let dismissTimer = window.setTimeout(dismiss, TOAST_LIFETIME_MS);
   item.addEventListener("mouseenter", () => window.clearTimeout(dismissTimer));
   item.addEventListener("mouseleave", () => {
     window.clearTimeout(dismissTimer);
-    dismissTimer = window.setTimeout(dismiss, 2000);
+    dismissTimer = window.setTimeout(dismiss, TOAST_HOVER_LIFETIME_MS);
   });
 }
 
@@ -1026,7 +1038,7 @@ async function suggestRepo(index) {
     row.suggestions = result.items || [];
     render();
     say(
-      row.suggestions.length ? `${row.suggestions.length} sugestões encontradas.` : "Nenhuma sugestão encontrada.",
+      row.suggestions.length ? `${row.suggestions.length} sugestões encontradas.` : "Nenhuma sugestão encontrada. Cole a URL manualmente.",
       row.suggestions.length ? "success" : "warning",
       true
     );
@@ -1329,7 +1341,7 @@ function init() {
     logTimer = setTimeout(() => {
       const active = document.visibilityState === "visible" && state.view === "activity";
       (active ? refreshLog() : Promise.resolve()).finally(scheduleLogRefresh);
-    }, 8000);
+    }, LOG_POLL_MS);
   }
   scheduleLogRefresh();
 
@@ -1377,7 +1389,7 @@ function registerEvents() {
       storeSet("alldown.query", state.query);
       render();
       writeHashState();
-    }, 150);
+    }, SEARCH_DEBOUNCE_MS);
   });
 
   dom.filters.addEventListener("click", (event) => {
@@ -1453,7 +1465,7 @@ function registerEvents() {
     if (!state.auto || !looksLikePath(value)) return;
     if (value === state.base && !state.lastScanFailed) return;
     window.clearTimeout(state.pathTimer);
-    state.pathTimer = window.setTimeout(doScan, 700);
+    state.pathTimer = window.setTimeout(doScan, PATH_AUTO_SCAN_DELAY_MS);
   });
 
   dom.pathInput.addEventListener("blur", () => {
diff --git a/static/components.css b/static/components.css
index 2d78979..41f8c98 100644
--- a/static/components.css
+++ b/static/components.css
@@ -884,8 +884,8 @@ body {
   text-align: center;
 }
 [data-component="empty-state"] [data-slot="empty-state-icon"] { color: var(--v2-icon-icon-muted); margin-bottom: 4px; }
-[data-component="empty-state"] [data-slot="empty-state-title"] { margin: 0; color: var(--v2-text-text-base); font-size: var(--v2-text-label-size); font-weight: var(--v2-weight-medium); line-height: var(--v2-text-label-line); letter-spacing: var(--v2-text-label-tracking); }
-[data-component="empty-state"] [data-slot="empty-state-body"] { margin: 0; max-width: 32ch; color: var(--v2-text-text-muted); font-size: var(--v2-text-label-size); font-weight: var(--v2-weight-regular); line-height: var(--v2-text-label-line); letter-spacing: var(--v2-text-label-tracking); }
+[data-component="empty-state"] [data-slot="empty-state-title"] { margin: 0; color: var(--v2-text-text-base); text-wrap: balance; font-size: var(--v2-text-label-size); font-weight: var(--v2-weight-medium); line-height: var(--v2-text-label-line); letter-spacing: var(--v2-text-label-tracking); }
+[data-component="empty-state"] [data-slot="empty-state-body"] { margin: 0; max-width: 32ch; text-wrap: pretty; color: var(--v2-text-text-muted); font-size: var(--v2-text-label-size); font-weight: var(--v2-weight-regular); line-height: var(--v2-text-label-line); letter-spacing: var(--v2-text-label-tracking); }
 [data-component="empty-state"] [data-slot="empty-state-actions"] { display: flex; align-items: center; gap: 8px; margin-top: 8px; }
 
 [data-component="skeleton"] {
diff --git a/static/shell.css b/static/shell.css
index ebdd63b..f29fe97 100644
--- a/static/shell.css
+++ b/static/shell.css
@@ -255,6 +255,7 @@
   align-items: center;
   gap: 8px;
   margin: 0;
+  text-wrap: balance;
   color: var(--v2-text-text-base);
   font-size: var(--v2-text-title-size);
   font-weight: var(--v2-weight-medium);