CÓMO
FUNCIONA
ESTO.

01 / Vista de pájaro

FRAMR es una app 100% cliente. No hay backend, no hay base de datos, no hay subida a ningún servidor. Todo el procesamiento de imágenes ocurre en el browser usando la Canvas API.

El flujo es simple:

1. El usuario sube una imagen (drag-drop o file picker).
2. El browser la carga en un HTMLImageElement y guarda sus dimensiones.
3. Para cada uno de los 23 presets de plataformas, se renderiza un preview interactivo.
4. El usuario reposiciona/zoomea cada frame con drag + scroll/slider.
5. Cuando descarga, se vuelca a un <canvas> del tamaño exacto del preset, se convierte a WebP con canvas.toBlob(), y se gatilla un download.
6. El ZIP se arma con JSZip en el browser, también sin red.

02 / Mapa de archivos

La app es chica, pero todo tiene su lugar:

Reglas que mantengo en este árbol:

• Componentes en components/, lógica pura en lib/, páginas en app/. Sin utils.ts cajón de sastre.
• Cada componente tiene su .module.css al lado. Sin Tailwind. Cada clase queda scopeada por archivo.
• Nada en lib/ importa de components/. Solo en una dirección.

03 / Catálogo de plataformas

Las medidas de cada red social viven hardcodeadas en lib/platforms.ts. Son datos estáticos, oficiales 2026, conseguidos de help centers y blogs de referencia (Buffer, Hootsuite, etc.).

export type Preset = {
  id: string;          // "ig_feed_portrait", único
  label: string;       // "Feed Portrait"
  width: number;       // 1080
  height: number;      // 1350
  ratio: string;       // "4:5" (info, no se usa en cálculo)
  minWidth: number;    // 320 (mínimo recomendado por la plataforma)
};

export type Platform = {
  id: string;          // "instagram"
  name: string;        // "Instagram"
  color: string;       // "#E4405F" (legacy, hoy se override en CSS)
  presets: Preset[];
};

Hay 6 plataformas con un total de 23 presets. Algunos ejemplos:

El archivo también exporta dos helpers chiquitos:

export function getCoverScale(imgW, imgH, presetW, presetH) {
  return Math.max(presetW / imgW, presetH / imgH);
}

export function meetsRequirement(imgW, imgH, preset) {
  return imgW >= preset.width && imgH >= preset.height;
}

getCoverScale dice cuánto hay que agrandar la imagen para que cubra completamente un preset. Si da > 1, hay que upscalear (y se pixela). Es la base del warning ⚠ +N%.

04 / El modelo de transform

Esta es la pieza más importante de todo el proyecto. Acá viven las matemáticas que hacen que el crop sea coherente entre lo que se ve en pantalla y lo que se descarga.

El problema

Necesitamos representar "cómo está cropeada la imagen en este preset" con un objeto chico, que sea independiente de las dimensiones del preview. ¿Por qué? Porque el preview se ve a 240px de display, pero el export se hace a 1080×1920 o 2560×1440. La misma "configuración de crop" tiene que servir para ambos.

La solución: 3 números

export type Transform = {
  zoom: number;  // >= 1, multiplicador encima del "cover fit"
  cx: number;    // 0..1, posición horizontal del centro en coords de imagen
  cy: number;    // 0..1, posición vertical del centro en coords de imagen
};

El truco mental:

• zoom = 1 significa "la imagen cubre el frame exacto" (cover-fit).
• zoom = 2 significa "el doble de grande" → vemos menos imagen pero con más detalle.
• cx = 0.5, cy = 0.5 es el centro de la imagen apuntando al centro del frame.
• cx = 0.2 es "estoy mirando el 20% horizontal de la imagen", o sea que el foco se corre a la izquierda.

05 / computeFrame(), paso a paso

Esta función toma un transform abstracto y un tamaño de frame, y devuelve los valores concretos en píxeles para renderizar.

export function computeFrame(
  imgW, imgH, frameW, frameH, t
) {
  // 1. La escala mínima que asegura cover (que la imagen cubra todo el frame).
  const base = Math.max(frameW / imgW, frameH / imgH);

  // 2. La escala efectiva incluye el zoom del usuario.
  const scale = base * t.zoom;
  const renderedW = imgW * scale;
  const renderedH = imgH * scale;

  // 3. Calculamos tx, ty para que (cx, cy) caiga en el centro del frame.
  let tx = frameW / 2 - t.cx * renderedW;
  let ty = frameH / 2 - t.cy * renderedH;

  // 4. Clamp: la imagen nunca puede dejar un borde vacío.
  const minTx = frameW - renderedW;  // más negativo posible
  const minTy = frameH - renderedH;
  if (tx > 0) tx = 0;
  if (ty > 0) ty = 0;
  if (tx < minTx) tx = minTx;
  if (ty < minTy) ty = minTy;

  return { scale, renderedW, renderedH, tx, ty };
}

Ejemplo con números reales

Imagen 2400×1600, preset 1080×1920 (vertical 9:16), zoom 1, cx 0.5, cy 0.5:

1. base = max(1080/2400, 1920/1600) = max(0.45, 1.2) = 1.2: la imagen tiene que crecer 20% para cubrir vertical.
2. scale = 1.2 * 1 = 1.2
3. renderedW = 2400 * 1.2 = 2880, renderedH = 1600 * 1.2 = 1920 (justito).
4. tx = 1080/2 - 0.5 * 2880 = 540 - 1440 = -900 (la imagen se mueve a la izquierda).
5. ty = 1920/2 - 0.5 * 1920 = 960 - 960 = 0.
6. El clamp: minTx = 1080 - 2880 = -1800. -900 está entre -1800 y 0, OK.

Resultado: la imagen se dibuja a tamaño 2880×1920, desplazada 900px a la izquierda, mostrando los 1080 píxeles del centro horizontal y los 1920 verticales. Cover perfecto.

El gemelo: clampedTransform()

Cuando el usuario arrastra o cambia el zoom, el cx/cy resultante puede caer fuera del rango válido (intentando ver más allá del borde). En vez de dejarlo y clampear solo en el render, ajustamos el cx/cy mismos antes de guardar el state. Eso mantiene los valores consistentes.

06 / Estado del page

Toda la app es un solo componente React (app/page.tsx) con tres bits de estado:

const [loaded, setLoaded] = useState<LoadedImage | null>(null);
const [transforms, setTransforms] = useState<Record<string, Transform>>({});
const [zipping, setZipping] = useState<string | null>(null);

• loaded: la imagen ya cargada como HTMLImageElement + su nombre. Null cuando todavía no se subió nada.
• transforms: un objeto keyed by preset id. Cada preset que el usuario tocó tiene su propio transform; los que no, usan DEFAULT_TRANSFORM ({ zoom: 1, cx: 0.5, cy: 0.5 }).
• zipping: string con qué se está zippeando ("all", "instagram", etc.) o null. Sirve para deshabilitar otros botones mientras corre.

07 / Uploader

El componente más simple de la app, pero con un par de detalles de a11y.

Estructura

Un <div> con role="button" y tabIndex={0} que actúa como dropzone Y como trigger del file picker:

<div
  role="button"
  tabIndex={0}
  onDragOver={onDragOver}
  onDragLeave={onDragLeave}
  onDrop={onDrop}
  onClick={openPicker}
  onKeyDown={(e) => {
    if (e.key === "Enter" || e.key === " ") openPicker();
  }}
>
  <input type="file" ref={inputRef} hidden />
  <h1>DROP. AN. IMAGE.</h1>
  {/* ... */}
</div>

Validación

Cuando llega un archivo, hacemos un check minimal:

if (!file.type.startsWith("image/")) {
  setError("THAT'S NOT AN IMAGE.");
  return;
}

No hay validaciones de tamaño máximo ni nada parecido. Siempre se pueden agregar más validaciones después según necesidad (un check de file.size, formatos específicos, lo que haga falta).

08 / PresetCard: el componente jugoso

Acá está casi todo el código interactivo. Es el responsable de mostrar el preview de un preset y permitir crop + download.

Anatomía

<article>                              <!-- card entero, a11y: aria-labelledby -->
  <header>                             <!-- label del preset + dimensiones target -->
    <h3>Feed Portrait</h3>
    <span>1080×1350</span>
  </header>
  <div>                                <!-- frame con overflow:hidden + drag handlers -->
    <img />                            <!-- imagen real, posicionada con transform -->
    <div>skeleton shimmer</div>        <!-- 400ms inicial -->
    <span>⚠ +28%</span>                <!-- badge si necesita upscale -->
    <span>↔ DRAG · ⇕ ZOOM</span>       <!-- hint en hover -->
  </div>
  <div>                                <!-- controles: slider de zoom + reset -->
    <input type="range" />
    <button>RESET</button>
  </div>
  <button>↓ GIMME .WEBP</button>
</article>

El frame muestra el preview a tamaño chico (MAX_DISPLAY = 240px en la dimensión más larga), pero matemáticamente representa el mismo crop que el canvas de export.

09 / Pan: cómo se arrastra

El drag usa Pointer Events (no mouse events). Pointer events funcionan unificados para mouse + touch + pen, y soportan setPointerCapture() que es clave.

El flow

// onPointerDown
(e) => {
  e.target.setPointerCapture(e.pointerId);  // el target retiene los eventos
  dragRef.current = {
    startX: e.clientX, startY: e.clientY,
    startCx: transform.cx, startCy: transform.cy,
    scale: math.scale,  // la escala efectiva actual
  };
};

// onPointerMove
(e) => {
  const d = dragRef.current;
  if (!d) return;
  const dx = e.clientX - d.startX;
  const dy = e.clientY - d.startY;
  // Convertimos delta en píxeles a delta en coords normalizadas de imagen.
  const cx = d.startCx - dx / (imgW * d.scale);
  const cy = d.startCy - dy / (imgH * d.scale);
  onTransformChange(clampedTransform(/* ... */, { zoom, cx, cy }));
};

// onPointerUp
() => { dragRef.current = null; };

10 / Zoom: wheel + slider

Dos formas de hacer zoom en cada frame.

Slider HTML

Un <input type="range" min={1} max={4} step={0.01}>. Trivial. Tiene un <label htmlFor> visualmente oculto pero asociado para screen readers.

Wheel listener nativo (no React)

Acá hay un truco. React por default registra los listeners de onWheel como passive, lo que significa que e.preventDefault() no funciona y el scroll de la página se sigue moviendo. Para evitarlo, registramos el listener vía useEffect con { passive: false } directamente al DOM:

useEffect(() => {
  const el = frameRef.current;
  if (!el) return;
  const handler = (e) => {
    e.preventDefault();   // gracias al passive: false
    const delta = -e.deltaY * 0.002;
    const zoom = transform.zoom * (1 + delta);
    onTransformChange(clampedTransform(/* ... */, { zoom, cx, cy }));
  };
  el.addEventListener("wheel", handler, { passive: false });
  return () => el.removeEventListener("wheel", handler);
}, [/* deps */]);

11 / Skeleton + fade: UX deliberada

Cuando se carga una imagen nueva, cada PresetCard muestra 400ms de skeleton (rayitas diagonales animadas) y después la imagen aparece con un fade de 320ms.

const [skeleton, setSkeleton] = useState(true);

useEffect(() => {
  setSkeleton(true);                                // reset al cargar una imagen nueva
  const id = setTimeout(() => setSkeleton(false), 400);
  return () => clearTimeout(id);
}, [image.src]);

El fade usa CSS transition en opacity. El skeleton es un background: repeating-linear-gradient con animación @keyframes shimmer que desplaza el patrón a 0.8s/loop.

12 / El check de upscale (warning)

Cuando una imagen es más chica que el preset, no la bloqueamos, la dejamos descargable pero con un warning visual.

const coverScale = getCoverScale(imgW, imgH, preset.width, preset.height);
const upscalePct = Math.round((coverScale - 1) * 100);
const fits = coverScale <= 1;

Si coverScale > 1, la imagen necesita ser agrandada para cubrir el preset. Se ve pixelada. Mostramos:

• Un badge magenta en la esquina del frame: ⚠ +28%.
• El botón download cambia a magenta y dice ↓ GIMME (UPSCALED +28%).
• Igual se puede descargar. El user decide.

13 / Export a WebP

La función central que convierte un transform en un Blob WebP:

export async function renderPresetToBlob(image, preset, transform) {
  const canvas = document.createElement("canvas");
  canvas.width = preset.width;        // canvas al tamaño exacto del preset
  canvas.height = preset.height;
  const ctx = canvas.getContext("2d");
  ctx.imageSmoothingEnabled = true;
  ctx.imageSmoothingQuality = "high"; // mejor remuestreo disponible

  const m = computeFrame(
    image.naturalWidth, image.naturalHeight,
    preset.width, preset.height,
    transform,
  );
  ctx.drawImage(image, m.tx, m.ty, m.renderedW, m.renderedH);

  return new Promise((resolve) =>
    canvas.toBlob((b) => resolve(b), "image/webp", 0.92),
  );
}

La clave: computeFrame() se llama con las dimensiones del canvas, no del preview. La misma función produce los valores correctos para cualquier escala, por eso lo que se ve chiquito en pantalla es exactamente lo que termina en el WebP.

El download

export function triggerDownload(blob, filename) {
  const url = URL.createObjectURL(blob);
  const a = document.createElement("a");
  a.href = url;
  a.download = filename;
  document.body.appendChild(a);
  a.click();
  a.remove();
  URL.revokeObjectURL(url);   // liberar memoria
}

14 / ZIPs en el browser

Usamos JSZip (única dependencia que no viene con Next.js). Genera ZIPs en memoria sin tocar disco.

export async function buildZip(image, imageName, presets, transforms) {
  const zip = new JSZip();
  for (const preset of presets) {
    const blob = await renderPresetToBlob(
      image, preset,
      transforms[preset.id] ?? DEFAULT_TRANSFORM,
    );
    if (blob) zip.file(fileNameFor(imageName, preset), blob);
  }
  return zip.generateAsync({ type: "blob" });
}

Hay tres puntos de entrada a buildZip:

• ZIP ALL (23): botón cyan al lado de SWAP, manda todos los presets.
• DOWNLOAD SET: un botón por plataforma en su banda, solo manda los presets de esa plataforma.
• Single .webp: el botón ↓ GIMME de cada card, no usa ZIP, hace un download directo.

15 / Brutalismo aplicado

Toda la estética sigue 7 reglas, listadas también en /ui-kit:

1. Esquinas afiladas. Cero border-radius.
2. Bordes negros de 3px en todo lo que tenga frontera.
3. Hover hace thunk: translate(-2px, -2px) + box-shadow: 4px 4px 0 color. Sin blur.
4. Copy en mayúscula, confrontacional. Punto final como signo.
5. Paleta saturada (amarillo, magenta, cyan, rojo). Nunca pastel.
6. Brand colors oficiales (con minimal darkening en YT y FB para WCAG).
7. Warning no es blocker. Mostrá el costo, dejá decidir.

Tokens

Definidos en globals.css con CSS custom props:

:root {
  --paper: #ffffff;
  --ink: #000000;
  --yellow: #fff200;     /* acción primaria */
  --magenta: #ff0066;    /* warnings, upscale */
  --cyan: #00e0ff;       /* acción secundaria (ZIP ALL) */
  --red: #ff2200;
  --lime: #c4ff00;       /* reserva (no se usa) */

  --line-w: 3px;

  --font-display: "Space Grotesk", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", ui-monospace, monospace;
}

16 / A11y: qué se hizo y por qué

Lighthouse a11y score: 100/100 en / y en /ui-kit. Lista de qué se cubrió:

17 / Decisiones y trade-offs

Client-side only

+ Privacidad real (no se sube nada).
+ Cero costo operativo.
+ Funciona offline después de la primera carga.
−Sin posibilidad de smart-crop con ML (requeriría server o WASM gordo).
−Imágenes muy grandes pueden saturar RAM mobile.

WebP q=92 fijo

+ Sweet spot calidad/tamaño.
−No le da control al usuario sobre el nivel de compresión.

Cover crop only (no contain, no stretch)

+ El output siempre cubre el frame exacto. No hay "padding" raro.
−Si la imagen no llega al ratio del preset, partes se pierden. Es por diseño.

Transform por preset (vs. uno global)

+ Permite enfocar la cara para Instagram y el horizonte para YouTube banner.
−Más state que mantener, pero está acotado al objeto transforms.

Skeleton + fade artificiales

+ Sensación percibida de procesamiento.
−Suma 400ms de espera real. En contextos low-latency podríamos darle un toggle.

ZIP secuencial

+ No revienta memoria en mobile.
−Algo más lento que en paralelo. Aceptable para 23 presets.

No backend

+ Deploy a static hosting (Vercel free, Netlify, GitHub Pages).
−No analytics ni telemetría sin meter algo aparte.

Brutalismo

+ Memorable, anti-template, fuerte identidad.
−Polariza. No es para todo público, pero ese era el punto.