Body
';\nconst blockMarkup = await convert(html, { url: 'https://example.com/page.html' });\n\nconsole.log(blockMarkup);\n```\n\nEmits:\n\n```html\n\nBody
\n\n```\n\n`convert` is the normal end-to-end path: it tries worker-backed conversion, falls back through composition when needed, canonicalizes the result, and returns WordPress block markup. If you don't pass a pool, it spins one up for the call and stops it before returning.\n\n## CLI\n\n```\nblocks-engine themeHello
', { url: 'https://example.com/' }, { pool });\n console.log(blockMarkup);\n} finally {\n await pool.stop();\n}\n```\n\n**Sizing.** The default pool size is `min(cores, 4)`, with a minimum of one worker. `WorkerPoolOptions.size` floors the value and still keeps at least one worker. Start with the default for request/response code; prefer `size: 1` (or another small number) for CI, deterministic tests, or memory-constrained jobs.\n\n**Cleanup.** Workers are child processes connected to the parent over Node IPC. Create the pool in the process that will send work, and don't pass a live pool across process boundaries. Workers die with the parent, but that is not a deterministic cleanup path — always `await pool.stop()` in a `finally` block, test teardown, or shutdown hook. The one-shot `convert` helper handles this for pools it creates itself; shared pools are your responsibility.\n\n**Recycling.** `recycleAfter` replaces a child after it has processed that many items. The default is `0` (disabled). Recycling helps with long-running batches, CI isolation, and workloads where periodically refreshing child-process state is safer than keeping one alive indefinitely.\n\n**Timeouts & resilience.** `itemTimeoutMs` (default `10000`) bounds how long one item can occupy a worker. On timeout or worker failure the pool reroutes work until its reroute limit is reached; unresolved raw conversions return a `RawConvertResult` sentinel and unresolved canonicalization returns the original HTML in a `FixResult`.\n\n**Observability.** `onEvent` receives `PoolEvent` values for `child-spawn`, `child-crash`, `re-route`, `recycle`, `sentinel`, and `pool-degraded`, with `childId` and `count` when available. Log these when diagnosing flakes, timeouts, fork limits, or degraded worker startup.\n\n**Packaging.** Run from an environment that can fork Node child processes and use IPC. For packaged or CI usage, run the package from its built distribution so the worker child file is present; source-mode execution depends on the local TypeScript runner setup.\n\n## Error handling\n\nPackage-level failures throw a `BlocksEngineError` carrying a stable `code` and a user-facing `hint`. The `code` is part of the package's contract — switch on it rather than matching message text. From the CLI, the `message` and `hint` are printed to stderr and the process exits non-zero.\n\n```ts\nimport { siteToTheme, BlocksEngineError } from '@automattic/blocks-engine';\n\ntry {\n await siteToTheme('./my-site');\n} catch (error) {\n if (error instanceof BlocksEngineError) {\n console.error(`[${error.code}] ${error.message}\\n${error.hint}`);\n } else {\n throw error;\n }\n}\n```\n\n| Code | Thrown when | Fix |\n|------|-------------|-----|\n| `INJECTION_VECTORS_REMAIN` | The default HTML fallback sanitized input but unsafe vectors remained. | Pass a custom `htmlFallback` that emits safe markup, or pre-sanitize the input. |\n| `THEME_INGEST_DUPLICATE_SLUG` | Two source pages resolve to the same theme slug. | Rename or restructure the source pages so each maps to a unique slug. |\n| `THEME_INGEST_NO_HTML` | A theme build finds no `.html`/`.htm` pages under the source directory. | Point the build at a directory that contains at least one HTML page. |\n| `WORKER_CHILD_UNRESOLVED` | The worker pool can't locate its child file (typically running from source, or an incomplete build). | Run `npm run build` and run from the built `dist`; confirm the worker child file is present. |\n\n## License\n\nGPL-3.0-or-later\n","readmeFilename":"README.md"}