# Puzzle Maker Pro Online (WordPress plugin)

Publishes interactive puzzle catalogs exported by Puzzle Maker Pro.
One `pmp_catalog` post = one exported batch; rendering is done by the
hosted React puzzle engine (`Web/PuzzleEngine`, served from
`https://puzzleengine.bookpublishertools.com/v1/`).

## Flow

1. In Puzzle Maker Pro, export an HTML batch (Number Trail, Number Snake,
   Queens, Binary). Zip the batch folder — catalog JSON + per-puzzle
   JSONs (+ future assets). Zipping the folder or its contents both work.
2. WordPress → Puzzle Catalogs → Add New → upload the zip in the
   **Catalog Upload** box. Selecting the file runs an instant preflight
   (same rules as the import) showing types/count/batch or the exact
   rejection before you save. Files are extracted, layout intact, to
   `wp-content/uploads/pmp-catalogs/<post_id>/`. JSON + images only;
   `index.html` and anything else is skipped. A catalog may contain
   **multiple puzzle types** — types are read from the puzzle JSONs
   themselves. Single-type catalogs get the type as category + tag
   (pretty names, e.g. "Queens"/`queens`); mixed catalogs get category
   "Mixed" with each type as a tag.
3. Publish. The post's own page (`/puzzles/<slug>/`) renders the player,
   or embed it anywhere with `[pmp_catalog id="123"]` /
   `[pmp_catalog slug="my-catalog"]`. One catalog per page.
4. Organize with the catalog-only taxonomies (Categories / Tags) and list
   catalogs anywhere with
   `[pmp_catalog_list category="queens" tag="…" type="…" limit="20" orderby="date|title"]`.
5. Settings → **Install demo catalogs** creates one demo post (a
   mixed-type catalog of 10 puzzles) from the zip bundled under `demos/`.
   Re-running updates it.

## Structure

| File | Responsibility |
|---|---|
| `puzzle-maker-pro-online.php` | Header, requirement gates, bootstrap |
| `includes/class-pmp-catalog-plugin.php` | Singleton loader |
| `includes/class-pmp-post-types.php` | `pmp_catalog` CPT, catalog taxonomies + admin columns; meta key constants |
| `includes/class-pmp-demo-content.php` | Demo catalog installer (Settings-page button, idempotent) |
| `admin/js/catalog-preflight.js` | Instant zip preflight in the upload meta box |
| `includes/class-pmp-zip-inspector.php` | Pure zip validation/extraction plan (tested by `../tests/test-zip-validation.php`) |
| `includes/class-pmp-importer.php` | Upload meta box, extraction, replace/delete lifecycle |
| `includes/class-pmp-renderer.php` | Shortcode + slug-page render; engine enqueue (`type="module"`) |
| `includes/class-pmp-settings.php` | Engine base URL + asset version (option `pmp_catalog_settings`) |

The embed contract (mount div attributes, absolute `data-puzzles-base`)
is documented in `Web/PuzzleEngine/README.md` → "Embedding".

## Development

- `php ../tests/test-zip-validation.php` — zip-security harness (no WP needed).
- `../build-plugin-zip.sh` — builds the installable zip.
- `TESTING.md` — manual acceptance checklist for a live site.
- Settings → Engine base URL → point at a local engine build
  (`http://localhost:5174/`) to develop against an unreleased engine.
