Paper Game Generator Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Upgrade the Schulte grid tool into a front-end paper game generator with an A4 block layout engine, clickable layout slots, Schulte blocks, S-sized 9x9 sudoku blocks, and M-sized harder maze blocks.

Architecture: Add PaperGameLayoutLogic.js for mm-based A4 block layout and PaperGameGenerators.js for game data generation. Replace the page component with PaperGameTool.vue, which converts layout coordinates to Canvas pixels and renders each block type into PNG pages.

Tech Stack: VuePress 1, Vue 2 single-file component, browser Canvas, CommonJS logic modules, Node assert tests.

---

Task 1: A4 Layout Engine

Files:

• Create: scripts/test_paper_game_layout_logic.js

• Create: docs/.vuepress/components/PaperGameLayoutLogic.js

• [ ] Step 1: Write failing layout tests

Test default A4 config, block presets, 6 schulte_number S components fitting on one page, maze_easy + sudoku_9x9 fitting on one page, sudoku_6x6 + 3 schulte_letter paginating, and invalid spans throwing.

• [ ] Step 2: Run layout test to verify it fails

Run: node scripts/test_paper_game_layout_logic.js Expected: FAIL because PaperGameLayoutLogic.js does not exist.

• [ ] Step 3: Implement layout logic

Create default config, block presets, game block presets, component factory, first-fit top-down layout, coordinate conversion, and validation.

• [ ] Step 4: Run layout test to verify it passes

Run: node scripts/test_paper_game_layout_logic.js Expected: PASS.

Task 1B: Slot Layout Revisions

Files:

• Modify: scripts/test_paper_game_layout_logic.js

• Modify: scripts/test_paper_game_generators.js

• Modify: docs/.vuepress/components/PaperGameLayoutLogic.js

• Modify: docs/.vuepress/components/PaperGameGenerators.js

• [ ] Step 1: Write failing revision tests

Update layout tests so sudoku_9x9 uses S, maze_easy uses M, and the default slot components fit one page as S S / S S / M. Update generator tests so the default maze is larger than the original 13x9 and template games come from slot definitions.

• [ ] Step 2: Run tests to verify they fail

Run:

node scripts/test_paper_game_layout_logic.js
node scripts/test_paper_game_generators.js

Expected: FAIL because current presets still use sudoku M, maze L, and old templates.

• [ ] Step 3: Implement revised presets and slot helpers

Change GAME_BLOCK_PRESETS.sudoku_9x9 to S and maze_easy to M. Add slot helper data and createGamesFromSlots(slots, options) in PaperGameGenerators.js. Increase default maze dimensions.

• [ ] Step 4: Run tests to verify they pass

Run:

node scripts/test_paper_game_layout_logic.js
node scripts/test_paper_game_generators.js

Expected: PASS.

Task 1C: Free Layout and Size Controls

Files:

• Modify: scripts/test_paper_game_layout_logic.js

• Modify: scripts/test_paper_game_generators.js

• Modify: scripts/test_schulte_grid_wiring.js

• Modify: docs/.vuepress/components/PaperGameLayoutLogic.js

• Modify: docs/.vuepress/components/PaperGameGenerators.js

• Modify: docs/.vuepress/components/PaperGameTool.vue

• [ ] Step 1: Write failing revision tests

Update tests so user-composed layouts can preserve slot order and place the default M maze at the bottom. Add generator coverage for maze size options, sudoku size validation, a no-maze schulte_focus shortcut, and a three-maze focus template. Update wiring tests for Schulte/Maze/Sudoku size controls and add/remove slot controls.

• [ ] Step 2: Run tests to verify they fail

Run:

node scripts/test_paper_game_layout_logic.js
node scripts/test_paper_game_generators.js
node scripts/test_schulte_grid_wiring.js

Expected: FAIL because the existing layout engine sorts by area, generator does not accept size controls, and the component has fixed 4S+1M slots.

• [ ] Step 3: Implement free layout and size controls

Add preserveOrder to the layout engine. Add maze size presets and sudoku size validation to the generator. Update the component with separate Schulte/Maze/Sudoku selectors, add/remove S/M slot buttons, a no-maze schulte_focus shortcut, and slot-order rendering.

• [ ] Step 4: Run tests to verify they pass

Run:

node scripts/test_paper_game_layout_logic.js
node scripts/test_paper_game_generators.js
node scripts/test_schulte_grid_wiring.js

Expected: PASS.

Task 1D: Difficulty Controls and 9x9 Sudoku

Files:

• Modify: scripts/test_paper_game_layout_logic.js

• Modify: scripts/test_paper_game_generators.js

• Modify: scripts/test_schulte_grid_wiring.js

• Modify: docs/.vuepress/components/PaperGameLayoutLogic.js

• Modify: docs/.vuepress/components/PaperGameGenerators.js

• Modify: docs/.vuepress/components/PaperGameTool.vue

• [ ] Step 1: Write failing revision tests

Update tests so sudoku_9x9 uses an S block, the generator creates a 9x9 puzzle with difficulty-controlled blank counts, maze uses difficulty semantics, and the component says 迷宫难度 / 数独难度 instead of size/spec copy.

• [ ] Step 2: Run tests to verify they fail

Run:

node scripts/test_paper_game_layout_logic.js
node scripts/test_paper_game_generators.js
node scripts/test_schulte_grid_wiring.js

Expected: FAIL because sudoku_9x9 and difficulty controls are not implemented yet.

• [ ] Step 3: Implement 9x9 sudoku and difficulty controls

Add GAME_BLOCK_PRESETS.sudoku_9x9 = S. Add a 9x9 sudoku generator with easy, medium, and hard blank counts. Change maze control names to difficulty while keeping the same size mapping. Update Vue UI labels, slot options, defaults, drawing function, and options passed to the generator.

• [ ] Step 4: Run tests to verify they pass

Run:

node scripts/test_paper_game_layout_logic.js
node scripts/test_paper_game_generators.js
node scripts/test_schulte_grid_wiring.js

Expected: PASS.

Task 1E: Maze Difficulty Expansion and Rendering

Files:

• Modify: scripts/test_paper_game_generators.js

• Modify: scripts/test_schulte_grid_wiring.js

• Modify: docs/.vuepress/components/PaperGameGenerators.js

• Modify: docs/.vuepress/components/PaperGameTool.vue

• [ ] Step 1: Write failing revision tests

Update generator tests so the default maze is 29x19, the maze title is 迷宫, and difficulty options include entry, easy, medium, hard, and challenge sizes through 41x27. Update wiring tests so the UI includes 挑战 41x27, does not include 简单迷宫, and uses compact block rendering for maze.

• [ ] Step 2: Run tests to verify they fail

Run:

node scripts/test_paper_game_generators.js
node scripts/test_schulte_grid_wiring.js

Expected: FAIL because the generator still exposes three maze sizes, default 23x15, and the UI still labels it 简单迷宫.

• [ ] Step 3: Implement maze difficulty and compact rendering

Expand maze difficulty mapping to 19x13, 23x15, 29x19, 35x23, and 41x27. Change the user-facing label and title to 迷宫. Add compact frame options for maze blocks so the maze uses a smaller header and padding, filling more of the M block.

• [ ] Step 4: Run tests to verify they pass

Run:

node scripts/test_paper_game_generators.js
node scripts/test_schulte_grid_wiring.js

Expected: PASS.

Task 2: Game Generators

Files:

• Create: scripts/test_paper_game_generators.js

• Create: docs/.vuepress/components/PaperGameGenerators.js

• Modify: docs/.vuepress/components/SchulteGridLogic.js

• [ ] Step 1: Write failing generator tests

Test Schulte number and letter component creation, 9x9 sudoku structure and blanks, simple maze dimensions, start/finish, and path reachability.

• [ ] Step 2: Run generator test to verify it fails

Run: node scripts/test_paper_game_generators.js Expected: FAIL because PaperGameGenerators.js does not exist.

• [ ] Step 3: Implement generator logic

Use SchulteGridLogic.js for Schulte sequences. Add 9x9 sudoku puzzle generation with a valid solved grid and blanks. Add simple maze generation with guaranteed path.

• [ ] Step 4: Run generator test to verify it passes

Run: node scripts/test_paper_game_generators.js Expected: PASS.

Task 3: Vue Component and Wiring

Files:

• Create: docs/.vuepress/components/PaperGameTool.vue

• Modify: docs/07.工具/40.舒尔特方格生成器.md

• Modify: docs/.vuepress/config.ts

• Modify: docs/07.工具/00.概览.md

• Modify: scripts/test_schulte_grid_wiring.js

• [ ] Step 1: Write failing wiring tests

Update wiring test to expect page title “纸面游戏生成器”, <PaperGameTool />, Tools nav text “Paper Games”, overview text “纸面游戏生成器”, layout controls, shortcut options, and no backend calls.

• [ ] Step 2: Run wiring test to verify it fails

Run: node scripts/test_schulte_grid_wiring.js Expected: FAIL because the page still uses SchulteGridTool.

• [ ] Step 3: Implement component and page wiring

Create PaperGameTool.vue with clickable S/M layout slots, slot type selectors, shortcut template buttons, refresh, multi-page PNG preview, and download links. Update page, nav, and overview.

• [ ] Step 4: Run wiring test to verify it passes

Run: node scripts/test_schulte_grid_wiring.js Expected: PASS.

Task 4: Full Verification and Commit

Files:

• All files touched above.

• [ ] Step 1: Run node tests

Run:

node scripts/test_paper_game_layout_logic.js
node scripts/test_paper_game_generators.js
node scripts/test_schulte_grid_logic.js
node scripts/test_schulte_grid_wiring.js

Expected: all commands exit 0.

• [ ] Step 2: Run VuePress build

Run: npm run build Expected: build exits 0.

• [ ] Step 3: Review diff

Run: git status --short, git diff --check, and git diff --stat. Expected: only source, test, spec, and plan files are changed; no generated docs/.vuepress/dist or temporary bundled config files are committed.

• [ ] Step 4: Commit

Run:

git add docs/.vuepress/components/PaperGameLayoutLogic.js docs/.vuepress/components/PaperGameGenerators.js docs/.vuepress/components/PaperGameTool.vue docs/.vuepress/components/SchulteGridLogic.js docs/07.工具/40.舒尔特方格生成器.md docs/07.工具/00.概览.md docs/.vuepress/config.ts scripts/test_paper_game_layout_logic.js scripts/test_paper_game_generators.js scripts/test_schulte_grid_logic.js scripts/test_schulte_grid_wiring.js docs/superpowers/specs/2026-04-07-schulte-grid-design.md docs/superpowers/plans/2026-04-07-schulte-grid.md
git commit -m "feat: add paper game layout generator"