From the webcam to an animated hand on the screen

<!doctype html>
<html lang="it">
  <head>
    <meta charset="UTF-8" />
    <!-- senza questo, sul telefono la pagina viene rimpicciolita come un sito desktop -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Mano</title>
  </head>

  <!-- data-state lo aggiorna main.ts: idle | loading | running | error -->
  <body data-state="idle">
    <canvas id="scene" aria-label="Riproduzione 3D della mano"></canvas>

    <header class="topbar">
      <div class="brand">✋ Mano</div>
      <div class="status" id="status" role="status" aria-live="polite">Camera spenta</div>
    </header>

    <!-- La camera si accende SOLO da qui: è una scelta esplicita di chi guarda,
         mai un effetto collaterale dell'apertura della pagina. -->
    <section class="intro" id="intro">
      <h1>Muovi la mano davanti alla webcam</h1>
      <button type="button" class="primary" id="start">Accendi la camera</button>
      <p class="privacy">Tutto avviene nel tuo browser: le immagini non vengono inviate
         a nessun server né salvate.</p>
      <p class="error" id="error" hidden></p>
    </section>

    <!-- Anteprima della webcam con i puntini sopra: serve a capire cosa "vede" il modello.
         muted e playsinline: senza, iOS si rifiuta di riprodurre il video dentro la pagina. -->
    <aside class="preview" id="preview" hidden>
      <video id="video" autoplay muted playsinline></video>
      <canvas id="overlay"></canvas>
    </aside>

    <footer class="hud" id="hud" hidden>
      <div class="gestures" id="gestures"></div>
      <div class="controls">
        <span class="metric" id="fps">– fps</span>
        <button type="button" id="toggle-preview" aria-pressed="true">Nascondi camera</button>
        <button type="button" id="stop">Spegni camera</button>
      </div>
    </footer>

    <!-- L'unico script della pagina. type="module" permette gli import; in produzione
         Vite lo sostituisce con il file compilato. -->
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

import "./style.css";

/**
 * Scorciatoia per prendere un elemento dall'HTML.
 * Il `as T` è una promessa fatta a TypeScript ("fidati, esiste ed è di questo tipo"):
 * qui è lecita perché gli id sono scritti a mano in index.html e non cambiano.
 */
const $ = <T extends HTMLElement>(id: string) => document.getElementById(id) as T;

/** Tutti i nodi della pagina in un posto solo: se cambia un id, si corregge qui. */
const ui = {
  scene: $<HTMLCanvasElement>("scene"),
  intro: $("intro"),
  start: $<HTMLButtonElement>("start"),
  error: $("error"),
  status: $("status"),
  preview: $("preview"),
  video: $<HTMLVideoElement>("video"),
  overlay: $<HTMLCanvasElement>("overlay"),
  hud: $("hud"),
  gestures: $("gestures"),
  fps: $("fps"),
  togglePreview: $<HTMLButtonElement>("toggle-preview"),
  stop: $<HTMLButtonElement>("stop"),
};

ui.start.addEventListener("click", () => console.log("via!"));

if (!window.isSecureContext || !navigator.mediaDevices?.getUserMedia) {
  throw new CameraError("La camera funziona solo su una pagina HTTPS.");
}

stream = await navigator.mediaDevices.getUserMedia({
  video: {
    facingMode: "user",     // camera frontale sui telefoni
    width: { ideal: 640 },
    height: { ideal: 480 },
  },
  audio: false,             // il microfono non serve: non va nemmeno chiesto
});

/** Errore "previsto", con un messaggio già scritto per l'utente. Lo distingue da un bug vero. */
export class CameraError extends Error {}

const MESSAGES: Record<string, string> = {
  NotAllowedError: "Permesso negato: consenti l'uso della camera dalle impostazioni del browser e riprova.",
  NotFoundError: "Nessuna webcam trovata su questo dispositivo.",
  NotReadableError: "La webcam è occupata da un'altra applicazione.",
  OverconstrainedError: "La webcam non supporta la risoluzione richiesta.",
};

// ...

} catch (e) {
  const name = e instanceof DOMException ? e.name : "";
  throw new CameraError(MESSAGES[name] ?? "Impossibile accendere la camera.");
}

video.srcObject = stream;
await video.play();

// Subito dopo play() le dimensioni possono essere ancora 0. A noi servono, per dare alla
// scena 3D le proporzioni giuste: quindi si aspetta l'evento che le annuncia.
if (video.videoWidth === 0) {
  await new Promise<void>((resolve) =>
    video.addEventListener("loadedmetadata", () => resolve(), { once: true }),
  );
}

export function stopCamera(video: HTMLVideoElement, stream: MediaStream | null): void {
  stream?.getTracks().forEach((t) => t.stop());  // ← questa è la riga che spegne la spia
  video.pause();
  video.srcObject = null;
}

The three precautions almost nobody takes

A "turn off" button is not enough. There are three moments when the camera must turn off on its own, and you only discover them if you think about it on purpose:

// 1. L'utente ha cambiato scheda MENTRE si accendeva la camera: non deve restare accesa.
if (document.hidden) { stop(); return; }

// 2. L'utente cambia scheda a camera accesa.
document.addEventListener("visibilitychange", () => {
  if (document.hidden && stream) stop();
});

// 3. L'utente lascia la pagina: si libera anche il riconoscitore (memoria e contesto grafico).
window.addEventListener("pagehide", () => {
  stop();
  tracker?.close();
  tracker = null;
});

The first case is the one that does not come to mind: between the moment the user grants permission and the moment the stream arrives, hundreds of milliseconds pass, and in that time they may well have moved on to something else.

import { FilesetResolver, GestureRecognizer, type GestureRecognizerResult } from "@mediapipe/tasks-vision";

const WASM_PATH = "/mediapipe/wasm";
const MODEL_PATH = "/mediapipe/gesture_recognizer.task";

// FilesetResolver guarda se il browser supporta le istruzioni SIMD del processore e sceglie
// da solo fra vision_wasm_internal.* e la variante "nosimd". Entrambe devono essere presenti.
const vision = await FilesetResolver.forVisionTasks(WASM_PATH);

const recognizer = await GestureRecognizer.createFromOptions(vision, {
  baseOptions: { modelAssetPath: MODEL_PATH, delegate: "GPU" },
  runningMode: "VIDEO",             // "IMAGE" ripartirebbe da zero a ogni fotogramma
  numHands: 2,
  minHandDetectionConfidence: 0.5,  // per accorgersi che c'è una mano
  minHandPresenceConfidence: 0.5,   // per dire che c'è ancora
  minTrackingConfidence: 0.5,       // per continuare a seguirla senza ricercarla da capo
});

detect(video: HTMLVideoElement, now: number): GestureRecognizerResult {
  // MediaPipe in modalità VIDEO usa l'istante per capire quanto tempo è passato dal
  // fotogramma precedente, e INTERROMPE CON UN ERRORE se riceve un tempo uguale o
  // minore dell'ultimo. Con performance.now() non dovrebbe mai capitare, ma il "+1"
  // di sicurezza costa nulla ed evita un errore fatale dove non te lo aspetti.
  const ts = now > this.lastTimestamp ? now : this.lastTimestamp + 1;
  this.lastTimestamp = ts;

  return this.recognizer.recognizeForVideo(video, ts);
}

{
  landmarks:   [ [ {x,y,z} × 21 ], … ],   // un array per mano vista
  worldLandmarks: [ … ],                  // gli stessi punti in metri, origine al centro della mano
  handedness:  [ [ { categoryName: "Left" | "Right", score } ], … ],
  gestures:    [ [ { categoryName: "Thumb_Up", score } ], … ],
}

/** Il codice ragiona in inglese, l'interfaccia parla italiano. */
export const GESTURE_LABELS: Record<string, string> = {
  Closed_Fist: "✊ Pugno",
  Open_Palm: "🖐️ Mano aperta",
  Pointing_Up: "☝️ Indice in su",
  Thumb_Down: "👎 Pollice giù",
  Thumb_Up: "👍 Pollice su",
  Victory: "✌️ Vittoria",
  ILoveYou: "🤟 Ti voglio bene",
};

static async create(onlyCpu = false): Promise<HandTracker> {
  // `?delegate=cpu` nell'indirizzo forza la CPU: utile per diagnosticare senza toccare il codice.
  const forceCpu = onlyCpu || new URLSearchParams(location.search).get("delegate")?.toLowerCase() === "cpu";
  const vision = await FilesetResolver.forVisionTasks(WASM_PATH);

  const options = (delegate: "GPU" | "CPU") => ({ /* …come sopra… */ });

  if (forceCpu) return new HandTracker(await GestureRecognizer.createFromOptions(vision, options("CPU")), "CPU");
  try {
    return new HandTracker(await GestureRecognizer.createFromOptions(vision, options("GPU")), "GPU");
  } catch {
    // Niente WebGL utilizzabile: la CPU è più lenta ma funziona ovunque,
    // ed è meglio di una pagina che non parte.
    return new HandTracker(await GestureRecognizer.createFromOptions(vision, options("CPU")), "CPU");
  }
}

const t0 = performance.now();
const result = this.recognizer.recognizeForVideo(video, ts);
const ms = performance.now() - t0;

// Media mobile esponenziale: pesa di più le misure recenti e non richiede di tenere
// uno storico. Due variabili invece di un array.
this.detections++;
this.avgDetectMs = this.detections === 1 ? ms : this.avgDetectMs * 0.8 + ms * 0.2;

async function fallbackToCpuIfSlow(): Promise<void> {
  if (!tracker || switching || tracker.delegate !== "GPU" ||
      tracker.detections < 8 || tracker.avgDetectMs < 150) return;

  switching = true;
  const slow = tracker;
  tracker = null;                              // il ciclo salta le rilevazioni finché non è pronto
  try {
    tracker = await HandTracker.create(true);  // true = solo CPU
    slow.close();                              // il vecchio va chiuso: tiene memoria e contesto grafico
    console.info(`GPU troppo lenta (${Math.round(slow.avgDetectMs)} ms): passo alla CPU`);
  } catch {
    tracker = slow;                            // se fallisce, si continua con quello di prima
  } finally {
    switching = false;
  }
}

import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";

// I moduli ES non hanno __dirname: si ricava dall'indirizzo del file stesso.
const root = join(dirname(fileURLToPath(import.meta.url)), "..");
const out = join(root, "public", "mediapipe");

// Le due varianti del runtime: SIMD (più veloce) e nosimd (ripiego). Sceglie MediaPipe
// quale usare, ma deve trovarle entrambe nella cartella.
const WASM_FILES = [
  "vision_wasm_internal.js",
  "vision_wasm_internal.wasm",
  "vision_wasm_nosimd_internal.js",
  "vision_wasm_nosimd_internal.wasm",
];
const wasmSrc = join(root, "node_modules", "@mediapipe", "tasks-vision", "wasm");
mkdirSync(join(out, "wasm"), { recursive: true });
for (const f of WASM_FILES) copyFileSync(join(wasmSrc, f), join(out, "wasm", f));

// Il modello (~8 MB). L'indirizzo punta alla versione "1", non a "latest".
const MODEL = {
  url: "https://storage.googleapis.com/mediapipe-models/gesture_recognizer/gesture_recognizer/float16/1/gesture_recognizer.task",
  file: join(out, "gesture_recognizer.task"),
  sha256: "97952348cf6a6a4915c2ea1496b4b37ebabc50cbbf80571435643c455f2b0482",
};
const sha = (buf) => createHash("sha256").update(buf).digest("hex");

if (!existsSync(MODEL.file) || sha(readFileSync(MODEL.file)) !== MODEL.sha256) {
  const res = await fetch(MODEL.url);
  if (!res.ok) throw new Error(`download del modello fallito: HTTP ${res.status}`);
  const buf = Buffer.from(await res.arrayBuffer());
  // Se il contenuto non è quello atteso la build si ferma: meglio un errore chiaro adesso
  // che un file sbagliato pubblicato sul sito.
  if (sha(buf) !== MODEL.sha256) throw new Error("checksum del modello diverso da quello atteso");
  writeFileSync(MODEL.file, buf);
}

console.log("asset MediaPipe pronti in public/mediapipe/");

"scripts": {
  "assets": "node scripts/prepare-assets.mjs",
  "dev": "npm run assets && vite",
  "build": "npm run assets && tsc && vite build",
  "test:e2e": "node tests/e2e/run.mjs"
}

let rafId = 0;           // id dell'ultimo requestAnimationFrame, per poterlo annullare
let lastVideoTime = -1;  // istante dell'ultimo fotogramma già analizzato

function loop(): void {
  rafId = requestAnimationFrame(loop);   // richiamami prima del prossimo ridisegno
  const video = ui.video;

  // readyState >= 2 significa "ci sono dati per il fotogramma corrente".
  if (tracker && video.readyState >= 2 && video.currentTime !== lastVideoTime) {
    lastVideoTime = video.currentTime;
    const now = performance.now();

    const result = tracker.detect(video, now);   // ← il riconoscimento
    // …qui useremo i punti: filtro, scena 3D, anteprima 2D…
  }

  scene.render();        // ← il disegno, SEMPRE, anche senza fotogrammi nuovi
}

frames++;
if (now - fpsWindowStart >= 1000) {
  ui.fps.textContent = `${Math.round((frames * 1000) / (now - fpsWindowStart))} fps · ${tracker.delegate}`;
  frames = 0;
  fpsWindowStart = now;
}

async function start(): Promise<void> {
  ui.error.hidden = true;
  setState("loading", "Avvio…");
  try {
    // L'ORDINE CONTA: prima il modello (pesante, ~8 MB, ma non chiede niente all'utente),
    // poi la webcam. Così il permesso viene chiesto quando manca poco al via, e non si tiene
    // la telecamera accesa per secondi mentre si scarica il modello.
    // Il `??=` fa sì che alla seconda accensione il modello già in memoria venga riusato.
    tracker ??= await HandTracker.create();
    stream = await startCamera(ui.video);

    if (document.hidden) { stop(); return; }

    // Le proporzioni reali del video decidono l'area utile della scena 3D.
    scene.setFrameAspect(ui.video.videoWidth / ui.video.videoHeight);
    lastVideoTime = -1;
    setState("running", "● Camera accesa");
    cancelAnimationFrame(rafId);   // per sicurezza: mai due cicli in parallelo
    loop();
  } catch (e) {
    stop();
    ui.error.textContent = e instanceof CameraError
      ? e.message
      : `Errore durante l'avvio: ${(e as Error).message ?? e}`;
    ui.error.hidden = false;
    setState("error", "Camera spenta");
  }
}

function stop(): void {
  cancelAnimationFrame(rafId);
  stopCamera(ui.video, stream);
  stream = null;
  scene.update("Right", null);
  scene.update("Left", null);
  streak.Right = streak.Left = 0;
  smoothers.Right = smoothers.Left = null;

  // Il ciclo principale è fermo, ma la dissolvenza della mano dura ancora un decimo di
  // secondo: si continua a disegnare per una ventina di fotogrammi, poi basta.
  let n = 20;
  const fade = () => { scene.render(); if (--n > 0) requestAnimationFrame(fade); };
  fade();

  setState("idle", "Camera spenta");
}

type State = "idle" | "loading" | "running" | "error";

function setState(state: State, status: string): void {
  document.body.dataset.state = state;
  ui.status.textContent = status;
  ui.status.classList.toggle("live", state === "running");
  ui.intro.hidden = state === "running";
  ui.hud.hidden = state !== "running";
  ui.preview.hidden = state !== "running" || ui.togglePreview.getAttribute("aria-pressed") !== "true";
  ui.start.disabled = state === "loading";
  ui.start.textContent = state === "loading" ? "Avvio in corso…" : "Accendi la camera";
}

import { DrawingUtils } from "@mediapipe/tasks-vision";

const overlayCtx = ui.overlay.getContext("2d")!;
const drawing = new DrawingUtils(overlayCtx);

// …dentro il ciclo, per ogni mano trovata:

// La tela ha le dimensioni REALI del video (es. 640×480); il CSS poi la rimpicciolisce.
// Così i punti disegnati coincidono con l'immagine che c'è sotto.
if (ui.overlay.width !== video.videoWidth) {
  ui.overlay.width = video.videoWidth;
  ui.overlay.height = video.videoHeight;
}
overlayCtx.clearRect(0, 0, ui.overlay.width, ui.overlay.height);

drawing.drawConnectors(landmarks, HAND_CONNECTIONS, { color: "#38bdf8", lineWidth: 3 });
drawing.drawLandmarks(landmarks, { color: "#ffffff", radius: 2.5, lineWidth: 1 });

// Riesportata da qui perché la usano sia l'anteprima 2D sia la scena 3D, e nessuna delle
// due deve importare MediaPipe solo per questo.
export const HAND_CONNECTIONS = GestureRecognizer.HAND_CONNECTIONS;

.preview video,
.preview canvas {
  object-fit: cover;
  transform: scaleX(-1);   /* effetto specchio, SOLO visivo */
}

import * as THREE from "three";

// `alpha: true`: lo sfondo lo mette il CSS (una sfumatura), la tela resta trasparente.
const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
// Su schermi ad alta densità si disegna al massimo al doppio della risoluzione: oltre non si
// vede la differenza e si spreca lavoro (e batteria).
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));

const scene = new THREE.Scene();

// fov 35°, aspect provvisorio, piani di taglio vicino/lontano
const camera = new THREE.PerspectiveCamera(35, 1, 0.1, 100);
// Telecamera FERMA davanti all'origine: si muove la mano, non l'inquadratura.
// È ciò che rende immediato l'effetto specchio.
camera.position.set(0, 0, 10);
camera.lookAt(0, 0, 0);

// Tre luci:
scene.add(new THREE.HemisphereLight(0xdbeafe, 0x1e1b4b, 1.4)); // diffusa cielo/terra: niente ombre nere
const key = new THREE.DirectionalLight(0xffffff, 2.2);
key.position.set(3, 5, 8);                                      // principale: dà volume
scene.add(key);
const rim = new THREE.DirectionalLight(0x818cf8, 1.2);
rim.position.set(-4, -2, -6);                                   // radente violacea: stacca dallo sfondo
scene.add(rim);

const DEPTH_GAIN = 1.6;

toWorld(p: Point3): Point3 {
  const width = this.frameAspect * this.frameHeight;
  return {
    x: (0.5 - p.x) * width,               // centra E specchia
    y: (0.5 - p.y) * this.frameHeight,    // centra E rovescia (in 3D la y cresce in alto)
    z: -p.z * width * DEPTH_GAIN,         // verso l'osservatore, un po' esagerata
  };
}

// Due geometrie per TUTTA la scena: una sfera di raggio 1 e un cilindro alto 1.
// Ogni oggetto le riusa cambiando solo posizione, rotazione e scala.
const jointGeo = new THREE.SphereGeometry(1, 20, 14);
const boneGeo = new THREE.CylinderGeometry(1, 1, 1, 14);

// Tre materiali condivisi, non uno per oggetto: cambiare la trasparenza di un materiale
// la cambia per tutti gli oggetti che lo usano — ed è così che funziona la dissolvenza.
this.solid = new THREE.MeshStandardMaterial({ color, roughness: 0.35, metalness: 0.1, transparent: true });
this.tips = new THREE.MeshStandardMaterial({
  color: 0xffffff,
  emissive: color,        // "emette" luce propria: le punte si notano anche in ombra
  emissiveIntensity: 0.9,
  roughness: 0.3,
  transparent: true,
});

for (let i = 0; i < 21; i++) {
  const joint = new THREE.Mesh(jointGeo, FINGERTIPS.has(i) ? this.tips : this.solid);
  this.joints.push(joint);
  this.group.add(joint);
}
for (let i = 0; i < HAND_CONNECTIONS.length; i++) {
  const bone = new THREE.Mesh(boneGeo, this.solid);
  this.bones.push(bone);
  this.group.add(bone);
}

/** Posizioni di lavoro riusate a ogni fotogramma, per non allocare 21 vettori ogni volta. */
private readonly world = Array.from({ length: 21 }, () => new THREE.Vector3());

const up = new THREE.Vector3(0, 1, 0);
const dir = new THREE.Vector3();

HAND_CONNECTIONS.forEach(({ start, end }, i) => {
  const a = this.world[start];
  const b = this.world[end];
  const bone = this.bones[i];

  dir.subVectors(b, a);
  const len = dir.length();

  // 1. POSIZIONE: il punto medio fra A e B
  bone.position.addVectors(a, b).multiplyScalar(0.5);

  // 2. ROTAZIONE: quella che porta l'asse Y (verso naturale del cilindro) sulla direzione A→B.
  //    `divideScalar(len)` normalizza la direzione; il controllo evita la divisione per zero
  //    quando due punti coincidono — cosa che capita nei primi fotogrammi.
  if (len > 1e-6) bone.quaternion.setFromUnitVectors(up, dir.divideScalar(len));

  // 3. SCALA: raggio sui lati, lunghezza del segmento in altezza
  bone.scale.set(boneR, len, boneR);
});

// Distanza polso → nocca del medio: è la "taglia" della mano in questo fotogramma.
const size = this.world[0].distanceTo(this.world[9]);
const jointR = size * 0.075;
const boneR = size * 0.05;

this.joints.forEach((j, i) => {
  j.position.copy(this.world[i]);
  // Polso un po' più grosso, punte leggermente più grandi: dà carattere alla figura.
  j.scale.setScalar(FINGERTIPS.has(i) ? jointR * 1.15 : i === 0 ? jointR * 1.4 : jointR);
});

/** Polso (0), base del pollice (1) e le quattro nocche (5, 9, 13, 17). */
const PALM = [0, 1, 5, 9, 13, 17];

const palmGeo = new THREE.BufferGeometry();
palmGeo.setAttribute("position", new THREE.BufferAttribute(new Float32Array(PALM.length * 3), 3));
// Un ventaglio di triangoli che parte dal polso:
// (polso, pollice, indice), (polso, indice, medio), e così via.
palmGeo.setIndex([0, 1, 2,  0, 2, 3,  0, 3, 4,  0, 4, 5]);

this.palm = new THREE.Mesh(palmGeo, this.palmMaterial);
// I vertici cambiano a ogni fotogramma, ma Three.js calcola il volume d'ingombro una volta
// sola. Senza questa riga, ogni tanto decide che il palmo è fuori inquadratura e lo salta.
this.palm.frustumCulled = false;

// …e a ogni fotogramma si riscrivono i sei vertici nel buffer già allocato:
const pos = this.palm.geometry.getAttribute("position") as THREE.BufferAttribute;
PALM.forEach((idx, k) => pos.setXYZ(k, this.world[idx].x, this.world[idx].y, this.world[idx].z));
pos.needsUpdate = true;                      // senza questo i dati non tornano alla scheda grafica
this.palm.geometry.computeVertexNormals();   // ricalcola l'orientamento per l'illuminazione

tick(dt: number): void {
  // `dt * 12` rende la dissolvenza indipendente dagli fps: circa un decimo di secondo
  // su qualunque macchina, che gira a 30, 60 o 144 Hz.
  this.opacity += (this.targetOpacity - this.opacity) * Math.min(1, dt * 12);
  if (this.opacity < 0.01 && this.targetOpacity === 0) this.opacity = 0;

  // A zero l'oggetto si spegne del tutto: Three.js salta i gruppi non visibili.
  this.group.visible = this.opacity > 0;
  this.solid.opacity = this.opacity;
  this.tips.opacity = this.opacity;
  this.palmMaterial.opacity = this.opacity * 0.35;   // il palmo resta comunque velato
}

private resize(): void {
  const w = this.canvas.clientWidth || window.innerWidth;
  const h = this.canvas.clientHeight || window.innerHeight;
  this.renderer.setSize(w, h, false);   // false = non toccare la dimensione CSS
  this.camera.aspect = w / h;
  this.camera.updateProjectionMatrix(); // OBBLIGATORIO dopo aver cambiato aspect o fov

  // Quanto mondo entra in verticale alla distanza della mano.
  const visibleH = 2 * this.camera.position.z * Math.tan(THREE.MathUtils.degToRad(this.camera.fov / 2));
  // Si sceglie il lato che "stringe" di più, così il rettangolo del video entra sempre tutto.
  const fit = this.camera.aspect > this.frameAspect ? visibleH : (visibleH * this.camera.aspect) / this.frameAspect;

  // Telefono in verticale: senza ingrandimento la mano sarebbe minuscola fra due bande vuote.
  // Si accetta che vicino ai bordi laterali possa uscire dall'inquadratura.
  const zoom = Math.min(1.4, Math.max(1, this.frameAspect / this.camera.aspect));
  this.frameHeight = fit * 0.92 * zoom;  // 0.92 = un margine perché la mano non tocchi i bordi
}

/**
 * Filtro passa-basso elementare: `y = α·x + (1-α)·y_precedente`.
 * Con α vicino a 1 segue fedelmente il valore; vicino a 0 lo insegue lentamente.
 */
class LowPass {
  private y: number | null = null;

  filter(x: number, alpha: number): number {
    this.y = this.y === null ? x : alpha * x + (1 - alpha) * this.y;
    return this.y;
  }

  last(): number | null {
    return this.y;
  }
}

/**
 * Converte una "frequenza di taglio" in hertz nel coefficiente α del passa-basso, tenendo
 * conto di quanto tempo è passato DAVVERO fra due fotogrammi: così il filtro si comporta
 * allo stesso modo a 30 o a 60 fotogrammi al secondo.
 */
const alpha = (cutoff: number, dt: number) => 1 / (1 + 1 / (2 * Math.PI * cutoff * dt));

export class OneEuroFilter {
  private x = new LowPass();   // filtra il valore
  private dx = new LowPass();  // filtra la sua velocità
  private lastTime: number | null = null;

  constructor(minCutoff = 1.2, beta = 8, dCutoff = 1) { /* … */ }

  filter(value: number, timeMs: number): number {
    const prev = this.x.last();

    // Tempo trascorso in secondi. Al primo giro si ipotizzano 30 fps; il minimo di 1 ms
    // evita una divisione per zero se arrivassero due misure con lo stesso istante.
    const dt = this.lastTime === null ? 1 / 30 : Math.max((timeMs - this.lastTime) / 1000, 1e-3);
    this.lastTime = timeMs;

    // Velocità stimata del punto (unità al secondo), a sua volta filtrata perché
    // altrimenti salterebbe come il dato grezzo da cui è calcolata.
    const derivative = prev === null ? 0 : (value - prev) / dt;
    const edx = this.dx.filter(derivative, alpha(this.dCutoff, dt));

    // ← IL CUORE DEL METODO: la soglia di filtro cresce con la velocità.
    const cutoff = this.minCutoff + this.beta * Math.abs(edx);
    return this.x.filter(value, alpha(cutoff, dt));
  }
}

/**
 * Ogni coordinata ha il proprio filtro indipendente: 21 punti × 3 assi = 63 filtri,
 * ognuno con due numeri di stato. Costa niente e mantiene il codice banale.
 */
export class LandmarkSmoother {
  private filters = Array.from({ length: 21 * 3 }, () => new OneEuroFilter());

  smooth(points: { x: number; y: number; z: number }[], timeMs: number) {
    return points.map((p, i) => ({
      x: this.filters[i * 3].filter(p.x, timeMs),
      y: this.filters[i * 3 + 1].filter(p.y, timeMs),
      z: this.filters[i * 3 + 2].filter(p.z, timeMs),
    }));
  }
}

const CONFIRM_FRAMES = 3;
const streak: Record<Side, number> = { Right: 0, Left: 0 };

result.landmarks.forEach((landmarks, i) => {
  let side = realSide(result.handedness[i]?.[0]?.categoryName);
  // Se MediaPipe attribuisce lo stesso lato a entrambe le mani (succede raramente), la
  // seconda finisce nell'altro contenitore: meglio un'etichetta sbagliata che una mano
  // che sparisce.
  if (seen.has(side)) side = side === "Right" ? "Left" : "Right";
  seen.add(side);
  streak[side]++;

  // Il filtro lavora ANCHE durante i fotogrammi di conferma, così quando la mano appare
  // è già stabile invece di assestarsi sotto gli occhi di chi guarda.
  smoothers[side] ??= new LandmarkSmoother();
  const smoothed = smoothers[side]!.smooth(landmarks, now);
  if (streak[side] < CONFIRM_FRAMES) return;   // non ancora confermata: niente da disegnare

  scene.update(side, smoothed);
  // …
});

// Le mani non viste in questo fotogramma svaniscono e i loro contatori si azzerano.
for (const side of ["Right", "Left"] as Side[]) {
  if (!seen.has(side)) {
    streak[side] = 0;
    scene.update(side, null);
    smoothers[side] = null;
  }
}

/**
 * MediaPipe decide destra/sinistra dando per scontato che l'immagine sia GIÀ SPECCHIATA,
 * come in una videochiamata. Il fotogramma grezzo della webcam però non lo è, quindi la
 * sua etichetta va ribaltata.
 */
function realSide(label: string | undefined): Side {
  return label === "Left" ? "Right" : "Left";
}

// 1) la mano 3D, con i punti ADDOLCITI dal filtro
scene.update(side, smoothed);

// 2) l'anteprima 2D, con i punti GREZZI: lì serve la corrispondenza esatta con l'immagine
drawing.drawConnectors(landmarks, HAND_CONNECTIONS, { color: side === "Right" ? "#38bdf8" : "#f472b6", lineWidth: 3 });
drawing.drawLandmarks(landmarks, { color: "#ffffff", radius: 2.5, lineWidth: 1 });

import { createReadStream, statSync } from "node:fs";
import { createServer } from "node:http";
import { extname, join, normalize, resolve } from "node:path";

const ROOT = resolve(process.env.ROOT ?? "app/dist");
const PORT = +(process.env.PORT ?? 8791);
/** Solo interfaccia locale: nessuno può raggiungere questo processo scavalcando il proxy. */
const HOST = process.env.HOST ?? "127.0.0.1";

/**
 * Il tipo dichiarato per ogni estensione. Non è un dettaglio: il file .wasm deve arrivare
 * come `application/wasm`, altrimenti il browser si rifiuta di compilarlo al volo e
 * MediaPipe non parte affatto.
 */
const TYPES = {
  ".html": "text/html; charset=utf-8",
  ".js": "text/javascript; charset=utf-8",
  ".css": "text/css; charset=utf-8",
  ".svg": "image/svg+xml",
  ".wasm": "application/wasm",
  ".task": "application/octet-stream",   // il modello dei gesti
};

const server = createServer((req, res) => {
  const url = new URL(req.url ?? "/", "http://localhost");

  // SICUREZZA: si ricostruisce il percorso assoluto e si pretende che stia dentro ROOT.
  // `normalize` risolve i "..", il controllo blocca i tentativi tipo /../../etc/passwd.
  // È l'unico punto davvero delicato di questo file.
  let path = resolve(join(ROOT, normalize(decodeURIComponent(url.pathname))));
  if (path !== ROOT && !path.startsWith(ROOT + "/")) {
    res.writeHead(403).end("Forbidden");
    return;
  }

  let info;
  try {
    info = statSync(path);
    if (info.isDirectory()) { path = join(path, "index.html"); info = statSync(path); }
  } catch {
    res.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("Non trovato");
    return;
  }

  // ETag da dimensione e data: se il browser ha già il file identico rispondiamo 304 e
  // non rispediamo 11 MB di WebAssembly a ogni ricarica.
  const etag = `"${info.size.toString(16)}-${info.mtimeMs.toString(16)}"`;
  if (req.headers["if-none-match"] === etag) { res.writeHead(304).end(); return; }

  res.writeHead(200, {
    "content-type": TYPES[extname(path)] ?? "application/octet-stream",
    "content-length": info.size,
    etag,
    // I file in assets/ hanno l'impronta del contenuto nel nome: se cambiano, cambia il
    // nome, quindi si possono tenere in cache per sempre.
    "cache-control": path.includes("/assets/") ? "public, max-age=31536000, immutable" : "public, max-age=300",
  });

  createReadStream(path).pipe(res);   // a pezzi: nessun file grande tenuto in memoria
});

server.listen(PORT, HOST);

mano.esempio.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8791

    header {
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Referrer-Policy no-referrer
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        -Server

        # La camera solo per questa origine; microfono e geolocalizzazione per nessuno.
        Permissions-Policy "camera=(self), microphone=(), geolocation=()"

        Content-Security-Policy "default-src 'none'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self'; img-src 'self' data: blob:; media-src 'self' blob:; connect-src 'self'; worker-src 'self' blob:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
    }

    # Nessun dato personale transita dal server, ma non serve nemmeno tenere log degli accessi.
    log {
        output discard
    }
}

function disableMediapipeTelemetry(): Plugin {
  const pattern = "flush(t,e){if(this.error)";
  return {
    name: "disable-mediapipe-telemetry",
    enforce: "pre",   // prima degli altri plugin: il codice dev'essere ancora l'originale
    transform(code, id) {
      if (!id.includes("@mediapipe/tasks-vision/vision_bundle")) return null;
      if (!code.includes(pattern)) {
        // Se un aggiornamento cambia quella stringa, la build si FERMA con un messaggio
        // chiaro, invece di lasciar passare in silenzio la telemetria riaccesa. È voluto.
        this.error("telemetria MediaPipe: pattern non trovato, ricontrollare la patch");
      }
      // `this.h=[]` svuota la coda dei messaggi, `t?.()` avvisa il chiamante che è andata bene.
      // Dopo la sostituzione il minificatore si accorge che il resto della funzione è
      // irraggiungibile e cancella anche l'indirizzo.
      return { code: code.replace(pattern, "flush(t,e){this.h=[];t?.();return;if(this.error)"), map: null };
    },
  };
}

export default defineConfig({
  plugins: [disableMediapipeTelemetry()],
  // Di norma Vite pre-impacchetta le dipendenze prima di servirle in sviluppo, e in quella
  // fase i plugin di trasformazione non passano. Escludendo MediaPipe, la patch vale anche
  // con `npm run dev`.
  optimizeDeps: { exclude: ["@mediapipe/tasks-vision"] },
  build: { chunkSizeWarningLimit: 900 },
});

// Si riusa il frammento di configurazione DI PRODUZIONE cambiando due sole cose: il nome
// del sito diventa localhost su HTTP (niente certificati nel test). Tutte le intestazioni
// restano identiche: è il punto di questo test.
const snippet = readFileSync(join(app, "../deploy/Caddyfile.snippet"), "utf8")
  .replace(/^mano\.esempio\.com \{/m, `http://localhost:${PORT} {`);

writeFileSync(join(cache, "Caddyfile"), `{\n    admin off\n}\n${snippet}`);
const caddy = spawn("caddy", ["run", "--adapter", "caddyfile", "--config", join(cache, "Caddyfile")]);

const E2E = new URLSearchParams(location.search).has("e2e");

// …dentro il ciclo:
if (E2E) {
  document.body.dataset.hands = String(shown.length);
  document.body.dataset.sides = shown.join(",");
  document.body.dataset.gestures = shownGestures.join(",");
  document.body.dataset.wrist = result.landmarks[0] ? result.landmarks[0][0].x.toFixed(3) : "";
}

const external = [];  // richieste verso domini diversi da localhost: devono restare zero

page.on("request", (r) => {
  const u = new URL(r.url());
  if (u.protocol.startsWith("http") && u.hostname !== "localhost") external.push(r.url());
});

// …alla fine:
check(external.length === 0, `nessuna richiesta esterna (trovate: ${external.length})`);