add-puzzle-type

Add Puzzle Type

Scaffold a new puzzle type across all pipeline integration points in jigsawR.

When to Use

• Adding a completely new puzzle type to the package
• Following the established integration checklist (CLAUDE.md 10-point pipeline)
• Ensuring nothing is missed when wiring a new type end-to-end

Inputs

• Required: New type name (lowercase, e.g. "triangular")
• Required: Geometry description (how pieces are shaped/arranged)
• Required: Whether the type needs external packages (add to Suggests)
• Optional: Parameter list beyond the standard (grid, size, seed, tabsize, offset)
• Optional: Reference implementation or algorithm source

Procedure

Step 1: Create Core Puzzle Module

Create R/<type>_puzzle.R with the internal generation function:

#' 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
}

Follow the pattern in R/voronoi_puzzle.R or R/snic_puzzle.R for structure.

Got: Function returns a list with $pieces, $edges, $adjacency, $metadata.

If fail: Compare the return structure against generate_voronoi_pieces_internal() to identify missing list elements or incorrect types.

Step 2: Wire into jigsawR_clean.R

Edit R/jigsawR_clean.R:

1. Add "<type>" to the valid_types vector
2. Add type-specific parameter extraction in the params section
3. Add validation logic for type-specific constraints
4. Add filename prefix mapping (e.g., "<type>" -> "<type>_")

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

Got: generate_puzzle(type = "<type>") is accepted without "unknown type" error.

If fail: Verify the type string is added to valid_types exactly as spelled, and that parameter extraction covers all required type-specific arguments.