@jjlmoya/utils-home 1.37.0 → 1.39.0

package/package.json

@@ -1,13 +1,15 @@
 {
     "name": "@jjlmoya/utils-home",
-    "version": "1.37.0",
+    "version": "1.39.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",
     "exports": {
         ".": "./src/index.ts",
         "./data": "./src/data.ts",
-        "./entries": "./src/entries.ts"
+        "./entries": "./src/entries.ts",
+        "./runtime/*": "./src/tool/*/index.ts",
+        "./category-seo": "./src/category/seo.astro"
     },
     "files": [
         "src",

package/src/tests/pagespeed_best_practices.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it } from 'vitest';
+import { readdirSync, readFileSync } from 'fs';
+import { join, relative } from 'path';
+import { ALL_TOOLS } from '../tools';
+import type { SEOSection, ToolLocaleContent } from '../types';
+
+const srcDir = join(process.cwd(), 'src');
+const toolDir = join(srcDir, 'tool');
+const geometryReads = [
+  'offsetWidth',
+  'offsetHeight',
+  'offsetTop',
+  'offsetLeft',
+  'clientWidth',
+  'clientHeight',
+  'clientTop',
+  'clientLeft',
+  'scrollWidth',
+  'scrollHeight',
+  'scrollTop',
+  'scrollLeft',
+  'getBoundingClientRect',
+  'getClientRects',
+  'computedStyle',
+  'getComputedStyle',
+];
+const domWrites = [
+  '.style.',
+  '.classList.add',
+  '.classList.remove',
+  '.classList.toggle',
+  '.appendChild',
+  '.insertBefore',
+  '.prepend',
+  '.append',
+  '.remove',
+  '.innerHTML',
+  '.textContent',
+  '.setAttribute',
+];
+
+function findFiles(dir: string, extensions: string[]): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...findFiles(fullPath, extensions));
+    else if (extensions.some((extension) => entry.name.endsWith(extension))) files.push(fullPath);
+  }
+  return files;
+}
+
+function relativePath(file: string): string {
+  return relative(process.cwd(), file).replace(/\\/g, '/');
+}
+
+function findFormControls(content: string, tagName: 'input' | 'select'): RegExpMatchArray[] {
+  return Array.from(content.matchAll(new RegExp(`<${tagName}\\b[^>]*>`, 'gi')));
+}
+
+function attrValue(tag: string, attr: string): string | null {
+  const match = tag.match(new RegExp(`\\b${attr}\\s*=\\s*(?:"([^"]+)"|'([^']+)'|\\{([^}]+)\\})`, 'i'));
+  return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+}
+
+function booleanAttr(tag: string, attr: string): boolean {
+  return new RegExp(`\\b${attr}\\b`, 'i').test(tag);
+}
+
+function controlStartIndex(content: string, tag: RegExpMatchArray): number {
+  return tag.index ?? content.indexOf(tag[0]);
+}
+
+function hasWrappingLabel(content: string, tag: RegExpMatchArray): boolean {
+  const index = controlStartIndex(content, tag);
+  const before = content.slice(0, index);
+  const labelOpen = before.lastIndexOf('<label');
+  const labelClose = before.lastIndexOf('</label>');
+  const nextLabelClose = content.indexOf('</label>', index + tag[0].length);
+  return labelOpen > labelClose && nextLabelClose !== -1;
+}
+
+function hasAccessibleName(content: string, tag: RegExpMatchArray): boolean {
+  const source = tag[0];
+  if (attrValue(source, 'aria-label')) return true;
+  if (attrValue(source, 'aria-labelledby')) return true;
+  const id = attrValue(source, 'id');
+  if (id && hasExplicitLabel(content, id)) return true;
+  return hasWrappingLabel(content, tag);
+}
+
+function isVisuallyHiddenFileInput(tag: string): boolean {
+  const type = attrValue(tag, 'type')?.toLowerCase() ?? 'text';
+  const attributes = `${attrValue(tag, 'style') ?? ''} ${attrValue(tag, 'class') ?? ''}`.toLowerCase();
+  const hiddenPatterns = ['display:none', 'display: none', 'file-input'];
+  return type === 'file' && hiddenPatterns.some((pattern) => attributes.includes(pattern));
+}
+
+function isIgnoredInput(tag: string): boolean {
+  const type = attrValue(tag, 'type')?.toLowerCase() ?? 'text';
+  return ['hidden', 'button', 'submit', 'reset'].includes(type) || booleanAttr(tag, 'aria-hidden') || isVisuallyHiddenFileInput(tag);
+}
+
+function controlFailures(content: string, tagName: 'input' | 'select'): string[] {
+  return findFormControls(content, tagName)
+    .filter((tag) => tagName !== 'input' || !isIgnoredInput(tag[0]))
+    .filter((tag) => !hasAccessibleName(content, tag))
+    .map((tag) => tag[0]);
+}
+
+function explicitLabelMessage(tagName: string, path: string, failures: string[]): string {
+  return `${tagName} controls without label, wrapping label, aria-label or aria-labelledby in ${path}:\n${failures.join('\n')}`;
+}
+
+function hasExplicitLabel(content: string, id: string): boolean {
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return (
+    new RegExp(`<label\\b[^>]*\\bfor\\s*=\\s*["']${escapedId}["'][^>]*>`, 'i').test(content)
+    || new RegExp(`<label\\b[^>]*\\bfor\\s*=\\s*\\{${escapedId}\\}[^>]*>`, 'i').test(content)
+  );
+}
+
+function headingLevels(sections: SEOSection[]): number[] {
+  return sections
+    .filter((section) => section.type === 'title')
+    .map((section) => Number('level' in section ? section.level : 0))
+    .filter((level) => Number.isInteger(level) && level > 0);
+}
+
+function findHeadingLevelJumps(levels: number[]): string[] {
+  const failures: string[] = [];
+  levels.forEach((level, index) => {
+    const previous = index === 0 ? 1 : levels[index - 1];
+    if (previous && level > previous + 1) {
+      failures.push(`h${previous} -> h${level}`);
+    }
+  });
+  return failures;
+}
+
+function hasDomWriteBeforeGeometryRead(content: string): boolean {
+  const normalized = content.replace(/\s+/g, ' ');
+  return domWrites.some((write) => {
+    const writeIndex = normalized.indexOf(write);
+    if (writeIndex === -1) return false;
+    return geometryReads.some((read) => normalized.indexOf(read, writeIndex + write.length) !== -1);
+  });
+}
+
+describe('PageSpeed best-practice guards', () => {
+  const astroToolFiles = findFiles(toolDir, ['.astro']);
+  const scriptFiles = findFiles(toolDir, ['.astro', '.ts', '.js']);
+
+  astroToolFiles.forEach((file) => {
+    const displayPath = relativePath(file);
+
+    it(`${displayPath} labels every input with an explicit label`, () => {
+      const content = readFileSync(file, 'utf-8');
+      const failures = controlFailures(content, 'input');
+
+      expect(failures, explicitLabelMessage('Input', displayPath, failures)).toEqual([]);
+    });
+
+    it(`${displayPath} labels every select with an explicit label`, () => {
+      const content = readFileSync(file, 'utf-8');
+      const failures = controlFailures(content, 'select');
+
+      expect(failures, explicitLabelMessage('Select', displayPath, failures)).toEqual([]);
+    });
+  });
+
+  ALL_TOOLS.forEach((tool) => {
+    Object.entries(tool.entry.i18n).forEach(([locale, loader]) => {
+      it(`${tool.entry.id}/${locale} keeps SEO headings sequential`, async () => {
+        if (!loader) return;
+        const content = (await loader()) as ToolLocaleContent;
+        const levels = headingLevels(content.seo);
+        const failures = findHeadingLevelJumps(levels);
+
+        expect(
+          failures,
+          `SEO headings in ${tool.entry.id}/${locale} skip levels: ${failures.join(', ')}`,
+        ).toEqual([]);
+      });
+    });
+  });
+
+  scriptFiles.forEach((file) => {
+    const displayPath = relativePath(file);
+
+    it(`${displayPath} avoids static forced-reflow patterns`, () => {
+      const content = readFileSync(file, 'utf-8');
+      expect(
+        hasDomWriteBeforeGeometryRead(content),
+        `${displayPath} appears to read layout geometry after DOM/style mutations. Split writes and reads across frames or measure before mutating.`,
+      ).toBe(false);
+    });
+  });
+});

package/src/tool/acTonnageCalculator/client-animations.ts

@@ -1,3 +1,7 @@
+function getStrokeColor(el: HTMLElement | null): string {
+  return el ? getComputedStyle(el).stroke : '#0ea5e9';
+}
+
 function getLabels(): Record<string, string> {
   const el = document.getElementById('ac-labels');
   if (!el) return {};
@@ -24,18 +28,11 @@ function roomLabel(btu: number): string {
   return labels.labelRoomHot ?? '';
 }
 
-export function updateMiniRoom(btu: number) {
-  const svg = document.querySelector('.ac-mini-room svg');
-  if (!svg) return;
-  const txt = svg.querySelector('text');
-  if (txt) txt.textContent = roomLabel(btu);
-}
-
 export function spawnRipple() {
   const wrap = document.querySelector('.ac-ring-wrap');
   if (!wrap) return;
   const el = document.getElementById('ac-ring-fill');
-  const color = el ? getComputedStyle(el).stroke : '#0ea5e9';
+  const color = getStrokeColor(el as HTMLElement | null);
   const ripple = document.createElement('div');
   ripple.className = 'ac-ripple';
   ripple.style.left = '50%';
@@ -46,6 +43,13 @@ export function spawnRipple() {
   setTimeout(() => ripple.remove(), 800);
 }
 
+export function updateMiniRoom(btu: number) {
+  const svg = document.querySelector('.ac-mini-room svg');
+  if (!svg) return;
+  const txt = svg.querySelector('text');
+  if (txt) txt.textContent = roomLabel(btu);
+}
+
 export function pulseGlow() {
   const glow = document.getElementById('ac-ring-glow');
   if (!glow) return;

package/src/tool/acTonnageCalculator/client.ts

@@ -88,7 +88,7 @@ function renderResult(res: ReturnType<typeof calculateAcTonnage>, people: number
   updateMiniRoom(res.btu);
   spawnRipple();
   const card = el('ac-card');
-  if (card) { card.classList.remove('ac-peak'); void card.offsetWidth; card.classList.add('ac-peak'); }
+  if (card) { card.classList.remove('ac-peak'); requestAnimationFrame(() => { card!.classList.add('ac-peak'); }); }
 }
 
 function update() {

package/src/tool/acTonnageCalculator/component.astro

@@ -57,7 +57,7 @@ function breakdownLabel(key: string): string {
       </div>
       <div class="ac-field">
         <div class="ac-field-top">
-          <span class="ac-label">{aUI.labelRoomSize}</span>
+          <label class="ac-label" for="ac-area">{aUI.labelRoomSize}</label>
           <span class="ac-val" id="ac-area-num">{defaults.area}</span>
         </div>
         <input class="ac-slider" type="range" id="ac-area" min="5" max="120" step="1" value={defaults.area} />
@@ -68,28 +68,28 @@ function breakdownLabel(key: string): string {
       </div>
       <div class="ac-field">
         <div class="ac-field-top">
-          <span class="ac-label">{aUI.labelCeilingHeight}</span>
+          <label class="ac-label" for="ac-height">{aUI.labelCeilingHeight}</label>
           <span class="ac-val" id="ac-height-num">{defaults.height}</span>
         </div>
         <input class="ac-slider" type="range" id="ac-height" min="2" max="6" step="0.1" value={defaults.height} />
       </div>
       <div class="ac-field">
         <div class="ac-field-top">
-          <span class="ac-label">{aUI.labelPeople}</span>
+          <label class="ac-label" for="ac-people">{aUI.labelPeople}</label>
           <span class="ac-val" id="ac-people-num">{defaults.people}</span>
         </div>
         <input class="ac-slider" type="range" id="ac-people" min="0" max="20" step="1" value={defaults.people} />
       </div>
       <div class="ac-field">
         <div class="ac-field-top">
-          <span class="ac-label">{aUI.labelHeatSources}</span>
+          <label class="ac-label" for="ac-heat">{aUI.labelHeatSources}</label>
           <span class="ac-val" id="ac-heat-num">{defaults.heat}</span>
         </div>
         <input class="ac-slider" type="range" id="ac-heat" min="0" max="20" step="1" value={defaults.heat} />
       </div>
       <div class="ac-row">
         <div class="ac-select-wrap">
-          <span class="ac-label">{aUI.labelSunExposure}</span>
+          <label class="ac-label" for="ac-sun">{aUI.labelSunExposure}</label>
           <select class="ac-select" id="ac-sun">
             <option value="light">{aUI.sunLight}</option>
             <option value="medium" selected>{aUI.sunMedium}</option>
@@ -97,7 +97,7 @@ function breakdownLabel(key: string): string {
           </select>
         </div>
         <div class="ac-select-wrap">
-          <span class="ac-label">{aUI.labelRoomType}</span>
+          <label class="ac-label" for="ac-room">{aUI.labelRoomType}</label>
           <select class="ac-select" id="ac-room">
             <option value="bedroom">{aUI.roomBedroom}</option>
             <option value="living" selected>{aUI.roomLiving}</option>

package/src/tool/applianceCostCalculator/component.astro

@@ -163,6 +163,10 @@ const PEAK = new Set([8, 9, 10, 11, 18, 19, 20, 21]);
 <script>
   import { calculateCycleCost, fmt2 } from './logic';
 
+  function getRect(e: HTMLElement): DOMRect {
+    return e.getBoundingClientRect();
+  }
+
   const RATES: Record<string, number> = { eur: 1, usd: 1.08, gbp: 0.85, jpy: 160 };
   const LS_KEY_CURRENCY = 'appliance-cost-currency';
   let currency: 'usd' | 'eur' | 'gbp' | 'jpy' = 'eur';
@@ -208,8 +212,8 @@ const PEAK = new Set([8, 9, 10, 11, 18, 19, 20, 21]);
   function moveIndicator(track: HTMLElement, activeBtn: HTMLElement) {
     const ind = el('apc-pill-indicator') as HTMLElement | null;
     if (!ind || !track || !activeBtn) return;
-    const tRect = track.getBoundingClientRect();
-    const bRect = activeBtn.getBoundingClientRect();
+    const tRect = getRect(track);
+    const bRect = getRect(activeBtn);
     ind.style.width = `${bRect.width}px`;
     ind.style.transform = `translateX(${bRect.left - tRect.left}px)`;
   }

package/src/tool/deskErgonomics/component.astro

@@ -27,7 +27,7 @@ const monPct = Math.min((initial.monitorHeight / maxVal) * 100, 100);
       </div>
       <div class="ergo-field">
         <div class="ergo-field-top">
-          <span class="ergo-label">{eUI.labelHeight}</span>
+          <label class="ergo-label" for="ergo-height">{eUI.labelHeight}</label>
           <span class="ergo-val" id="ergo-height-val">{defaultHeight} {eUI.unitCm}</span>
         </div>
         <input type="range" class="ergo-slider" id="ergo-height" min="140" max="210" step="1" value={defaultHeight} />

package/src/tool/humidityCalculator/component.astro

@@ -89,12 +89,12 @@ const initial = calculateHumidity({ roomM2: DEF_ROOM, tempC: DEF_TEMP, currentRH
 
       <div class="hc-sliders">
         <div class="hc-slider-group">
-          <label class="hc-slider-label">{hUI.labelTargetHumidity}</label>
+          <label class="hc-slider-label" for="hc-rh-t">{hUI.labelTargetHumidity}</label>
           <input type="range" id="hc-rh-t" class="hc-slider" min="0" max="100" value={DEF_TAR} />
           <span class="hc-slider-val" id="hc-rh-t-val">{DEF_TAR}{hUI.unitPercent}</span>
         </div>
         <div class="hc-slider-group">
-          <label class="hc-slider-label">{hUI.labelCapacity}</label>
+          <label class="hc-slider-label" for="hc-cap">{hUI.labelCapacity}</label>
           <input type="range" id="hc-cap" class="hc-slider" min="0" max="100" value={DEF_CAP} />
           <span class="hc-slider-val" id="hc-cap-val">{DEF_CAP}{hUI.unitLitersDay}</span>
         </div>
@@ -205,8 +205,7 @@ const initial = calculateHumidity({ roomM2: DEF_ROOM, tempC: DEF_TEMP, currentRH
     const ring = el('hc-runtime-ring') as HTMLElement | null;
     if (ring) {
       ring.classList.remove('hc-pulse');
-      void ring.offsetWidth;
-      ring.classList.add('hc-pulse');
+      requestAnimationFrame(() => { ring!.classList.add('hc-pulse'); });
     }
   }
 

package/src/tool/projectorCalculator/component.astro

@@ -25,7 +25,7 @@ const initial = calculateProjection(100, 16 / 9, 1.5);
           <label class="proj-label" for="proj-diagonal">{pUI.labelDiagonal}</label>
           <span class="proj-unit">{pUI.labelDiagonalUnit}</span>
         </div>
-        <input type="range" id="proj-diagonal-slider" min="30" max="300" value="100" step="1" class="proj-slider" />
+        <input type="range" id="proj-diagonal-slider" min="30" max="300" value="100" step="1" class="proj-slider" aria-label={pUI.labelDiagonal} />
         <div class="proj-number-row">
           <input type="number" id="proj-diagonal" value="100" min="30" max="300" class="proj-number-input" />
           <span class="proj-number-unit">"</span>

package/src/tool/qrGenerator/component.astro

@@ -24,11 +24,11 @@ const qrUI = ui as QRGeneratorUI;
 
       <div id="form-wifi" class="qr-form">
         <div class="field-group">
-          <label class="field-label">{qrUI.labelSsid}</label>
-          <input type="text" name="ssid" class="qr-input field-input" placeholder={qrUI.placeholderSsid} />
+          <label class="field-label" for="qr-ssid">{qrUI.labelSsid}</label>
+          <input type="text" name="ssid" id="qr-ssid" class="qr-input field-input" placeholder={qrUI.placeholderSsid} />
         </div>
         <div class="field-group">
-          <label class="field-label">{qrUI.labelPassword}</label>
+          <label class="field-label" for="wifi-password">{qrUI.labelPassword}</label>
           <div class="input-row">
             <input type="password" name="password" id="wifi-password" class="qr-input field-input" placeholder={qrUI.placeholderPassword} />
             <button type="button" id="toggle-password" class="eye-btn" aria-label="toggle password">
@@ -38,8 +38,8 @@ const qrUI = ui as QRGeneratorUI;
         </div>
         <div class="two-col">
           <div class="field-group">
-            <label class="field-label">{qrUI.labelEncryption}</label>
-            <select name="encryption" class="qr-input field-input">
+            <label class="field-label" for="qr-encryption">{qrUI.labelEncryption}</label>
+            <select name="encryption" id="qr-encryption" class="qr-input field-input">
               <option value="WPA">{qrUI.encWpa}</option>
               <option value="WEP">{qrUI.encWep}</option>
               <option value="nopass">{qrUI.encNone}</option>
@@ -56,33 +56,33 @@ const qrUI = ui as QRGeneratorUI;
 
       <div id="form-url" class="qr-form hidden">
         <div class="field-group">
-          <label class="field-label">{qrUI.labelUrl}</label>
-          <input type="url" name="url" class="qr-input field-input" placeholder={qrUI.placeholderUrl} />
+          <label class="field-label" for="qr-url">{qrUI.labelUrl}</label>
+          <input type="url" name="url" id="qr-url" class="qr-input field-input" placeholder={qrUI.placeholderUrl} />
         </div>
       </div>
 
       <div id="form-vcard" class="qr-form hidden">
         <div class="two-col">
           <div class="field-group">
-            <label class="field-label">{qrUI.labelName}</label>
-            <input type="text" name="name" class="qr-input field-input" />
+            <label class="field-label" for="qr-name">{qrUI.labelName}</label>
+            <input type="text" name="name" id="qr-name" class="qr-input field-input" />
           </div>
           <div class="field-group">
-            <label class="field-label">{qrUI.labelSurname}</label>
-            <input type="text" name="surname" class="qr-input field-input" />
+            <label class="field-label" for="qr-surname">{qrUI.labelSurname}</label>
+            <input type="text" name="surname" id="qr-surname" class="qr-input field-input" />
           </div>
         </div>
         <div class="field-group">
-          <label class="field-label">{qrUI.labelPhone}</label>
-          <input type="tel" name="phone" class="qr-input field-input" />
+          <label class="field-label" for="qr-phone">{qrUI.labelPhone}</label>
+          <input type="tel" name="phone" id="qr-phone" class="qr-input field-input" />
         </div>
         <div class="field-group">
-          <label class="field-label">{qrUI.labelEmail}</label>
-          <input type="email" name="email" class="qr-input field-input" />
+          <label class="field-label" for="qr-email">{qrUI.labelEmail}</label>
+          <input type="email" name="email" id="qr-email" class="qr-input field-input" />
         </div>
         <div class="field-group">
-          <label class="field-label">{qrUI.labelOrg}</label>
-          <input type="text" name="org" class="qr-input field-input" />
+          <label class="field-label" for="qr-org">{qrUI.labelOrg}</label>
+          <input type="text" name="org" id="qr-org" class="qr-input field-input" />
         </div>
       </div>
     </div>

package/src/tool/tariffComparator/component.astro

@@ -151,7 +151,7 @@ function iBarH(val: number): number {
           <p class="tc-sim-desc">{tUI.labelSolarDesc}</p>
         </div>
         <div class="tc-sim-card">
-          <p class="tc-sim-title">{tUI.labelShift}</p>
+          <label class="tc-sim-title" for="tc-shift">{tUI.labelShift}</label>
           <input type="range" id="tc-shift" min="0" max="50" step="5" value="0" class="tc-slider" />
           <p class="tc-sim-desc">{tUI.labelShiftDesc} <strong id="tc-shift-val">0%</strong></p>
         </div>

package/src/tool/tileLayoutCalculator/tile-layout-calculator.css

@@ -329,8 +329,8 @@
   gap: 10px;
   padding: 10px 16px;
   border-radius: 12px;
-  background: var(--tile-bg-glow);
-  border: 1px solid var(--tile-stroke);
+  background: var(--bg-surface);
+  border: 1px solid var(--border-color);
   width: 100%;
   max-width: 320px;
 }

package/src/tool/vampireDrawSimulator/component.astro

@@ -69,7 +69,7 @@ const initial = calculateVampireDraw(DEFAULT_DEVICES.map((d) => ({ name: d.name,
           <div class="vamp-device-row" data-name={d.name} data-watts={d.watts}>
             <span class="vamp-device-name">{d.name}</span>
             <span class="vamp-device-watts">{d.watts} {vUI.unitWatts}</span>
-            <input type="number" class="vamp-device-hours" value={d.hours} min="0" max="24" step="1" />
+            <input type="number" class="vamp-device-hours" value={d.hours} min="0" max="24" step="1" aria-label={vUI.labelHours} />
             <span class="vamp-device-watts">{vUI.unitHours}</span>
             <button class="vamp-remove-btn">{vUI.removeDevice}</button>
           </div>
@@ -223,7 +223,7 @@ const initial = calculateVampireDraw(DEFAULT_DEVICES.map((d) => ({ name: d.name,
     row.className = 'vamp-device-row';
     row.dataset.name = name;
     row.dataset.watts = String(watts);
-    row.innerHTML = `<span class="vamp-device-name">${name}</span><span class="vamp-device-watts">${watts} ${unitW}</span><input type="number" class="vamp-device-hours" value="${hours}" min="0" max="24" step="1" /><span class="vamp-device-watts">${unitH}</span><button class="vamp-remove-btn">${removeLabel}</button>`;
+    row.innerHTML = `<span class="vamp-device-name">${name}</span><span class="vamp-device-watts">${watts} ${unitW}</span><input type="number" class="vamp-device-hours" value="${hours}" min="0" max="24" step="1" aria-label="hours" /><span class="vamp-device-watts">${unitH}</span><button class="vamp-remove-btn">${removeLabel}</button>`;
     list.appendChild(row);
     attachRowListeners(row, card);
     calculate(card);

package/src/tool/wifiRangeSimulator/sketch-render-dash.ts

@@ -163,8 +163,10 @@ export function updateDashboard(
   const ring = document.getElementById('sketch-ring');
   if (ring) {
     ring.classList.remove('sketch-peak-anim', 'sketch-danger-anim');
-    void ring.offsetWidth;
-    if (avgResult.verdict === 'perfect') ring.classList.add('sketch-peak-anim');
-    if (avgResult.verdict === 'dead') ring.classList.add('sketch-danger-anim');
+    requestAnimationFrame(() => {
+      if (!ring) return;
+      if (avgResult.verdict === 'perfect') ring.classList.add('sketch-peak-anim');
+      if (avgResult.verdict === 'dead') ring.classList.add('sketch-danger-anim');
+    });
   }
 }

package/src/tool/wifiRangeSimulator/sketch-render.ts

@@ -3,6 +3,10 @@ import { calculateSignalFromSketch, getVerdictColor, MATERIALS } from './logic';
 import { buildDeviceSVG } from './sketch-render-device';
 import { getUI } from './i18n-utils';
 
+function getRect(el: HTMLElement): DOMRect {
+  return el.getBoundingClientRect();
+}
+
 export function renderWalls(walls: Segment[]) {
   const layer = document.getElementById('sketch-walls-layer');
   if (!layer) return;
@@ -121,10 +125,10 @@ export function renderRays(router: Point, devices: PlacedDevice[], walls: Segmen
 export function spawnParticle(x: number, y: number, text: string) {
   const wrap = document.getElementById('sketch-canvas-wrap');
   if (!wrap) return;
+  const rect = getRect(wrap);
   const p = document.createElement('span');
   p.className = 'sketch-particle';
   p.textContent = text;
-  const rect = wrap.getBoundingClientRect();
   p.style.left = `${x - rect.left}px`;
   p.style.top = `${y - rect.top}px`;
   wrap.appendChild(p);