Automattic / Automattic/blocks-engine

Preserve canonical artifact asset URLs through runtime mutation

Open
#1,159 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
PHP
Stars
14
Forks
2
Avg merge
2h 26m
Merged PRs (30d)
606

Description

## Problem

A captured site artifact can contain local files under `media/` and `assets/css/`, while preserved runtime behavior reintroduces root-relative URLs such as `/media/example.jpg` and `/assets/css/capture.css` after WordPress markup has already been canonicalized. Static Site Importer correctly copies the files under the generated theme, but the live frontend requests them from the WordPress origin root and receives `404`.

The Greek Corner acceptance case currently copies all four gallery images and three captured stylesheets successfully. Its persisted WordPress post content contains installed-theme URLs for the gallery images, but the post-load DOM contains `/media/...` image URLs and the browser requests all seven resources from root-relative paths.

## Verified boundary

Static HTML reference canonicalization is already working for the persisted post content. The remaining failure occurs when preserved gallery/runtime behavior mutates or emits asset references after page load. The producer contract must carry canonical artifact-local references through that runtime boundary; the consumer should not need source-platform-specific URL repair.

## Reproduction

1. Capture and compile `https://www.greekcorner.us/` through the static-site artifact path used by Automattic/studio#3952.
2. Materialize the resulting WordPress site plan.
3. Confirm the persisted homepage content contains installed-theme URLs for the gallery images.
4. Load the homepage and inspect the post-load DOM and network responses.
5. Observe copied theme files alongside live `/media/*.jpg` and `/assets/css/capture-*.css` requests returning `404`.

## Acceptance

- Preserve canonical artifact-local references when executable or preserved runtime content emits or mutates asset URLs.
- Keep Blocks Engine unaware of installed WordPress paths by expressing the references through the existing artifact/site-plan contract.
- Preserve query strings, fragments, external scheme URLs, and genuinely origin-owned root references.
- Cover runtime-emitted image `src`/`srcset`, stylesheet links, and CSS `url()` references.
- Greek Corner gallery images and captured stylesheets return `200` after normal SSI materialization and page load.

Evidence tracker: Automattic/studio#3952.

## AI assistance

OpenAI GPT-5.6 Sol via OpenCode compared persisted WordPress content with post-load network/DOM evidence, corrected the initial static-markup diagnosis, and drafted this issue update. Chris Huber remains responsible for the report.

Contributor guide

Open the contributing guide

Research direction

Trace the existing artifact/site-plan contract from the preserved runtime mutation boundary through normal Static Site Importer materialization. Reproduce the Greek Corner case and compare post-load DOM and network requests for images, stylesheets, and CSS references. Done means canonical artifact-local references survive runtime emission while external, query, fragment, and origin-owned URLs remain unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
php, wordpress
Domain
full-stack, web-dev
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.