TouchForge

Biblioteca de TypeScript que combina deteccion de gestos de mano (MediaPipe, en un Web Worker) con un motor de particulas en Canvas 2D. Todo corre en el navegador: el video nunca sale de la maquina del usuario.

No es una aplicacion. demo/ es una demostracion que consume la biblioteca exactamente como lo haria cualquier consumidor externo: importando desde los dos mostradores publicos, nunca desde rutas internas.

Que se puede hacer con las manos

| Gesto | Efecto | |------------------------------------|-------------------------------| | Indice derecho | De ahi salen las particulas | | Pulgar + medio, mano derecha | Perfil FUEGO | | Pulgar + anular, mano derecha | Perfil NIEVE | | Pulgar + menique, mano derecha | Perfil CHISPAS | | Puno izquierdo | Atrae las particulas | | Palma izquierda | Las repele | | Paz izquierda, o barra espaciadora | Prende y apaga el emisor | | Teclas 1 / 2 / 3 | Fuego / nieve / chispas |

En la demo, ?fps=1 en la URL enciende el contador de cuadros por segundo.

Estructura por capas

src/
  index.ts                 mostrador publico: core + particles, sin React
  core/                    TypeScript puro
    camera/                prender y apagar streams
    detection/             MediaPipe en un Worker, con backpressure
    gestures/              measureOpenness, measurePinch, measurePeace, stepGesture
    mapping/               smoothPoint y conversion de coordenadas
    time/                  delta de cuadro
    types/                 tipos compartidos
  particles/               TypeScript puro
    engine/                fisica, pool, fuerzas, emision
    profiles/              ParticleProfile y presets
    renderers/             Canvas 2D
  adapters/
    react/                 hooks; unico lugar donde React esta permitido
demo/                      aplicacion de demostracion

Regla de dependencias

Las dependencias van solo hacia adentro:

demo  ->  adapters  ->  core / particles

• core/ y particles/ son TypeScript puro y nunca importan React, ni siquiera como tipo.
• core/ nunca importa de adapters/ ni de demo/.
• React vive unicamente en src/adapters/react/ y en demo/.

Dos mostradores

// El motor. TypeScript puro, sin React.
import { createParticlePool, emitInto, measurePinch, updateParticles } from 'touchforge'

// El adaptador de React, entrada aparte para no arrastrar React al que no lo usa.
import { CameraView, useCamera, useHandDetector } from 'touchforge/react'

react y react-dom quedan fuera del bundle de la biblioteca: los provee la aplicacion que la consume.

Comandos

npm.cmd run dev          # levanta la demo en localhost:5173
npm.cmd run test         # los tests una vez
npm.cmd run test:watch   # tests en modo watch
npm.cmd run lint         # oxlint
npm.cmd run build        # demo -> dist/    (base /touchforge/, para Pages)
npm.cmd run build:lib    # biblioteca -> dist-lib/ (ESM + .d.ts)
npm.cmd run preview      # sirve dist/ como lo serviria Pages

En Windows va npm.cmd, no npm: PowerShell bloquea la ejecucion de los .ps1 de los shims.

Deploy

La demo se publica en GitHub Pages desde .github/workflows/deploy.yml en cada push a master. El base de Vite es /touchforge/ en el build y / en desarrollo; sin eso el Worker de deteccion resuelve contra la raiz del dominio y da 404.

Requisitos

• Node >= 20.19 o >= 22.12 (lo exige Vite 8)
• Un navegador con WebGL y camara. La camara solo funciona sobre https o localhost: por IP de red local el navegador ni siquiera ofrece pedirla.

Estado

Fase 4. El paquete todavia no esta publicado en npm.

Licencia

MIT. Ver LICENSE.