Dalla webcam a una mano animata sullo schermo

<!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;
}

// 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;
});

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})`);