Headbreaker.js — “max pieces count was not specified” when using renderPuzzle() in Next.js with imported puzzle state

[chakradharreddy82]

I’m using Next.js (App Router, React 18) and trying to load a saved Headbreaker puzzle state using Puzzle.import() and then renderPuzzle().
The puzzle renders correctly when autogenerated, but whenever I restore the saved state, I get this error:

importing puzzle state: Error: max pieces count was not specified

Here is the relevant part of my Next.js client component:

"use client";

import { useEffect, useRef } from "react";

declare global {
interface Window {
headbreaker: any;
}
}

const STORAGE_KEY = "validated_puzzle_dump";

export default function SoundPuzzleWithResume() {
const containerRef = useRef<HTMLDivElement | null>(null);

useEffect(() => {
const ensureHeadbreaker = () =>
new Promise((resolve, reject) => {
if (window.headbreaker) return resolve();
const script = document.createElement("script");
script.src = "https://flbulgarelli.github.io/headbreaker/js/headbreaker.js";
script.onload = () => resolve();
script.onerror = (e) => reject(e);
document.body.appendChild(script);
});

const horizontalPiecesCount = 6;
const verticalPiecesCount = 5;
const totalPiecesCount = horizontalPiecesCount * verticalPiecesCount;

const init = async () => {
  await ensureHeadbreaker();
  if (!containerRef.current) return;

  const headbreaker = window.headbreaker;

  const validated = new headbreaker.Canvas("sound-canvas", {
    width: 800,
    height: 650,
    pieceSize: 100,
    proximity: 20,
    borderFill: 10,
    strokeWidth: 1.5,
    lineSoftness: 0.18,
    image: img,
    strokeColor: "black",
    fixed: true,
  });

  const savedDumpString = window.localStorage.getItem(STORAGE_KEY);

  if (savedDumpString) {
    const wrappedDump = JSON.parse(savedDumpString);

    const imported = headbreaker.Puzzle.import(wrappedDump.puzzle, {
      maxPiecesCount: wrappedDump.maxPiecesCount, // <-- passed here
    });

    validated.clear();
    validated.renderPuzzle(imported); // <-- error happens here
    validated.draw();
  } else {
    validated.autogenerate({
      horizontalPiecesCount,
      verticalPiecesCount,
      insertsGenerator: headbreaker.generators.random,
    });
    validated.draw();
  }
};

init();

}, []);

return <div ref={containerRef} id="sound-canvas" style={{ width: 800, height: 650 }} />;
}

The saved dump looks like this:

{
"maxPiecesCount": 30,
"puzzle": { ... }
}

But when I pass this to:

headbreaker.Puzzle.import(wrappedDump.puzzle, {
maxPiecesCount: wrappedDump.maxPiecesCount
});

And then call:

validated.renderPuzzle(imported);

I always get:

Error: max pieces count was not specified

❓ What I need help with

Why does Puzzle.import() accept maxPiecesCount, but renderPuzzle() still thinks it is missing?

Is there a known issue with Headbreaker.js restoring puzzle state in Next.js / React?

Does the imported puzzle object require additional fields (like pieces, rows, columns, etc.) that the exported/compacted dump doesn’t include?

What is the correct way to restore a puzzle and call renderPuzzle() without triggering the “max pieces count was not specified” error?

[flbulgarelli]

Hi!

Puzzle.import should not take a second argument, just the puzzle dump. Was that specified somewhere in the docs? Unless there is something I'm missing, your second argument is just being discarded.

That said, how did you generate the JSON dump of the puzzle? This error might indicate a bug in the import method, but I would like to better understand the full picture first.

[flbulgarelli]

{
"maxPiecesCount": 30,
"puzzle": { ... }
}

At first glance, this dump doesn't look right, since there are no maxPiecesCount nor puzzle keys in the default puzzle export result (please have a look at the export button here https://flbulgarelli.github.io/headbreaker/#persistent).