frontend-visual-verification

Frontend Visual Verification (beating stale browser cache)

Overview

You changed a stylesheet/template and want to see it worked. The trap: a browser_vision screenshot can show the old layout even though the server is already serving your new code. The browser cache (notably for /css/*.css and other static assets) survives a container rebuild and a re-navigate to the same URL — the HTML re-renders but the stale stylesheet is reused. The vision model then confidently describes the OLD layout as if it were real.

Never trust a single screenshot when it contradicts the DOM or the served asset. Cross-check with the triple below.

The triple-check (do this before declaring "it didn't work")

1. DOM — browser_snapshot(). The markup reflects the HTML you served. If your new wrapper/selector is present, the HTML is new.
2. Computed style — run in browser_console, read the returned dict:

   (() => {
     const el = document.querySelector('.your-new-selector');
     if (!el) return 'SELECTOR NOT IN DOM';
     const cs = getComputedStyle(el);
     return { display: cs.display, position: cs.position,
              grid: cs.gridTemplateColumns, borderRight: cs.borderRightWidth };
   })()
   

   If this shows OLD values while the DOM shows the new structure, it's cache.
3. Served asset — from the terminal: curl -s http://HOST/css/main.css | grep -c 'your-new-token' Server new + browser computed-style old ⇒ 100% cache, not your code.

Force a fresh stylesheet (no hard-reload in the toolset)

Bust the cache by rewriting the <link> href to a unique query string, wait ~600ms, then re-screenshot:

(() => {
  const l = document.querySelector('link[rel="stylesheet"]');
  l.href = l.href.split('?')[0] + '?cb=' + Date.now();
  return 'busted: ' + l.href;
})()

Now browser_vision reflects the new CSS.

Container / static-asset gotchas

• Docker with read-only filesystem: local file edits do NOT reach the running container. Rebuild/restart first: docker compose -f <file> -p <proj> up -d --build Repo HANDOFF.md/AGENTS.md usually state this — read them before debugging "why isn't my change showing up".
• Autologin demos / protected pages: a nav-guard may bounce you to /login or the landing. To reach a protected page in the browser, either hit the auth route that sets the cookie (e.g. POST /api/auth/login via curl to grab a cookie jar, then reuse with curl -b jar), or just fill the login form in the browser with demo credentials. Don't debug layout while stuck in a redirect loop.
• CSS <link> without ?v= = rebuild never reaches the browser (real session, ~20 wasted iterations). If the header serves <link rel=stylesheet href="/css/main.css"> with NO query string, the browser caches the file in disk and NO container rebuild updates it — the DOM keeps measuring the old rule (e.g. align-items: stretch) even though the host file already says start. Fix: version the link like the footer already does — href="/css/main.css?v=<%= assetVersion %>" (the assetVersion is set in app.locals by the server; in an EJS partial use the bare global <%= assetVersion %>, NOT app.locals.assetVersion — that throws a runtime 500). Then changing CSS and bumping ASSET_VERSION actually busts the cache.
• Demo visual change invisible until you rebuild BOTH app and app-demo. The browser requests /css/main.css (absolute, no /demo/), and nginx routes /css/* → location / → the app principal, NOT app-demo. So a CSS/header
  • Demo visual change invisible until you rebuild BOTH app and app-demo, AND the browser loads /css/main.css from the PRINCIPAL, not the demo. In the financas-app setup the page /demo/app references the stylesheet at /css/main.css (absolute, no /demo/ prefix); nginx routes /css/* → location / → the app principal container, NOT app-demo. So even after you rebuild app-demo, the browser keeps showing the OLD CSS because the principal is still serving the previous file. Symptom that cost a full debug cycle: DevTools document.styleSheets listed http://HOST/css/main.css (no /demo), and a computed-style check reported the OLD marginTop even though curl /demo/css/main.css clearly had the new rule — the two URLs are DIFFERENT files. Fix: rebuild BOTH containers (docker compose up -d --build app app-demo) and verify the served bytes of the PRINCIPAL: curl -s http://HOST/css/main.css?v=probe | grep -n 'your-new-token'. If it still shows the old rule, app (principal) wasn't rebuilt — rebuilding only app-demo is not enough.
  • ASSET_VERSION cache-bust is mandatory for the USER's browser, not just yours. header.ejs already links /css/main.css?v=<%= assetVersion %> and footer.ejs versions the JS the same way (app.locals.assetVersion = process.env.ASSET_VERSION || '1'). When you ship a CSS fix, bump ASSET_VERSION in the compose env (ASSET_VERSION: ${ASSET_VERSION:-1} → pass ASSET_VERSION=2 docker compose up -d --build app app-demo) so the user's already-open tab actually re-fetches the new asset instead of using the cached ?v=1. For YOUR OWN validation you can also just navigate the browser directly to the versioned URL (/css/main.css?v=2) to force a fresh fetch before measuring computed style.
  • /css/main.css (principal) and /demo/css/main.css (app-demo) are DIFFERENT files — grep the one the browser actually loads. In financas-app the page /demo/app requests the stylesheet at the absolute /css/main.css (no /demo/), so nginx routes it to location / → the app principal container. The curl /demo/css/main.css you may be checking is the demo's copy and can have your new rule while the browser still shows the old one. Always cross-check the SAME url the browser fetches: curl -s http://HOST/css/main.css | grep -c 'your-new-token'. If that shows 0 but /demo/css/main.css shows 2, the principal wasn't rebuilt — docker compose up -d --build app app-demo (both), then re-grep /css/main.css.
  • Nested-card spacing pattern (financas-app dashboard). Cards that are children of .container/<main> but whose preceding sibling is a <div class="grid-2"> (not a .card) are NOT reached by the global .card + .card { margin-top }, so they "colam" no módulo anterior. Fix: .container > .card { margin-top: 1.5rem } + .container > .card:first-child { margin-top: 0 }. Cards nested inside another card (e.g. "Custo mensal" inside the Veículos card) also miss .card + .card → add .card > .card { margin-top: 1.25rem }. And restore margin-top inside @media (max-width: 820px) for .grid-2 > .card + .card / .split > .card + .card so stacked columns keep their gap.
  • Rosca (donut) chart labels. In financas-app the SVG donut is built in app/public/js/financas-lib.js (função rosca). It drew a fixed, oversized <text> percent label inside each slice — Pedro called this "feio" / "percentuais muito grandes". Fix: drop the fixed <text>, keep the native <title> (hover shows label — % (R$ valor)), and rely on the legend <ul> below the chart (already renders label + % + value). Verify by snapshot: center of donut should be empty (or show only the total), legend below carries the %s.