---

name: add-puzzle-type description: > Crear la estructura para un nuevo tipo de rompecabezas en los mas de 10 puntos de integracion del pipeline en jigsawR. Crea el modulo central del rompecabezas, lo conecta al pipeline unificado (generacion, posicionamiento, renderizado, adyacencia), agrega capas geom/stat de ggpuzzle, actualiza DESCRIPTION y config.yml, extiende la aplicacion Shiny y crea una suite de pruebas completa. Usar al agregar un tipo de rompecabezas completamente nuevo al paquete o al seguir la lista de verificacion de integracion de 10 puntos para asegurar que nada se omita de principio a fin. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: jigsawr complexity: advanced language: R tags: jigsawr, puzzle-type, pipeline, integration, scaffold locale: es source_locale: en source_commit: 6f65f316 translator: claude-sonnet-4-6 translation_date: 2026-03-16

Agregar Tipo de Rompecabezas

Crear la estructura para un nuevo tipo de rompecabezas en todos los puntos de integracion del pipeline en jigsawR.

Cuando Usar

• Agregar un tipo de rompecabezas completamente nuevo al paquete
• Seguir la lista de verificacion de integracion establecida (pipeline de 10 puntos de CLAUDE.md)
• Asegurar que nada se omita al conectar un nuevo tipo de principio a fin

Entradas

• Requerido: Nombre del nuevo tipo (minusculas, ej. "triangular")
• Requerido: Descripcion de la geometria (como se forman/organizan las piezas)
• Requerido: Si el tipo necesita paquetes externos (agregar a Suggests)
• Opcional: Lista de parametros mas alla de los estandar (grid, size, seed, tabsize, offset)
• Opcional: Implementacion de referencia o fuente del algoritmo

Procedimiento

Paso 1: Crear Modulo Central del Rompecabezas

Crear R/<type>_puzzle.R con la funcion interna de generacion:

#' Generate <type> puzzle pieces (internal)
#' @noRd
generate_<type>_pieces_internal <- function(params, seed) {
  # 1. Initialize RNG state
  # 2. Generate piece geometries
  # 3. Build edge paths (SVG path data)
  # 4. Compute adjacency
  # 5. Return list: pieces, edges, adjacency, metadata
}

Seguir el patron en R/voronoi_puzzle.R o R/snic_puzzle.R para la estructura.

Esperado: La funcion retorna una lista con $pieces, $edges, $adjacency, $metadata.

En caso de fallo: Comparar la estructura de retorno contra generate_voronoi_pieces_internal() para identificar elementos de lista faltantes o tipos incorrectos.

Paso 2: Conectar en jigsawR_clean.R

Editar R/jigsawR_clean.R:

1. Agregar "<type>" al vector valid_types
2. Agregar extraccion de parametros especificos del tipo en la seccion de parametros
3. Agregar logica de validacion para restricciones especificas del tipo
4. Agregar mapeo de prefijo de nombre de archivo (ej., "<type>" -> "<type>_")

# In valid_types
valid_types <- c("rectangular", "hexagonal", "concentric", "voronoi", "snic", "<type>")

Esperado: generate_puzzle(type = "<type>") es aceptado sin error de "tipo desconocido".

En caso de fallo: Verificar que la cadena del tipo se agrego a valid_types exactamente como se escribe, y que la extraccion de parametros cubre todos los argumentos requeridos especificos del tipo.

Paso 3: Conectar en unified_piece_generation.R

Editar R/unified_piece_generation.R:

1. Agregar caso de despacho en generate_pieces_internal()
2. Agregar manejo de fusion si el tipo soporta notacion PILES

# In the switch/dispatch
"<type>" = generate_<type>_pieces_internal(params, seed)

Esperado: Las piezas se generan cuando se despacha el tipo.

En caso de fallo: Confirmar que la cadena del caso de despacho coincide exactamente con el nombre del tipo y que generate_<type>_pieces_internal esta definida y exportada desde el modulo del rompecabezas.

Paso 4: Conectar en piece_positioning.R

Editar R/piece_positioning.R:

Agregar despacho de posicionamiento para el nuevo tipo. La mayoria de los tipos usan logica de posicionamiento compartida, pero algunos necesitan manejo personalizado.

Esperado: apply_piece_positioning() maneja el nuevo tipo sin errores y las piezas se colocan en las coordenadas correctas.

En caso de fallo: Verificar si el nuevo tipo necesita logica de posicionamiento personalizada o puede reutilizar la ruta de posicionamiento compartida. Agregar un caso de despacho si la ruta predeterminada no aplica.

Paso 5: Conectar en unified_renderer.R

Editar R/unified_renderer.R:

1. Agregar caso de renderizado en render_puzzle_svg()
2. Agregar funcion de ruta de bordes: get_<type>_edge_paths()
3. Agregar funcion de nombre de pieza: get_<type>_piece_name()

Esperado: Se genera salida SVG para el nuevo tipo con contornos de piezas y rutas de bordes correctos.

En caso de fallo: Verificar que get_<type>_edge_paths() retorna datos de ruta SVG validos y get_<type>_piece_name() produce identificadores unicos para cada pieza.

Paso 6: Conectar en adjacency_api.R

Editar R/adjacency_api.R:

Agregar despacho de vecinos para que get_neighbors() y get_adjacency() funcionen para el nuevo tipo.

Esperado: get_neighbors(result, piece_id) retorna los vecinos correctos para cualquier pieza del rompecabezas.

En caso de fallo: Verificar que el despacho de adyacencia retorna la estructura de datos correcta. Probar con una cuadricula pequena y verificar manualmente las relaciones de vecindad contra la geometria.

Paso 7: Agregar Capa Geom de ggpuzzle

Editar R/geom_puzzle.R:

Crear geom_puzzle_<type>() usando la fabrica make_puzzle_layer():

#' @export
geom_puzzle_<type> <- function(mapping = NULL, data = NULL, ...) {
  make_puzzle_layer(type = "<type>", mapping = mapping, data = data, ...)
}

Esperado: ggplot() + geom_puzzle_<type>(aes(...)) se renderiza sin error.

En caso de fallo: Verificar que make_puzzle_layer() recibe la cadena de tipo correcta y que la funcion geom esta exportada en el NAMESPACE via @export.

Paso 8: Agregar Despacho Stat

Editar R/stat_puzzle.R:

1. Agregar parametros predeterminados especificos del tipo
2. Agregar caso de despacho en compute_panel()

Esperado: La capa stat calcula la geometria del rompecabezas correctamente y produce el numero esperado de poligonos.

En caso de fallo: Verificar que el caso de despacho de compute_panel() retorna un data frame con las columnas requeridas (x, y, group, piece_id) y que los parametros predeterminados son razonables para el nuevo tipo.

Paso 9: Actualizar DESCRIPTION

Editar DESCRIPTION:

1. Agregar el nuevo tipo al texto del campo Description
2. Agregar nuevos paquetes a Suggests: (si es dependencia externa)
3. Actualizar Collate: para incluir el nuevo archivo R (orden alfabetico)

Esperado: devtools::document() tiene exito. Sin NOTE sobre archivos no listados.

En caso de fallo: Verificar que el nuevo archivo R esta listado en el campo Collate: en orden alfabetico y que cualquier nuevo paquete en Suggests esta escrito correctamente con restricciones de version.

Paso 10: Actualizar config.yml

Editar inst/config.yml:

Agregar valores predeterminados y restricciones para el nuevo tipo:

<type>:
  grid:
    default: [3, 3]
    min: [2, 2]
    max: [20, 20]
  size:
    default: [300, 300]
    min: [100, 100]
    max: [2000, 2000]
  tabsize:
    default: 20
    min: 5
    max: 50
  # Add type-specific params here

Esperado: La configuracion es YAML valido. Los valores predeterminados producen un rompecabezas funcional cuando son usados por generate_puzzle().

En caso de fallo: Validar YAML con yaml::yaml.load_file("inst/config.yml"). Asegurar que los valores predeterminados de grid y size producen un rompecabezas razonable (ni demasiado pequeno ni demasiado grande).

Paso 11: Extender la Aplicacion Shiny

Editar inst/shiny-app/app.R:

1. Agregar el nuevo tipo al selector de tipo en la UI
2. Agregar paneles UI condicionales para parametros especificos del tipo
3. Agregar logica de generacion del lado del servidor

Esperado: La aplicacion Shiny muestra el nuevo tipo en el desplegable y genera rompecabezas cuando se selecciona.

En caso de fallo: Verificar que el tipo se agrego al argumento choices del selector UI, que el panel condicional para parametros especificos del tipo usa conditionalPanel(condition = "input.type == '<type>'"), y que el manejador del servidor pasa los parametros correctos.

Paso 12: Crear Suite de Pruebas

Crear tests/testthat/test-<type>-puzzles.R:

test_that("<type> puzzle generates correct piece count", { ... })
test_that("<type> puzzle respects seed reproducibility", { ... })
test_that("<type> adjacency returns valid neighbors", { ... })
test_that("<type> fusion merges pieces correctly", { ... })
test_that("<type> geom layer renders without error", { ... })
test_that("<type> SVG output is well-formed", { ... })
test_that("<type> config constraints are enforced", { ... })

Si el tipo requiere un paquete externo, envolver las pruebas con skip_if_not_installed().

Esperado: Todas las pruebas pasan. Sin omisiones a menos que falte una dependencia externa.

En caso de fallo: Verificar cada punto de integracion individualmente. El problema mas comun es la falta de casos de despacho -- ejecutar grep -rn "switch\|valid_types" R/ para encontrar todas las ubicaciones de despacho.

Validacion

• generate_puzzle(type = "<type>") produce salida valida
• Los 10 puntos de integracion estan conectados correctamente
• devtools::test() pasa con las nuevas pruebas
• devtools::check() retorna 0 errores, 0 advertencias
• La aplicacion Shiny renderiza el nuevo tipo
• Las restricciones de configuracion se aplican (validacion min/max)
• La adyacencia y fusion funcionan correctamente
• La capa geom de ggpuzzle se renderiza sin error
• devtools::document() tiene exito (NAMESPACE actualizado)

Errores Comunes

• Caso de despacho faltante: Olvidar uno de los mas de 10 archivos causa fallo silencioso o errores de "tipo desconocido"
• strsplit con numeros negativos: Al crear claves de adyacencia con paste(a, b, sep = "-"), las etiquetas de pieza negativas producen claves como "1--1". Usar separador "|" y dividir con "\\|".
• Usar cat() para salida: Siempre usar envoltorios de registro del paquete cli (log_info, log_warn, etc.)
• Orden de Collate: El campo Collate de DESCRIPTION debe estar en orden alfabetico o por dependencias
• Formato de Config.yml: Asegurar que el YAML es valido; probar con yaml::yaml.load_file("inst/config.yml")

Habilidades Relacionadas

• generate-puzzle -- probar el nuevo tipo despues de crearlo
• run-puzzle-tests -- ejecutar la suite completa de pruebas para verificar la integracion
• validate-piles-notation -- probar fusion con el nuevo tipo
• write-testthat-tests -- patrones generales de escritura de pruebas
• write-roxygen-docs -- documentar la nueva funcion geom