La capa de comentarios, paso a paso.

Necesitas Node ≥ 22 y pnpm. Perfect Front corre en tu máquina; no hay cuenta ni nube.

1. Clona el repositorio y entra en la carpeta.
2. Instala dependencias y construye.
3. Desde la raíz de tu proyecto (no la de Perfect Front) ejecuta perfect-front o su alias comment.

# una sola vez
git clone https://github.com/jorgeguzmanq/perfect-front.git
cd perfect-front
pnpm install
pnpm build

# cada día, en la carpeta de TU proyecto
perfect-front

El comando detecta tu proyecto, arranca tu dev server, levanta el servidor local y un proxy (por defecto en 127.0.0.1:7788) que reenvía tu app e inyecta la capa. Abre el navegador en la URL del proxy y se queda vivo en primer plano: Ctrl+C apaga todo lo que inició.

Si la carpeta solo tiene .html y ningún runner, Perfect Front la sirve con su propio servidor estático (usa index.html, o te pide elegir la página).

Opciones

Subcomandos

La capa viene activa pero en reposo: un clic normal no se intercepta y tu app funciona igual.

• Alt + clic sobre un elemento: abre el comentario de ese elemento.
• Ctrl/Cmd + ⇧ + C: alterna el modo selección; ahí el clic normal comenta. Esc sale.
• También puedes usar el botón Comentar del lanzador (esquina inferior derecha).

Estados

Mientras guardas, el campo se bloquea y el botón muestra «Guardando…». Si el servidor local no responde, tu texto se conserva y puedes pulsar Reintentar. Si intentas guardar vacío, el campo se marca con un error.

Primero decides a qué te refieres. Un comentario puede apuntar a un elemento, a varios o a toda la vista.

Navegar por el DOM v2

Con el elemento elegido, afina sin volver a hacer clic:

• ↑ sube al padre; ↓ baja al primer hijo.
• ← / → van al hermano anterior o siguiente.
• Los botones se apagan cuando no hay a dónde ir (por ejemplo, el primer hermano no tiene ←).

Selección múltiple v2

⇧ + clic suma o quita elementos (o el botón Sumar del panel). Todos viajan en un solo comentario. Aparece una bandeja con un chip por elemento; el chip con borde de acento es el foco. Las flechas mueven solo el foco. En Estilos puedes aplicar «Solo el foco» o «Los N elementos».

Con Toda la vista el comentario no apunta a ningún elemento (sirve para «la página se siente apretada»).

Reordenar hermanos v2

En la pestaña Estructura mueves un elemento entre sus hermanos con «Mover antes» / «Mover después». Es una propuesta: se previsualiza en la página, viaja con el comentario y se puede Deshacer. El código no cambia.

Copiar ubicación v2

El botón de copiar de la cabecera del panel abre «Copiar como»:

«Archivo:línea» necesita que el elemento lleve data-pf-src (plugin de build, aún no existe); sin él se copian los demás formatos.

Aquí dices qué debería cambiar. El comentario de texto está disponible hoy; las pestañas del panel completo son v2.

Comentario de texto Disponible

1. Escribe qué habría que cambiar (hasta 10 000 caracteres).
2. Pulsa Guardar o Ctrl+↵.

Contenido e i18n v2

La pestaña Contenido edita el texto del elemento y lo pinta en la página mientras escribes; Cancelar lo deshace. Hay tres casos:

Si no escribes comentario, se genera uno automático del tipo «Cambiar texto de … a …» (regla descrita en el diseño; no verificada en código).

Estilos: editable vs. foundation v2

La pestaña Estilos separa lo que puedes cambiar de lo que solo se consulta:

Cada cambio muestra «antes → después» y se ve en vista previa en vivo; Revertir (por fila o todo) o cerrar el panel la deshace. Si una propiedad usa un token, se indica «usa --token».

Imágenes v2

• Pegar: Ctrl+V con el panel abierto.
• Soltar: arrastra archivos sobre la zona de imágenes («Suelta para adjuntar»).
• Abrir: botón «Abrir…».
• Hasta 20 adjuntos por comentario. Formatos: PNG, JPEG y WebP (el esquema compartido no admite GIF aunque el prototipo lo muestre); hasta 5 MB cada una.
• Se copian a .perfect-front/attachments/ y el JSON guarda rutas relativas al proyecto.

Captura de nodo v2

Una capa propia enmarca el nodo y lo renderiza de nuevo a 1×, 2×, 3× o 4× (no agranda una imagen).

1. En el panel: Capturar ▾ → Nodo seleccionado, o Alt+⇧+S.
2. Marca las escalas que quieras. Cada una muestra su tamaño real en px antes de capturar.
3. Con varios nodos elige por separado o juntos.
4. Pulsa Capturar. Si el nodo está fuera de pantalla, la página se desplaza sola; el overlay se oculta durante la captura y no hay parpadeo. No muevas la página mientras dura.
5. Revisa el resultado: Adjuntar, Copiar, Descargar o Capturar de nuevo.

Una escala se apaga (con el motivo a la vista) si el resultado pasa de 16 384 px por lado, de 100 M px en total, o de 5 MB tras renderizar. Elige una menor o captura solo una parte.

Copiar y descargar

• Copiar al portapapeles: copia la imagen como PNG, lista para pegar en un chat o documento.
• Descargar: guarda pf-<selector>-<escala>x.png; Descargar todas baja cada escala.
• Requisitos: contexto seguro (localhost o 127.0.0.1) y la página enfocada. Si el navegador rechaza copiar, usa Descargar.

Para decir «esto sobra» sin escribir nada: el botón Eliminar elemento del panel guarda un comentario con el texto «Eliminar este elemento.», con una nota opcional que explique por qué.

Grupos y cola de lectura

En la pestaña Cola atas el comentario a un grupo: varios comentarios que se entienden juntos, en orden y con contexto. Opciones: Grupo nuevo, Añadir a un grupo, Atar a un comentario… (se coloca justo después del elegido) y Sacar del grupo.

• Nota de contexto: un texto que explica el objetivo del grupo.
• Entender el grupo antes de actuar: quien ejecute lee la nota y toda la cola, en orden, antes de tocar nada.
• Con grupo, Guardar pasa a Guardar en la cola. Cada ítem muestra su estado (Pendiente, En curso, Resuelto).

Cajón de comentarios

Desde el menú del lanzador (Más opciones → Comentarios) se abre el cajón, aparte del editor: pestañas Abiertos, Grupos y Resueltos. Al hacer clic en un ítem vas a su pin. En un grupo, Copiar como brief arma un resumen para pegar.

Pines

Cada comentario deja un pin numerado sobre el elemento: azul si está abierto, verde si está resuelto, otro color si pertenece a un grupo. El conteo aparece en el lanzador.

El dashboard del servidor local lista tus proyectos y comentarios. Para trabajar sin navegador ni servidor, el CLI opera directo sobre .perfect-front/ y no modifica nunca tu código: tú (o tu agente) cambias el código y luego registras la resolución.

<id> acepta el ID completo (pf_ + 26 caracteres) o un prefijo único. Con --json, stdout trae un único objeto JSON: {"ok":true,…} o {"ok":false,"error":{"code","message"}}. Para no pisar cambios ajenos usa --expect-updated-at <iso> (alias --rev).

Flujo recomendado

perfect-front list --json
perfect-front claim <id>
perfect-front show <id> --json
# cambia el código y verifica (build, lint, tests)
perfect-front resolve <id> --summary "qué cambió y por qué" \
  --files src/a.tsx --verification "pnpm build ok" --by agent

Para localizar el elemento, en orden de confianza: ruta, texto, selectores, HTML y, si hay, la captura. Si no lo localizas con confianza, no lo resuelvas: anota el resultado parcial con edit (conservando el texto original) y deja in_progress o pending.

Códigos de salida

Bloque para tu CLAUDE.md / AGENTS.md

Pégalo en el archivo de instrucciones del proyecto para que tu agente sepa cómo trabajar. El contrato completo está en packages/cli/AGENTS.md del repositorio.

## Comentarios visuales (Perfect Front)

Para aplicar comentarios visuales: ejecuta `perfect-front list --json` (solo pendientes;
`--status in_progress|all` para otros). Por cada comentario: `perfect-front claim <id>`,
luego `perfect-front show <id> --json` y localiza el elemento por `location.route`,
`location.text`, `selector`/`selectorCandidates` y `location.html` (si hay `attachments`,
mira la captura). Cambia el codigo, verifica (build/lint/tests) y registra con
`perfect-front resolve <id> --summary "..." --files a,b --verification "..." --by agent`.
Si no localizas el elemento con confianza, NO lo resuelvas: anota el resultado parcial con
`perfect-front edit <id> --comment "..."` (conservando el texto original) y deja el
estado en `in_progress` o `pending`.
Usa `--expect-updated-at <iso>` para no pisar cambios ajenos. Codigos de salida: 0 ok,
2 uso, 3 sin proyecto, 6 id no encontrado, 7 conflicto/revision obsoleta, 8 datos.
Contrato completo: packages/cli/AGENTS.md del repo perfect-front.

Dónde se guarda

Todo vive dentro de tu proyecto, en .perfect-front/. Un comentario = un archivo JSON.

"id": "pf_01K7A…", "status": "pending", "scope": "element",
"comment": "El título se corta en móvil.",
"location": { "route": "/planes", "selector": "main > div.card", … },
"viewport": { … }, "attachments": [ … ], "resolution": null

Los archivos v1 siguen siendo legibles; la v2 añade sections[], extraTargets[], proposals[] y group.

Privacidad

Sin nube. El servidor local y el proxy escuchan solo en 127.0.0.1; no se envía nada a terceros. Puedes versionar .perfect-front/ en Git o ignorarlo, según prefieras.

Límites conocidos

• El proxy solo reenvía destinos HTTP; con HTTPS no hay capa (se avisa en la terminal).
• La app se sirve desde otro origen (127.0.0.1:<puerto del proxy>): localStorage, cookies y orígenes permitidos quedan separados. Si dependes de ellos, usa --no-proxy.
• HTML comprimido pese a quitar accept-encoding, o en UTF-16, no se inyecta.
• Máximo 20 adjuntos y 5 MB por imagen; reordenar, estilos y contenido son propuestas, nunca cambian el código.
• La v2 todavía es un prototipo de diseño: algunas piezas descritas aquí aún no tienen código en la rama principal.

Solución de problemas