Import a static site or generated website artifact into WordPress pages and an intentional companion block or classic theme.
Static Site Importer is a WordPress plugin. It requires the Blocks Engine PHP transformer Composer package. Production compilation uses ArtifactCompiler::compile(); export still calls blocks_engine_php_transformer_convert_format().
Build a production-shaped development ZIP using immutable Blocks Engine source without changing this checkout's Composer files:
npm run build:dev-package -- --blocks-engine-path ../blocks-engine --blocks-engine-ref origin/trunkTo test an unreleased Blocks Engine change, point --blocks-engine-path at that checkout and omit --blocks-engine-ref: the package then uses the checkout's HEAD, and the build refuses to run while php-transformer/ or figma-transformer/ have uncommitted changes, because only committed bytes are packaged. With neither option, ../blocks-engine at origin/trunk is used.
The command resolves the requested ref once, archives php-transformer/ and figma-transformer/ from that commit into an isolated temporary snapshot, installs production dependencies there, and delegates ZIP assembly to homeboy review build. The ZIP and adjacent provenance JSON are written to build/. Use --output-dir <path> to select another destination. The receipt records SSI HEAD, a dirty worktree identity when present, the Blocks Engine ref and SHA, Composer lock digest, ZIP digest, and schema version.
runtime-package-manifest.json is the canonical package-composition contract for constrained or embedded WordPress runtimes. Consumers locate the manifest inside the normal plugin release, select a named profile, copy only matching relative paths, and fail if any declared required_files entry is absent. The contract is deployment-neutral: storage, archive transport, scheduling, and runtime infrastructure remain consumer concerns.
website-artifact-import remains the default release profile and provides the full artifact import, validation, WordPress site-plan materialization, and manifest-inspection abilities with all production Composer dependencies, including the Blocks Engine PHP and Figma transformers. html-site-import provides those same abilities for HTML string, file, URL, ZIP, and HTML website-artifact inputs while excluding Figma, optional Markdown conversion dependencies, and SSI's root Composer runtime. Select it for a development package with npm run build:dev-package -- --runtime-profile html-site-import; package consumers select the same name from runtime-package-manifest.json. Markdown and MDX inputs return an explicit unsupported-capability diagnostic in that reduced runtime. The immutable contract is also available from static-site-importer/get-runtime-package-manifest for runtime discovery.
static-site-importer/materialize-wordpress-site-plan is the generic plan-only boundary for a blocks-engine/wordpress-site-plan/v3 produced by Blocks Engine. SSI calls the package's canonical validator and resolver, then owns WordPress/filesystem preflight, materialization, reconciliation, and the static-site-importer/materialization-receipt/v2 response. Plan, report, classic handoff, and receipt bindings use the producer's blocks-engine/wordpress-site-plan-identity/v1; the materializer keeps its prepared_resolved_projection_hash separate for prepare-to-write TOCTOU detection. It accepts no source HTML or transformer result envelope.
For an isolated runtime matrix, invoke the ability with plan, slug, and optional overwrite, or use:
wp static-site-importer materialize-wordpress-site-plan --plan=/path/to/plan.json --slug=generated-siteImported documents and internal links use native WordPress permalinks. Redirection is the sole owner of old-source URL continuity: imports with source documents prepare the plugin and create owner-manageable exact-path 301 rules wherever source paths differ, including .html, index.html, and nested directory aliases. Switching themes does not remove these rules. Generated themes and companion plugins contain no source-route resolver or permalink override; keep Redirection active to retain old URLs. Portable exports carry active rules through _redirects for reimport.
Every artifact is passed through client_script_policy before Blocks Engine compilation and WordPress materialization. The default is inert: SSI removes executable inline, local, remote, module, telemetry, and data: script markup, removes bundled JavaScript assets, and records each disposition in import_report.client_script_policy. JSON data scripts are quarantined in the report and are not emitted into the generated site.
isolated_preview is the sole preservation opt-in. It requires an explicit client_script_provenance object with a non-empty ref and a runtime isolation assertion. It is intended only for an isolated disposable preview runtime. Preserved scripts remain untrusted_imported_code; artifact carriage, local paths, and source type never establish trust. Current-site REST imports forcibly use inert. Existing include_scripts URL collection callers no longer preserve scripts; callers must request script_policy: isolated_preview, supply provenance, and run only in an isolated preview environment.
Blocks Engine marks a plan reference_semantics.dynamic_client_assets.status = not_proven when a preserved local script builds asset URLs at runtime (dynamic imports, script injection, runtime URL construction), because those references cannot be proven against the theme's asset surface. By default SSI fails closed: destination preparation rejects the unproven plan with the canonical reason code.
Callers can opt into treating unproven references as a reported loss with require_proven_dynamic_client_assets => false (CLI: --allow-unproven-dynamic-client-assets). SSI then drops exactly the unprovable scripts from the artifact, strips their <script> tags and script preloads, recompiles a proven plan, and records one typed unproven_dynamic row per unproven reference (script path, referencing document, src, and sha256) in the client_script_policy.dropped report section the materialization receipt projects. Proven scripts and all non-script files are untouched.
Static Site Importer is the WordPress materialization layer for static website inputs. It accepts two related shapes:
- Static source imports: an HTML entry file, pasted HTML document, public HTML URL, bounded public static-site collection, direct HTML upload, or ZIP source tree.
- Generated website artifacts: a
blocks-engine/php-transformer/site-artifact/v1bundle emitted by website generation or browser runtimes.
The conversion stack is split by responsibility:
- Static Site Importer owns WordPress intake, safety checks, page/theme creation, asset placement, import reports, quality gates, and intentional block or classic theme materialization.
- Blocks Engine PHP transformer owns the generic
ArtifactCompiler, its diagnostics, and thesource_reports.wordpress_site_planv2 output. SSI materializes that plan into WordPress and returns the receipt and import report.
Companion refresh accepts new blocks, additive attributes, authoring defaults, styles and implementation updates. Removing a registration or changing/removing an existing attribute schema triggers a saved-usage lookup before files are written. It parses candidate WordPress posts (including revisions, reusable blocks and template posts), then active theme templates and parts. Text mentions and block name prefixes are not treated as actual instances.
If an instance still uses that contract, refresh returns
static_site_importer_companion_saved_contract_changed with the block name,
changed attributes and a post/template reference. An unused schema may change.
An unavailable or capped lookup returns static_site_importer_companion_usage_unverified.
overwrite is not a migration of every saved instance, including revisions.
This check targets schema-driven data loss. JavaScript/save-function compatibility,
default-value behavior and switching to another companion plugin remain separate
concerns. Run tests/companion-persistence.php in a disposable WordPress site for
the real multi-request regression and legitimate-refresh proof.
Jetpack form materialization prepares normalized controls, topology, provider layout/presentation destinations, and bounded receipt losses as a Static_Site_Importer_Form_Mapping_Plan. The plan resolves one mapped/declined decision before final form serialization; runtime binding and report projection consume that same decision. Visual-state collection reads the admitted plan without serializing a provider form.
The existing static_site_importer_form_receipt_loss_accepted waiver filter receives the complete proposed emission row, including markup and overlays. When that filter is installed and a loss needs its decision, the plan lazily serializes the proposal and reuses those exact bytes for the final report. Declined proposals remain report evidence and do not become runtime bindings.
Run php tests/smoke-form-mapping-plan.php for the phase-ordering, waiver, and loss-overflow contract, and the form-materializer smoke/topology and rendered-layout suites for output and presentation coverage.
Producer-declared WordPress.org metrics bind directly to native Paragraph and Heading text leaves. The generated companion carries fixed provider endpoints, validated configuration and source provenance, one-hour caching, per-request request deduplication, last-known-good fallback, editor refresh/detach controls, and runtime freshness receipts. Materialization receipts report the configured binding; after a frontend request, static_site_importer_external_metric_receipts records fresh, stale, captured_fallback, or unresolved with the fetch timestamp. Failed or partial aggregates never become zero. GitHub stars/forks remain unresolved until their separate bounded provider is implemented. See the external metric runtime contract.
All HTML, folders, ZIPs, URLs, and website artifact objects are untrusted static content. SSI accepts only explicit static asset extensions and server-side source markers never reach compilation. One decision, Static_Site_Importer_Content_Policy::admit_artifact(), runs once per import where the artifact is frozen for compilation, whatever the intake (REST files or ZIP, staged ZIP, CLI request bundle, URL collection, provided artifact):
- a non-static asset is skipped with a
static_site_importer_non_static_file_skippedfinding; - a non-entry page that is not static content (a server page, or HTML carrying server code) is dropped with a
static_site_importer_non_static_page_droppedfinding, and the remaining pages import; - the entrypoint (the declared one, or a root
index/default/homedocument) and the root_redirectsmanifest fail closed withstatic_site_importer_executable_source_rejected. Compiler-produced companion payloads are independently revalidated before any generated plugin file is written or activated. Companion block renders accept static HTML only; SSI emits its own fixed PHP wrapper to output that markup, so source PHP cannot be preserved or executed. Existing payloads that relied on PHP render templates or PHP companion assets must migrate their behavior to blocks, data bindings, or client-side JavaScript.
A URL import admits each collected batch through the same decision, with the site entry URL's page as the entrypoint. Its fetch guards stay its own: a private or reserved address, a disallowed scheme, embedded credentials, a TLS failure, a deadline, or a failure to fetch the site entry fails the import. A non-entry route that cannot be fetched (an HTTP error status, an oversize or empty response, a timeout, a client-rendered shell) is left out with a static_site_importer_url_route_omitted finding, and an asset that cannot be fetched keeps its source URL.
When a generated artifact contains full-document HTML, Static Site Importer routes document metadata, head content, styles, scripts, and page body fragments to the right WordPress destinations before calling the conversion stack. A core/html block in imported page content is therefore a materialization/conversion quality issue to fix in this stack, not a product-layer workaround to hide upstream.
- Accepts pasted HTML, one public HTML URL, a direct
.html/.htmupload, or a ZIP containing a static-site folder with anindex.htmlshell/chrome entry point. - Allows ZIP/CLI source-site imports to include nested
.md/.markdowncontent documents;.mdxis skipped with explicit diagnostics because MDX runtime components are not supported. - Provides one WP-CLI importer,
wp static-site-importer import, for pasted HTML, website files, ZIP archives, and public URLs through the canonicalstatic-site-importer/importability. - Discovers readable sibling
*.htmlfiles beside the selected entry file and recursive Markdown content documents under the source tree, then imports them as WordPress pages. - Compiles static HTML fragments and Markdown content through Blocks Engine
ArtifactCompiler. - Stores converted page bodies on the imported WordPress pages as
post_content. - Generates a block theme with shared header/footer template parts,
core/post-contenttemplates, page patterns for reusable/reference artifacts,theme.json,style.css, and optionalassets/site.js. - Rewrites local
.htmllinks to the imported WordPress page permalinks. - Creates deterministic
wp_navigationposts for supported header/footer navigation and references them from generated template parts. - Consumes producer-owned
explicit_refs/v1navigation references, validates all declarations before writes, and binds IDs before page persistence. Full destinations, submenu structure and authored item presentation stay producer-owned; SSI performs no inline-menu signature matching. Navigation uses explicit post-type reconciliation, participates in rollback, and is exposed inmaterialization_receipt.completed.navigation_entities. - Persists each producer-declared
synced_patternsentity (explicit_refs/v1) as one syncedwp_block, reconciled by identity on reimport, and replaces every{{wordpress-site-plan:pattern:…}}core/blockref with its post ID. Runtime entity bindings addressed to a pattern'ssource_pathapply inside the pattern, an owner-edited pattern is not overwritten, and patterns are reported inmaterialization_receipt.completed.synced_patterns. - Keeps imported pages native and editor-visible; page content belongs to WordPress pages while the generated theme owns shared chrome, background decoration, styles, scripts, and template wrappers.
- Keeps nested shared chrome references at their original positions inside page-owned layout containers. One template part owns the shared content while its occurrences preserve authored containment and order.
- Optionally activates the generated theme and assigns the imported
index.htmlpage as the front page when that page exists. - Names the generated theme from the resolved imported site title unless the caller supplies an explicit name.
- Removes untouched WordPress installation content (
Hello world!,Sample Page, and the sample comment) from fresh sites by default.
- WordPress 7.1 or later.
- PHP 8.3 or later.
- Composer dependencies installed with
composer install. - Node dependencies installed only when running the JavaScript block-validation smoke tests.
SSI pins automattic/blocks-engine-php-transformer:0.33.0 from Packagist. The committed Composer lockfile records the immutable source reference for the php-transformer-v0.33.0 release.
At runtime, SSI loads the transformer package from vendor/ and compiles with new ArtifactCompiler()->compile(). Theme export still calls blocks_engine_php_transformer_convert_format().
Static Site Importer is an infrastructure plugin. Its supported runtime surfaces are WordPress abilities, WP-CLI commands, REST endpoints, and PHP consumer APIs. It does not register an admin screen or ship an end-user Gutenberg block.
Open the separate demo interface in a disposable WordPress Playground site:
The release blueprint installs the infrastructure-only Static Site Importer package and a separate demo plugin built from demos/playground-importer/. The demo plugin owns the static-site-importer/importer block and consumes SSI's public REST contract to import into the disposable Playground site. The SSI plugin and its runtime package contain no demo UI or demo registration.
Testers can enter one public URL, upload static site files, choose a folder, upload a ZIP, or paste HTML. Figma upload is enabled only when the Playground runtime provides the optional zstd extension; all other source types remain available without it. Tagged blueprints and demo packages are published through the Playground publication contract, while the README uses the browser-verified playground/latest/blueprint.json alias.
URL imports collect a complete canonical plan before applying it once to the existing Playground site. The demo's PHP.wasm-only network adapter resolves public A/AAAA records through Google's DNS-over-HTTPS endpoint and uses WordPress HTTP over Playground's browser/proxy transport. SSI retains public-address classification, redirect validation, response limits, and the inert script policy. Native WordPress installations continue to use SSI's IP-pinned transport. After successful materialization, the demo opens the imported homepage; the /import/ page and Move to WordPress.com toolbar remain available. Failed imports stay on the importer with their error.
Imported document titles and descriptions belong to post titles and excerpts; social images belong to Media Library attachments via featured images. Registered Jetpack SEO fields receive authored values. Generated themes no longer replay route titles or descriptive source head tags. See the ownership contract and theme-switch proof for platform scope, presentation-only decisions, and remaining slices of #2430.
The imported site's resolved title is also the generated theme name, so a producer's generic package name does not replace the site identity. Callers can still pass name and slug. Developers can customize the final values with static_site_importer_theme_name and static_site_importer_theme_slug:
add_filter( 'static_site_importer_theme_name', static fn ( string $name ): string => $name . ' Theme' );
add_filter( 'static_site_importer_theme_slug', static fn ( string $slug ): string => 'custom-' . $slug );Imports remove untouched core seed content on sites where WordPress still reports fresh_site: the seed post, page, privacy-policy draft and comment, and the default fallback Navigation (a Page List titled "Navigation") that core publishes when a block theme header renders before the import, unless the import targets an existing theme. Records are fingerprinted before page materialization and checked again before deletion, so edited or replaced content is preserved. Set the canonical import argument remove_default_content to false, pass --keep-default-content to WP-CLI import commands, or use the static_site_importer_remove_default_content filter to disable cleanup.
POST /wp-json/static-site-importer/v1/imports normalizes source (url, html, files, archive, or artifact) and executes the canonical static-site-importer/import ability in the installed WordPress runtime. Product-specific interfaces and disposable preview orchestration belong in their owning product layers and consume the same ability contract.
URL intake rules:
- Every built-in URL import collects the bounded site through the resumable batch engine. It reads the origin's
/sitemap.xml, follows same-origin HTML links, and collects directly referenced page assets and nested CSS assets. - SSI owns collection, batch, deadline, asset, byte, pacing, and script-policy defaults. Hosts can adjust this policy with the
static_site_importer_url_batch_import_argsfilter. static-site-importer/importaccepts{ source: { type: "url", url, import_id? }, operation }. The first URL apply returns an opaqueimport_id; continuation supplies that ID in the same source envelope. SSI resolves the server-owned workspace and validates the URL, import options, and current user; no filesystem path is accepted or returned.- URL collection uses the frozen static artifact policy: executable and data scripts are omitted with reason-coded provenance because the server-rendered output does not require them.
- All source HTML is preserved. On the block-theme path SSI does not classify a subtree as non-authored chrome; deciding what content is in scope belongs to the capture adapter and the Blocks Engine plan. Classic projection still extracts header/footer/background fragments from source HTML.
- External assets must be directly referenced by fetched HTML or CSS and pass the same public-IP and redirect validation as page URLs.
- Only
httpandhttpsURLs are accepted. - Localhost, loopback, link-local, private, and otherwise reserved IP targets are rejected before connecting.
- Address classification is owned by SSI and behaves identically on every supported PHP version. Addresses are compared as packed bytes against an explicit RFC 6890 block table, IPv4-in-IPv6 encodings such as
::ffff:127.0.0.1are unmapped so the classified address is the address the transport connects to, and shared address space (100.64.0.0/10) is treated as non-public. - Redirect targets are revalidated with the same policy and capped.
- Requests use a timeout and maximum response size, require an HTML-like content type, and do not forward cookies, authorization headers, or embedded URL credentials.
- Import reports include source URL, final URL, status code, content type, fetch timestamps, response size, and redirect history.
ZIP intake rules:
- A root-level
index.htmlwins when present. - If there is no root-level
index.html, the ZIP may contain exactly one nestedindex.html, such assite-export/index.html. - If there are multiple nested
index.htmlfiles and no rootindex.html, the import fails so the entry point is not guessed. - Archive entries with absolute paths or
../traversal segments are normalized before extraction. Entries that are not static content follow the content-only decision above. - The entry-count and total-uncompressed-size limits reject the archive. An entry over a per-entry limit (uncompressed size or compression ratio) is skipped unread with a
static_site_importer_archive_entry_skippedfinding, unless it is the entrypoint or the redirects manifest, which fail closed. .mdand.markdownfiles under the selected source tree are imported as pages..mdxfiles are not executed or parsed as Markdown; they are skipped and listed inimport-report.jsondiagnostics.
Static store generators can expose products directly in raw HTML. Product cards using .product-card with a visible heading and price are accepted as commerce context and do not require a separate manifest. Generators may also include an optional products.json file beside the selected entry HTML file. When present, Static Site Importer validates the manifest and records the contract result under commerce.products_manifest in import-report.json.
Minimal schema:
{
"schema_version": 1,
"products": [
{
"name": "Signal Hoodie",
"slug": "signal-hoodie",
"regular_price": "64.00"
}
]
}Required fields:
schema_version: integer1.products: array of product objects.products[].name: non-empty string.products[].slug: lowercase URL slug using letters, numbers, and hyphens.products[].regular_price: decimal string such as19.00.
Optional product fields:
sale_price: decimal string.descriptionandshort_description: strings.categories: array of non-empty category-name strings.image: string path relative to the static site source.status: string product post status metadata.stock_status: string stock status metadata.stock_quantity: integer stock quantity.source_selectors: array of non-empty CSS selector strings for source-product cards.
Invalid manifests do not abort the import. The report marks the manifest invalid and records path-addressed errors such as $.products[0].slug. If raw HTML product cards supply product context, the optional manifest does not add a top-level products_manifest_invalid diagnostic.
Commerce-bearing imports require WooCommerce. Commerce intent is detected when any of these signals are present:
- a valid
products.jsonmanifest with at least one product, or - caller-supplied
commerce_contextwith at least one product, or - inferred commerce context from JSON-LD
Productdata or visible product cards.
When intent is present and WooCommerce is not active, Static Site Importer first tries to materialize the dependency deterministically by installing and activating WooCommerce from WordPress.org inside the active WordPress runtime. This keeps product support in the WordPress/PHP materializer rather than relying on the generating agent to install plugins by prompt convention.
The dependency materialization result is recorded under plugin_materialization.plugins.woocommerce with the plugin slug, plugin file, source, attempted flag, install/activate actions, status, and any error. If WooCommerce is already loaded, the status is already_available; if the runtime installs and activates it, the status is installed_activated; if installation or activation is unavailable, the status is failed and the dependency finding is retained for follow-up.
When WooCommerce remains unavailable after materialization, the import still succeeds. The missing dependency is reported three ways:
commerce.dependencies.woocommerceblock on the import report (required,active,waived,sources,product_count,missing_apis).- A
woocommerce_missingerror diagnostic in the reportdiagnostics[]list. quality.failure_reasons[]containswoocommerce_missingandquality.commerce_dependency_failuresis non-zero. The materialized import remains successful; install WooCommerce to enable commerce features.
Pass --allow-missing-woocommerce (CLI) or 'allow_missing_woocommerce' => true (PHP API) to import the theme without seeding products. The waiver records a woocommerce_waived warning diagnostic and clears the dependency failure. Pass --skip-dependency-materialization (CLI) or 'materialize_dependencies' => false (PHP API) only for tests or hosts that intentionally forbid plugin installation. Non-commerce imports (no manifest, no inferred context) are unaffected: no commerce.dependencies block is recorded and no dependency diagnostics are emitted.
This materializer is intentionally generic: WooCommerce is the first plugin-backed entity path, and the same pattern should be used for bbPress forums/topics, Jetpack-backed features, and other popular WordPress.org plugins. The source artifact declares or implies plugin-backed intent; SSI materializes the plugin in PHP; then a plugin-specific seeder creates native WordPress/plugin entities and records diagnostics.
Replay composition after a direct-artifact import fails at composition or later:
wp static-site-importer recompose --import-id=<id> [--output=/path/to/result.json]This uses retained compile receipts with the installed Blocks Engine, without recompiling pages or materializing the site. It writes the compact plan view (default: recomposed-result.json in the run workspace) and prints JSON diagnostic counts by code plus content-loss source paths. Successful runs still prune replay inputs; expired or missing checkpoints cannot be replayed.
The canonical ability uses source.type (html, files, zip, url, or figma) and operation (plan or apply). Figma sources accept a raw figma_file, scenegraph, or artifact bundle and normalize through the Blocks Engine Figma transformer before canonical materialization. Planning returns the canonical WordPress site plan, diagnostics, quality evidence, and source provenance without writing to the destination. Reference-backed sources use opaque source.ref values resolved only by the server-side static_site_importer_resolve_source_reference filter; ability callers never provide filesystem paths. All source HTML is preserved: SSI has no provider or platform axis and offers no option to strip source markup.
Direct artifact imports bound each step by max_invocation_seconds; reaching it yields a resumable continuation, so a host that relaunches steps compiles every page. A CLI host that stops relaunching at a wall-clock limit can set import_deadline_seconds in its --request JSON (for example, "import_deadline_seconds": 1800). It must be a positive finite number of seconds, measured from the run's recorded start, not from each continuation; invalid values are rejected. Omitting it keeps today's behavior: no overall import deadline. PHP hosts can also set it through the static_site_importer_direct_artifact_run_policy filter. When that deadline passes, the import finishes with the pages already compiled: the entrypoint is compiled first, and each unstarted page is reported as a page_compile_omitted warning with reason deadline and its source path in the import report's loss ledger. Those pages fail the quality gate unless the request also sets allow_omitted_pages: true. A missing entrypoint remains fatal.
static-site-importer import is the canonical host command. Its request file is the exact static-site-importer/import ability input, so every source type and option has one contract across PHP, REST, and WP-CLI. The command owns bounded continuation: it relaunches the same import step in fresh WordPress runtimes, passes SSI's opaque import_id, and prints only the terminal JSON result. A terminal failure prints the same machine-readable envelope and exits nonzero.
wp static-site-importer import --request=/absolute/path/to/import-request.json{
"operation": "apply",
"source": {
"type": "files",
"entrypoint": "index.html",
"files": [
{
"path": "index.html",
"content": "<main><h1>Portable site</h1></main>"
}
]
},
"slug": "portable-site",
"name": "Portable Site",
"activate": true,
"overwrite": true
}The host prints one static-site-importer/import-cli-receipt/v1 object. Use --report=/absolute/path/to/import-report.json for the operator-owned report destination and --max-steps=<count> to cap continuation steps. By default the host continues while every step advances the import and stops after 16 consecutive steps without progress. --single-step is the internal fresh-runtime seam; host integrations invoke the command without it. --url= is a minimal ergonomic source argument.
An import that materialized is accepted: its receipt has status: "completed" and response.success: true. Quality findings never reject it. quality.pass, failure_reasons, counters, scorecards, diagnostics and finding packets still report follow-up work. Failed receipts are reserved for genuine import failures, such as compilation or materialization errors.
A files request-bundle source may point at a raw Blocks Engine capture directory (its capture-receipt.json has the blocks-engine-capture/capture-receipt/v1 schema). SSI imports the receipt's websiteRoot and, when the request has no source.metadata.reports, forwards the receipt's reports (capture-root-relative sidecar paths) as the declared reports, read from the capture root and validated with the same safe-relative rules; declared reports the capture does not hold are skipped and symlinked ones are refused. An explicit source.metadata.reports always wins, and a receipt without reports forwards none.
Use --theme-materialization=block|classic; block is the default. Use --operation=plan or "operation": "plan" in the request to emit a plan without writes. Apply a saved response with --plan=/absolute/path/to/plan-response.json. A classic plan response includes a versioned, hashed normalized artifact, projection, and complete normalized arguments bundle. Apply verifies every digest and requires the immutable theme_materialization=classic strategy before running the full classic lifecycle.
wp static-site-importer import --url=https://example.com/ \
--operation=plan \
--slug=example-site \
> url-plan-receipt.json
jq '.response' url-plan-receipt.json > url-plan.json
wp static-site-importer import --plan=/absolute/path/to/url-plan.json
# Commerce-bearing import: put allow_missing_woocommerce in the request JSON.
wp static-site-importer import --request=/absolute/path/to/store-request.jsonindex.html has special front-page behavior: it becomes the home page slug and, when --activate is used, is assigned as the site's static front page. If the imported directory has no index.html, the pages are still imported, but the importer does not assign page_on_front automatically.
By default, source directories are deleted after a successful clean import so generated upload work directories do not accumulate. Sources are preserved when conversion quality checks report issues. Use --keep-source with CLI imports when you want to keep the original local source directory or fetched URL fixture after a successful clean import for debugging or development. Import reports include a source_documents summary with counts by format, skipped MDX count, unresolved local links, and Markdown parse-error diagnostics.
An import writes a conventional block theme directory under wp-content/themes/<slug>/:
<slug>/
style.css
functions.php
theme.json
assets/site.js # only when the source has inline JS
parts/header.html
parts/footer.html
templates/front-page.html
templates/index.html
templates/page.html
templates/page-<page>.html
patterns/page-<page>.php
Important behavior:
style.cssandtheme.jsonare plan-owned writes from Blocks Engine (ThemeJsonProjectionand stylesheet assets). SSI materializes those files rather than re-deriving palettes from:root.functions.phpenqueues frontend styles, editor styles, and optional generatedassets/site.js.- Shared chrome is stored in
parts/header.htmland, when present in the source,parts/footer.html. - Generated templates are lightweight block-theme wrappers: header template part, imported background decoration,
core/post-content, and optional footer template part. - Imported WordPress page posts store the converted page body in
post_content, so routing, titles, front-page assignment, editor visibility, and body edits stay native. - Page patterns are generated as reusable/reference copies of each converted page body; they are not the primary storage for imported page content.
static-site-importer/export-theme exports an imported or active block theme as a Blocks Engine website artifact. SSI owns the WordPress import/export/materialization path; Blocks Engine PHP transformer owns generic website artifact compilation. Product callers should consume the exported website_artifact object instead of SSI-specific static-site wrappers.
The export envelope includes:
schema: "blocks-engine/php-transformer/site-artifact/v1",artifact_type: "website",version,id,generated_at,root, andentrypoint.files[]entries with safe artifact-relative paths,role,kind,mime_type,encoding,bytes,sha256, and inlinecontent.- UTF-8 text content by default; binary content is transported as Base64 with
encoding: "base64". - source/materialization provenance under
provenance. - import/validation summaries and
reports[]references for repair loops. import-report.jsonandsource-documents.jsonmetadata files when the exported theme has SSI import provenance.
The default root is website with entrypoint: "website/index.html". Callers can pass any safe single-segment root with a matching entrypoint, such as root: "artifact" and entrypoint: "artifact/index.html". The import ability accepts the same canonical website artifact through artifact.
tools/reduce-finding.mjs shrinks a standalone page to the smallest version that still shows a finding. It parses HTML with parse5 and CSS with a block-aware parser. It then runs hierarchical delta debugging: ddmin over each level of the element tree, then unwrapping elements, dropping attributes and shortening text, then ddmin over CSS rules (including whole at-rule blocks and rules nested in @media/@layer) and declarations. It repeats until a round changes nothing or --max-calls/--timeout-ms runs out.
node tools/reduce-finding.mjs --input page.html --output reduced-case \
--predicate 'my-check {candidate}' # exit 0 = still reproduces
# or check a JSON report the command prints for each candidate:
# --report-command 'editability-report {candidate}' --check 'metrics.raw_html_block_count > 0' --stage editabilityThe output directory holds source.html (the reduced page), reduction.json (counts, budget use and a failure signature), and fixture.json. fixture.json is a blocks-engine/php-transformer/visual-parity-fixture/v1 fixture with 390px and 1440px viewports. Pass --target-command '<cmd {source}>' to write the transformer's WordPress render to target.html. Without it, the target is a placeholder (metadata.target_status: "placeholder") for the caller to fill in. The signature digests stage, check, blocks and structural features (tags, CSS property names, at-rules, selector features, value functions) and ignores names, text and literal values. Predicates can also be functions: reportPredicate, editabilityPredicate (Blocks Engine editability report metrics such as raw_html_block_count or max_nesting_depth) and visualParityPredicate (visual parity report reason_code). The import findings loop calls it to reduce each new finding before filing.
The bounded URL entrypoint retains one fresh capture from a caller-configured capture command, then passes that exact generated-artifact tree through SSI's existing fixture intake. It never interprets fallback counts as solved-site acceptance and does not run a matrix unless explicitly requested:
node tools/url-loop-intake.mjs https://quinn-fluid-demo.squarespace.com/ \
--capture-command '["npx","--yes","--package=<package spec>","<bin>","{url}","--output","{output}"]' \
--output-root /path/to/retained/quinn-capture \
--run-matrix --static-site-importer /path/to/static-site-importer \
--blocks-engine /path/to/blocks-engineThe harness names no capture producer. The caller supplies it:
| Setting | Flag | Environment | Default |
|---|---|---|---|
Capture command: a JSON argv array. {url} (the normalized source URL) and {output} (the retained capture directory) are substituted in every element and must each appear at least once. |
--capture-command |
SSI_URL_LOOP_CAPTURE_COMMAND |
none: the run is refused with capture_command_missing |
| Expected receipt schema | --capture-receipt-schema |
SSI_URL_LOOP_CAPTURE_RECEIPT_SCHEMA |
blocks-engine-capture/capture-receipt/v1 |
A flag wins over the environment. A bare argv[0] resolves against the bounded
child PATH (the configured Node directory plus the standard system
directories), and the recorded command is the absolute program that ran. The
command must write exactly one directory under {output} holding
capture-receipt.json and a website/ tree.
To run with Data Liberation Agent, use v0.27.0 or later; earlier releases
write the retired data-liberation/capture-receipt/v1 receipt and are blocked
with capture_receipt_schema_unknown. For v0.27.0 (commit
2986ca1e386e994696d41a47e94edb8dd3665c43, asset SHA256
2611d686a804f0db20c1306fbfc807d8785a62040e462a555c2f02fb53cfedc3):
export SSI_URL_LOOP_CAPTURE_COMMAND='["npx","--yes","--package=https://github.com/Automattic/data-liberation-agent/releases/download/v0.27.0/data-liberation-0.27.0.tgz","data-liberation","{url}","--output","{output}"]'Pin an immutable release asset rather than a moving npm tag so repeated runs use the same producer bytes. The operator then supplies only the URL on later runs.
The resulting url-loop-handoff.json records
derived SHA256 provenance for the normalized URL, receipt bytes, and retained
capture content, plus the capture receipt,
observed component identities (the capture identity is the configured argv, its
SHA256 and the expected receipt schema), normalized fixture, canonical matrix summary and
artifact references when requested, stage failures, and replay commands. A capture receipt must
declare the expected receipt schema, with source.url bound to the normalized
URL and a complete route summary (routesCaptured === routesDiscovered, with no
failed or skipped routes). Ambiguous artifact directories, partial captures,
missing files, and a missing capture command are blocked before SSI intake. A complete capture
without a requested matrix is needs_evaluation; matrix evidence is accepted only
when the selected fixture is explicitly verified in the canonical runtime
evidence summary. WordPress/editor evidence remains owned by the existing fixture
matrix and is required by solved-site promotion; this entrypoint never claims solved
status.
tools/import-loop/loop.json is a Homeboy workflow (homeboy/workflow/v1) that drives one source URL toward a clean, editable import. It imports the way a user does: studio create --from <url>, which installs the latest Data Liberation Agent, Static Site Importer and Blocks Engine releases. One pass is one workflow instance. Homeboy runs the steps, Cook fan-out, the approval and the chain of passes; the scripts in this directory hold the import-specific logic.
-
import (
import.sh) captures the source once withstudio create --from --keep-source. Every pass then re-imports that frozen capture through the latest Static Site Importer release, with the transformer from Blocks Enginetrunk(gates/reimport.sh, as triage, the Cook gate and confirm do). A merged Blocks Engine fix is measured on the very next pass, with no wait for a release. -
evaluate (
evaluate.mjs) renders every source and imported route at 390, 768 and 1440px, opens each route in the block editor, and writesfindings.json. Each finding has a stable signature over stage, check, owning repository and subject, so a defect keeps its id across passes. Theme metrics (restyle_coverage_low,theme_css_bloat,quality_status,block_nesting_deep) are advisory; every other check is a blocker. A pass with no blockers accepts the source. -
triage (
triage.mjs) matches each blocker to an issue that carries its signature. For a new finding with a predicate inpredicates/<check>.mjs, it:- reproduces the finding against Blocks Engine
trunk, falling back to the capture's own route document when the inlined page does not show it; - reduces it with
tools/reduce-finding.mjs; - files it in the owning repository with the reduced page and the predicate.
It reopens a closed issue whose finding still reproduces. Findings without a predicate are reported as untracked.
- reproduces the finding against Blocks Engine
-
cook runs up to three Homeboy Cooks in parallel, one per tracked issue. A Cook opens a fix PR, or reworks the existing one. Its gate is the repository's
verifycommand fromrepos.jsonplus the finding's acceptance check. -
confirm (
confirm.mjs) re-imports the capture at each fix PR's head and re-runs the finding's predicate on every route and width where the finding was seen. The fix is refuted if the predicate still reproduces, if the head restyles elements outside the finding, if it breaks the import, or if it conflicts withtrunk. -
merge runs
homeboy git pr merge-when-greenfor each PR in confirm's merge list: each PR that is not refuted, at the head confirm checked, once its checks are green. A merge that holds (failed checks, conflict, a moved head) is reworked by the next pass.
Homeboy's next_pass starts the next pass. The chain stops when the source is accepted, when no blocker is tracked, when three passes in a row see the same blockers, or after 60 passes. Cook and merge items may fail without ending the chain ("join": {"min_succeeded": 0}): the next pass sees the same findings and tries again.
Run it from this repository's root (the host needs studio, an authenticated gh, PHP, Node, and this repository's npm ci with Playwright Chromium):
homeboy workflow run "$PWD/tools/import-loop/loop.json" \
--input url=https://example.com/ --input slug=example \
--input loop_dir="$PWD/tools/import-loop" --input runs_dir=/path/to/runs \
--input blocks_engine=/path/to/blocks-engine-clone \
--input cook_model=<model> \
[--input cook_placement=auto] [--input wp_cli='studio wp'] \
[--notification-transport <transport> --notification-route <route>]
homeboy runs show <instance>blocks_engine is a clone the loop owns: triage resets it to trunk before reproducing. cook_model chooses the Cook's Pi model (see homeboy agent-task providers). cook_placement follows homeboy agent-task cook --placement.
The loop measures; the importer does not fail an import on these findings. Import quality gates are always report-only, so the loop's blockers are its own acceptance policy, not import failures.
The product handoff contract is defined in docs/product-handoff-contract.md and locked by tests/fixtures/product-handoff-contract/v1.json plus tests/smoke-product-handoff-contract.php.
Owner readiness after materialization uses static-site-importer/owner-handoff-evidence/v1. It binds the canonical plan identity and materialization receipt hashes, composes existing parity/editability/media/provider/metadata/runtime receipts, and renders the same envelope as a user-facing report card. Missing mandatory evidence is an evidence_gap; it is never treated as a pass. accepted_built_allowed is false when the report contains hard failures or evidence gaps. See docs/contracts/owner-handoff-evidence-v1.md.
The handoff path is:
- product caller sends a
blocks-engine/php-transformer/site-artifact/v1input artifact; - Blocks Engine
ArtifactCompilerreturnsblocks-engine/php-transformer/result/v1withsource_reports.wordpress_site_planusingblocks-engine/wordpress-site-plan/v3; - SSI consumes that v2 plan, writes WordPress state, and returns a materialization receipt plus
static-site-importer/import-report/v1with import validation and finding packet artifacts; - Codebox may validate the WordPress result and return
wp-codebox/validation-artifact-envelope/v1artifact references.
Blocks Engine does not know about Codebox. Products that need sandbox validation request it after SSI materializes WordPress.
static-site-importer/validate-artifact validates a Blocks Engine website artifact in the current WordPress runtime and returns static-site-importer/import-validation-result/v1 importer diagnostics. The ability accepts artifact plus normal import options; it is exposed through the Abilities REST API when that API is available.
The matching CLI command reads an artifact JSON object, imports it with activation, overwrite, and dependency materialization enabled by default, and writes the result to stdout or --output:
wp static-site-importer validate-artifact \
--artifact=/path/to/website-artifact.json \
--slug=example-import \
--name="Example Import" \
--output=/path/to/validation-result.jsonThe repository has both WordPress-side fixture coverage and generated-artifact validation.
Run the full local contract from the repository root:
npm install
npm run test:validationThe harness requires the Studio CLI. By default it creates a disposable Studio site in a fresh temporary directory, imports tests/fixtures/wordpress-is-dead/, and runs the PHP smokes and JavaScript block-validation smoke in dependency order. WordPress commands use studio wp --path <temporary-site>. The harness deletes the site and directory afterwards, including on failure.
Use --keep-site to retain the disposable site for inspection, even on failure; its path is printed. Set STATIC_SITE_IMPORTER_SITE_PATH to use an existing site instead: the harness may change its content and active theme, but never deletes it.
The theme directory defaults to the target site's wp-content/themes/wordpress-is-dead. A positional directory overrides STATIC_SITE_IMPORTER_THEME_DIR, which overrides that default. STATIC_SITE_IMPORTER_WP_CLI overrides the WordPress command only, not disposable-site creation or cleanup; pair it with an explicit site path for an existing non-Studio runtime.
npm run test:validation -- --keep-site
STATIC_SITE_IMPORTER_SITE_PATH=/path/to/site npm run test:validation
STATIC_SITE_IMPORTER_SITE_PATH=/path/to/site STATIC_SITE_IMPORTER_WP_CLI="wp --path=/path/to/site" npm run test:validation
STATIC_SITE_IMPORTER_SITE_PATH=/path/to/site npm run test:validation -- --skip-import /path/to/wp-content/themes/wordpress-is-dead
STATIC_SITE_IMPORTER_THEME_DIR=/path/to/theme npm run test:validation
npm run test:validation -- --json--skip-import skips fixture import only; use an existing site and generated theme when revalidating artifacts. --json emits structured results, including the target site path.
test-manifest.json is the canonical repository-wide test inventory. It classifies every executable test as standalone PHP, WordPress runtime, Node, browser/WP Codebox, or operator-only acceptance. Explicit command values are arrays of executable and argument strings. npm test runs the fast standalone PHP and Node projection; it reports the environment-heavy lanes as skipped. npm run test:all is the complete CI/reviewer command and runs configured runtime lanes while reporting operator-only acceptance commands explicitly. npm run test:inventory verifies that every executable test is declared once and that standalone_php_test_paths in homeboy.json remains the deterministic standalone-PHP projection used by Homeboy.
PHP smokes are declared in test-manifest.json; run the standalone lane with npm test or the complete configured lanes with npm run test:all.
Submitted choice forms can stay editable while still needing a working way to save answers. Those imports complete successfully with a form_submission_setup_required finding. Their reports explain the setup needed, and the importer sends its successful completion signal. Forms without a submit control keep their existing handling.
The normal tests and automatic engine-upgrade checks run this form test with the installed engine. Older engines must retain the unsupported form fallback. Engines that preserve editable choice forms must disable their controls, show the visitor message, and keep the import marked as needing repair. To require the editable-form checks against a specific engine checkout, run:
STATIC_SITE_IMPORTER_BLOCKS_ENGINE_PATH=/path/to/blocks-engine/php-transformer php tests/smoke-choice-submission-form.phpRunning every tests/form-*.php and tests/smoke-form-*.php also includes the real-provider rendering test, smoke-form-repeated-instance-ids.php. Its WordPress runtime must have Jetpack installed, active, and its Forms module enabled (installing the plugin alone is insufficient):
wp --path="$STATIC_SITE_IMPORTER_WP_ROOT" plugin install jetpack --activate
wp --path="$STATIC_SITE_IMPORTER_WP_ROOT" jetpack module activate contact-form
for t in tests/form-*.php tests/smoke-form-*.php; do php "$t" || exit 1; doneUse a disposable test WordPress installation; these setup commands change its installed plugins and active modules.
Every new WP_Error( and throw new in includes/*.php is classified in tests/fixtures/error-classification.json, and php tests/smoke-error-classification.php fails on any site that is not. Classes are integrity (paths, containment, permissions, digests, identity, producer contracts), operational (size, time, memory, runtime availability), representability (source content this layer cannot express, with a unit of item, block, page, route or asset), propagated (an error from another layer passed through) and programmer.
-
A
WP_Errorwith a literal code is registered by its code. -
A computed code, or any
throw new, is registered as<file>#<normalized expression>and needs a comment on its line or the line above:// ssi-error-class: integrity throw new RuntimeException( 'Artifact workspace directory cannot be a symlink.' );
Use
representability:<unit>for representability, for example// ssi-error-class: representability:page. -
Registry entries whose site no longer exists fail, so remove them with the code.
-
representability_pendingcan only shrink. A new limit should degrade the smallest unit and record a finding instead of failing the import. When a pending site is converted, move its key torepresentability_convertedwithfinding_code,unit,owning_layerandproof_smoke, a registered smoke that shows the finding reachingStatic_Site_Importer_Receipt_Projection::compose().
php tests/smoke-error-classification.php --list prints every site with its key as JSON lines.
The import report records each finding once, with a loss class and an acceptability. Classes come from Static_Site_Importer_Diagnostic_Loss_Classes. Producers report their own losses through website/source-findings.json (docs/contracts/website-artifact-evidence.md).
| Acceptability | Loss classes | Meaning |
|---|---|---|
acceptable_conversion |
native_conversion, editable_approximation |
Converted to editable blocks. |
acceptable_preservation |
preserved_runtime_island |
Preserved as a bounded runtime island. |
accepted_reported_loss |
page_compile_omitted, degraded_unit, omitted_unit |
A producer hit a representability limit confined to one unit. The import completes and the loss is reported. |
unacceptable_imported_output_defect |
unsupported_loss, importer_materialization_bug, unrecognized_loss_class |
The imported output is defective. |
Degrade codes SSI and Blocks Engine own are classified by code, before any explicit loss_class, contract repair lane or heuristic. unit and owning_layer fill in only when the producer row names none. Other producers' rows carry their own loss_class, unit and owning_layer (see source findings below):
| Code | Loss class | Unit | Owning layer |
|---|---|---|---|
page_compile_omitted |
page_compile_omitted |
page |
blocks-engine |
editability_policy_degraded |
degraded_unit |
page |
blocks-engine |
html_include_budget_exceeded |
degraded_unit |
page |
blocks-engine |
html_include_directive_ignored |
degraded_unit |
page |
blocks-engine |
glyph_color_undecodable |
degraded_unit |
item |
blocks-engine |
wordpress_site_plan_unresolved_navigation_link |
degraded_unit |
item |
blocks-engine |
runtime_dependency_target_missing |
degraded_unit |
block |
blocks-engine |
wordpress_site_plan_colliding_asset_target |
degraded_unit |
asset |
blocks-engine |
wordpress_site_plan_omitted_link_declaration |
omitted_unit |
item |
blocks-engine |
runtime_entity_dropped |
omitted_unit |
item |
blocks-engine |
runtime_declaration_dropped |
omitted_unit |
declaration |
blocks-engine |
runtime_entity_binding_unanchored |
omitted_unit |
binding |
blocks-engine |
runtime_form_graph_rejected |
omitted_unit |
item |
blocks-engine |
runtime_declaration_rejected |
degraded_unit |
item |
blocks-engine |
document_head_attribute_dropped |
omitted_unit |
item |
blocks-engine |
document_head_element_dropped |
omitted_unit |
item |
blocks-engine |
static_site_importer_non_static_file_skipped |
omitted_unit |
file |
static-site-importer |
static_site_importer_non_static_page_dropped |
omitted_unit |
page |
static-site-importer |
static_site_importer_archive_entry_skipped |
omitted_unit |
file |
static-site-importer |
static_site_importer_url_route_omitted |
omitted_unit |
route |
static-site-importer |
font_face_unavailable |
omitted_unit |
asset |
static-site-importer |
omitted_artifact_files, omitted_artifact_file |
omitted_unit |
file |
blocks-engine |
degraded_unit keeps the unit with reduced fidelity; omitted_unit removes it from the import. Blocks Engine's file-drop codes (file_limit_exceeded, artifact_file_too_large, artifact_total_too_large, and the aggregate artifact_inputs_rejected) are re-owned as omitted_artifact_files / omitted_artifact_file; the rest of the site imports, and dropped_artifact_files stays a quality failure reason without rejecting the materialized import. A page_compile_omitted page (a representability throw, a stalled compile worker, or the import deadline) is absent from the imported site, so it fails the quality gate with failure reason page_compile_omitted, counted as omitted_page_count and by the omitted_pages validation gate; source_documents.total_count counts it as a source document and source_documents.omitted_documents names it. The rest of the site still imports. A caller that accepts a partial site sets allow_omitted_pages: true (CLI --allow-omitted-pages): the omission stays a reported loss and does not fail the gate. A font_face_unavailable row carries a resolution of dropped (the theme uses its fallback font) or remote_import_retained (the source's Google @import is kept); a font digest mismatch fails closed. Blocks Engine repair lanes restore_compiled_document_identity and restore_projected_selector_binding map to unsupported_loss and editable_approximation.
A website artifact may carry website/source-findings.json (schema static-site-importer/source-findings/v1): the routes, pages, blocks, assets, stylesheets or profiles its producer dropped or degraded. At intake, Static_Site_Importer_Source_Findings removes the file from the site and adds one report row per finding, with the row's own code, severity, unit, loss_class (omitted_unit or degraded_unit), owning_layer, location, message and numeric metrics. None of these rows fails the import. A row outside SSI's vocabulary stays visibly unrecognized_loss_class. An artifact without the file imports unchanged; a file that cannot be read or fails validation adds one source_findings_unreadable warning. The contract, including the capture evidence names SSI reads from Blocks Engine's vocabulary, is docs/contracts/website-artifact-evidence.md.
Static_Site_Importer_Diagnostic_Projection::normalize_import_diagnostics() gives every report row the same canonical fields. The mapping is additive: each producer field also stays on the row under its own name.
| Canonical field | Filled from, first non-empty |
|---|---|
code |
code, diagnostic_code, type |
severity |
producer severity, else derived from type |
unit |
producer unit, then the degrade-code table, else '' |
location |
source_path, path, url, then Blocks Engine context.source_path. A nested context.source_path also fills a missing top-level source_path. |
message |
message, summary, reason (producer free text), error_message |
reason_code |
reason_code, reason, error_code, else type |
metrics |
numeric metrics entries. Blocks Engine editability context.metric/actual/maximum becomes <metric> and <metric>_maximum, and omitted_count is copied in. Empty map when none. |
owning_layer |
producer owning_layer, then the degrade-code table, then static-site-importer for a static_site_importer_* code or blocks-engine for a Blocks Engine source class, else '' |
loss_class |
classification above |
acceptability |
derived from the final loss_class |
Single compiler diagnostics keep unit, owning_layer, reason_code, source_path, path, url, selector, numeric metrics and omitted_count through the compiler diagnostic bound.
compact_summary (static-site-importer/import-metrics/v1) carries loss_class_summary (every class), loss_count and loss_counts (classes whose acceptability is accepted_reported_loss or unacceptable_imported_output_defect), and omitted_page_count. Its diagnostics list keeps code, location, url, path, value and metrics along with the classification fields.
The list holds at most 50 rows. When the report has more, rows are kept by tier: imported-output defects, then accepted reported losses, then acceptable conversions and preservations, in report order within each tier. Kept rows are emitted in report order.
php tests/smoke-wordpress-site-plan-materializer.php runs outside WordPress and verifies that Blocks Engine's direct ArtifactCompiler output is consumed through source_reports.wordpress_site_plan v2 and materialized into the stable receipt contract.
The wordpress-is-dead smoke verifies the multi-page fixture, generated block-theme artifacts, internal-link rewrites, persistent navigation entities, source CSS preservation, editor style support, plan-owned theme.json / style.css, and selector fidelity across stored/rendered paths. The mixed-source-site smoke verifies an Astro-like source tree with index.html, nested Markdown content documents, explicit skipped-MDX diagnostics, report source counts, and generated page block markup.
tests/StaticSiteImporterFixtureTest.php mirrors the wordpress-is-dead fixture contract in PHPUnit form for the Homeboy WordPress test runner and CI.
homeboy test static-site-importer --path /path/to/static-site-importerThe GitHub workflow runs Extra-Chill/homeboy-action@v2 with the test command across PHP 8.3, 8.4, and 8.5.
The generated-theme JavaScript smoke runs Gutenberg's parser and block validator against generated theme artifacts:
npm install
npm run test:js-block-validation -- /path/to/wp-content/themes/wordpress-is-dead
npm run test:js-block-validation -- --json /path/to/wp-content/themes/wordpress-is-deadIf no path is passed, the smoke uses STATIC_SITE_IMPORTER_THEME_DIR, then WP_CONTENT_DIR/themes/wordpress-is-dead when WP_CONTENT_DIR is set, then a local wordpress-is-dead directory under the repository root.
It validates parts/header.html, parts/footer.html, patterns/*.php, and templates/*.html, and reports invalid blocks with the file, nested block path, block name, validation reason, and failure summaries grouped by block name and file.
The repo owns the Static Site Importer fixture matrix under bench/, tools/, lib/fixture-matrix/, fixtures/, and rigs/static-site-importer-fixture-matrix/. This is the product-level development gate for importer quality against generated static-site artifacts and the Blocks Engine fixture corpus.
npm run test:fixture-matrix
node bench/static-site-fixture-matrix.bench.mjs \
--static-site-importer-path . \
--blocks-engine-php-transformer-path /path/to/blocks-engine/php-transformer \
--fixture-root /path/to/blocks-engine/fixtures/websitesSee docs/fixture-matrix.md for the Homeboy/Lab/WP Codebox workflow, generated-artifact intake, visual parity, editor validation, and Blocks Engine corpus/override usage. SSI keeps only minimal matrix smoke fixtures under tests/fixtures/fixture-matrix; the canonical site corpus lives in Blocks Engine.
This repo is Homeboy-managed:
homeboy.jsondeclares the component ID, WordPress extension, version target instatic-site-importer.php, and generated changelog target atdocs/CHANGELOG.md.- Do not edit
docs/CHANGELOG.mdmanually. Homeboy owns changelog generation from commits at release time. - Do not hand-bump plugin versions. Homeboy updates version targets during release.
- Use conventional commits so release notes and changelog entries are meaningful.
- The importer is intentionally static-site/artifact-to-block-theme glue. Blocks Engine PHP transformer owns generic artifact compilation, format conversion, and conversion reports; SSI owns WordPress uploads, import workflows, media, route rewriting, page/product materialization, and theme assembly.
- Local source imports discover flat sibling
*.htmlfiles beside the selected entry file and recursive Markdown content documents. Bounded URL collection discovers sitemap and same-origin linked HTML routes but does not execute JavaScript or perform platform-specific API extraction. - Admin imports accept pasted HTML, one public URL, a direct
.html/.htmfile, or a ZIP with a rootindex.htmlor exactly one nestedindex.html; CLI imports take a direct HTML entry path or one public URL. - MDX, Astro, Eleventy, Hugo, and other runtime/build orchestration is out of scope. Build those projects to static HTML first, or provide plain
.md/.markdownsource content alongside the HTML shell. - Linked local stylesheets and inline styles are copied into
style.css; inline scripts are copied intoassets/site.js. Bounded URL collection packages directly referenced HTML/CSS assets, while local source intake does not independently crawl missing assets. - Navigation persistence is limited to supported header/footer shapes that can be converted into deterministic
wp_navigationentities without guessing. - External live triage has exercised additional static sites; committed first-party fixtures include
tests/fixtures/wordpress-is-dead/andtests/fixtures/mixed-source-site/.
This plugin owns static-site and website-artifact import workflows plus generated WordPress artifacts. Blocks Engine PHP transformer owns generic artifact compilation and emits source_reports.wordpress_site_plan using blocks-engine/wordpress-site-plan/v2; SSI materializes that plan and records its receipt.
The intended dependency direction is:
Static Site Importer -> Blocks Engine PHP transformer
SSI import reports record blocks_engine.transformer provenance and blocks_engine.wordpress_site_plan; they do not project compiled-site or materialization-plan v1 payloads. Blocks Engine schemas are the active wire contract; SSI should not call lower-level converter packages directly or re-derive semantic page-route intent when the transformer supplies it.
Imported pages remain WordPress pages for routing, titles, front-page assignment, editor visibility, and body content edits. Their imported body layouts live on the page posts as block markup in post_content. The generated block theme owns shared header/footer parts, optional background decoration, frontend/editor styles, scripts, and template wrappers that render page bodies through core/post-content; the generic templates/page.html stays the fallback for pages created after import.