Assembly challenge: rebuild an engine from its parts with hints and an explanation of each connection

[PouyanJay]

The separation slider takes an engine apart and puts it back together for you. The most effective way to learn an assembly is to do it yourself. An assembly challenge starts with the pieces spread out and asks the user to rebuild the engine, with hints and an explanation of each connection.

What is needed

A game-like mode where the user assembles an engine from its component groups:

• Start with the engine separated (component groups, not every individual piece) and a checklist of what has to go back.
• The user picks a group and places it. Placement snaps when the group is close to its home pose and shows a short explanation of what it connects to and why it goes there.
• Order matters where it matters: the crankshaft before the pistons, the rotor before the side housings. The mode explains the reason when the user tries something out of order.
• Hints on request: highlight the home location, then show a ghost, then place it automatically.
• A completion screen with time, hints used, and the option to try the same engine with individual pieces for a harder round.

Success criteria

• All seven engines have a challenge with a defined placement order and one explanation per group.
• Snapping tolerance is forgiving on touch and precise enough that a wrong slot never snaps.
• Every group's home pose after completion equals its captured home matrix; the engine check asserts the final state is identical to Assembled mode.
• The mode is fully usable by keyboard: select from the checklist, move with arrows, place with enter.
• Progress for the current engine survives a reload.
• Copy is plain language with no em dashes or en dashes.
• Works on a phone in portrait orientation.

Suggested approach

• Build on the direct manipulation work in Drag individual pieces out of the assembly, inspect them, and snap them back #3. The challenge is that feature plus a rule set, so land Drag individual pieces out of the assembly, inspect them, and snap them back #3 first.
• Define each challenge as data in lib/engine/: { order: PartId[][], explanations: Record<PartId, string>, dependencies: Record<PartId, PartId[]> }, where each inner array of order is a set of groups that may be placed in any order among themselves.
• Reuse the inventory layout from explosion-layout.ts for the starting spread, but at group level: treat each component group as one piece with the group's combined bounds.
• Snapping: when a dragged group's centre comes within a distance proportional to its bounding radius of its home, and its orientation is within a set angle, animate it home using the return animation from the drag feature and mark it placed.
• Ghost hints can use the same overlay group as the drag feature's home ghosts.
• Keep the checklist in the left panel where the component list is now, so the interface does not grow a new region.
• Store progress in local storage keyed by engine and difficulty.

Out of scope

Scores shared between users, timers that penalise, and multi-player.

Touchpoints

lib/engine/explosion-controller.ts, lib/engine/explosion-layout.ts, app/page.tsx, components/engine/engine-scene.tsx, scripts/check-explosion.mjs