Skip to content

[Blueprints] Export complete versioned Playground ZIP snapshots - #4139

Merged
adamziel merged 1 commit into
trunkfrom
adamziel/complete-versioned-zip-exports
Jul 21, 2026
Merged

[Blueprints] Export complete versioned Playground ZIP snapshots#4139
adamziel merged 1 commit into
trunkfrom
adamziel/complete-versioned-zip-exports

Conversation

@adamziel

@adamziel adamziel commented Jul 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Playground ZIP exports now contain every file under wp-content, plus wp-config.php. The manifest records formatVersion: 2 so the importer work in #4130 can distinguish these archives from pre-versioned partial exports.

This removes the selfContained option from the public zipWpContent() API. Every caller now receives a complete archive.

Testing

Export a Playground with a custom file inside a default theme. Inspect the ZIP and confirm it contains that file, wp-config.php, and a playground-export.json manifest with formatVersion: 2.

Stack

  1. #4139 — Export complete versioned Playground ZIP snapshots
  2. #4141 — Exclude legacy runtime artifacts from site snapshots
  3. #4130 — Import versioned ZIP user content while retaining legacy defaults
  4. #4131 — Import ZIP contents before initial browser persistence
  5. #4132 — Keep ZIP preparation visible until the imported site is ready
  6. #4121 — Accept ZIP drops across the page
@adamziel
adamziel requested review from a team and brandonpayton July 21, 2026 10:12
This was referenced Jul 21, 2026
Merged
Merged
Merged
Merged
@adamziel
adamziel force-pushed the adamziel/complete-versioned-zip-exports branch from 0d59a23 to 0f14b54 Compare July 21, 2026 10:33
@adamziel adamziel mentioned this pull request Jul 21, 2026
Merged
@adamziel
adamziel merged commit c0e10bd into trunk Jul 21, 2026
53 checks passed
@adamziel
adamziel deleted the adamziel/complete-versioned-zip-exports branch July 21, 2026 10:59
adamziel added a commit that referenced this pull request Jul 21, 2026
@adamziel
[Blueprints] Import versioned ZIP user content while retaining legacy…
534b3c5 
… defaults (#4130)

A version-2 Playground ZIP now defines user-owned `wp-content`: archived
files replace the boot defaults, and a missing user file means it was
deleted. Legacy runtime artifacts remain owned by the importing
Playground through #4141.

Pre-versioned exports remain partial. When one omits a stock plugin,
theme, or database directory, import retains the fresh installation's
copy. An archived copy still wins when present.

This preserves customized default themes such as BrewCommerce's purple
Twenty Twenty-Five background through export, import, and reload without
treating stock themes as runtime files.

## Testing

Browser coverage imports a pre-versioned partial export, then separately
customizes Twenty Twenty-Five, exports it, imports it into a new
Playground, reloads, and checks both the theme file and rendered
background. The full stack passes 488 Blueprint tests, 347 website
tests, both packages' lint and typecheck, and 10 Chromium ZIP-import
scenarios.

## Stack

1. [#4139 — Export complete versioned Playground ZIP
snapshots](#4139)
2. [#4141 — Exclude legacy runtime artifacts from site
snapshots](#4141)
3. [#4130 — Import versioned ZIP user content while retaining legacy
defaults](#4130)
4. [#4131 — Import ZIP contents before initial browser
persistence](#4131)
5. [#4132 — Keep ZIP preparation visible until the imported site is
ready](#4132)
6. [#4121 — Accept ZIP drops across the
page](#4121)
adamziel added a commit that referenced this pull request Jul 21, 2026
@adamziel
[Blueprints] Import versioned ZIP user content while retaining legacy…
394496a 
… defaults (#4130)

A version-2 Playground ZIP now defines user-owned `wp-content`: archived
files replace the boot defaults, and a missing user file means it was
deleted. Legacy runtime artifacts remain owned by the importing
Playground through #4141.

Pre-versioned exports remain partial. When one omits a stock plugin,
theme, or database directory, import retains the fresh installation's
copy. An archived copy still wins when present.

This preserves customized default themes such as BrewCommerce's purple
Twenty Twenty-Five background through export, import, and reload without
treating stock themes as runtime files.

## Testing

Browser coverage imports a pre-versioned partial export, then separately
customizes Twenty Twenty-Five, exports it, imports it into a new
Playground, reloads, and checks both the theme file and rendered
background. The full stack passes 488 Blueprint tests, 347 website
tests, both packages' lint and typecheck, and 10 Chromium ZIP-import
scenarios.

## Stack

1. [#4139 — Export complete versioned Playground ZIP
snapshots](#4139)
2. [#4141 — Exclude legacy runtime artifacts from site
snapshots](#4141)
3. [#4130 — Import versioned ZIP user content while retaining legacy
defaults](#4130)
4. [#4131 — Import ZIP contents before initial browser
persistence](#4131)
5. [#4132 — Keep ZIP preparation visible until the imported site is
ready](#4132)
6. [#4121 — Accept ZIP drops across the
page](#4121)
adamziel added a commit that referenced this pull request Jul 21, 2026
@adamziel
[Blueprints] Export and import all site files except Playground runti…
28db845 
…me files (#4141)

Make new ZIP exports preserve the site’s plugins, themes, uploads, and
database exactly. Make imports remove any pre-bundled Playground's
runtime files (such as `0-playground.php` mu-plugin) and lean on their
latest versions shipped in the `/internal` directory.

## Backwards compatibility

Playground's ZIP export format evolved over time. Here's how each
version is handled after this PR:

| ZIP | Site files in `wp-content` | Playground runtime artifacts | If a
theme or plugin is missing |
| --- | --- | --- | --- |
| Before this PR | Custom plugins, themes, and uploads. Default
`themes/twenty*` directories were included only by the self-contained
export. `database/` may be absent. | Some January–May 2024 ZIPs contain
the old SQLite MU plugin. | Backfill well-known paths from the site
loaded right before the import: Akismet, Hello Dolly, WordPress
Importer, default themes, and `database/`. This is a best-effort
heuristic. We can't distinguish a deleted theme from a missing theme. |
| `formatVersion: 2` after this PR | Every site path then on disk:
plugins, themes, uploads, `database/`, and a custom `db.php` if the user
specifically created one. | None. | Leave it missing. |

On every import, archived Playground files are removed. The new
Playground supplies them.

## Playground runtime files

These four old paths are always treated as Playground-provided runtime
files:

- `mu-plugins/sqlite-database-integration`
- `mu-plugins/playground-includes`
- `mu-plugins/0-playground.php`
- `mu-plugins/0-sqlite.php`

From January 29 through May 8, 2024, the self-contained exporter
included `mu-plugins/sqlite-database-integration`. It also included
`mu-plugins/0-sqlite.php` when present. It already omitted
`mu-plugins/0-playground.php` and `mu-plugins/playground-includes`;
those entries handle stale sites, GitHub trees, and hand-built ZIPs.

`db.php` needs a separate rule because it can be a custom WordPress
drop-in. During legacy WordPress boot, `writeLegacyDbPhp()` creates
Playground's copy through `generateDbPhpContent()`. That function writes
`@playground-managed` into the file header. Only a `db.php` with that
marker is treated as a Playground file. An unmarked `db.php` stays with
the site.

Before January 29, 2024, SQLite used
`plugins/sqlite-database-integration`. This PR leaves that path as site
content because it is also a valid user-installed plugin path.

**Breaking change:** `wpContentFilesExcludedFromExport` is no longer
public. `getLegacyPlaygroundRuntimeWpContentPaths()` exposes the smaller
runtime rule.

## Testing

Tests cover a modified Twenty Twenty-Five theme, a deleted v2 theme, a
theme omitted by a pre-v2 ZIP, archived runtime files, marked and custom
`db.php` files, failed runtime staging, and archives without
`wp-content`. The full stack passes 488 Blueprint tests, 347 website
tests, package lint and typecheck, and 10 Chromium ZIP-import scenarios.

## Stack

1. [#4139 — Export complete versioned Playground ZIP
snapshots](#4139)
— merged
2. [#4141 — Exclude legacy runtime artifacts from site
snapshots](#4141)
— includes #4130
3. [#4131 — Import ZIP contents before initial browser
persistence](#4131)
4. [#4132 — Keep ZIP preparation visible until the imported site is
ready](#4132)
5. [#4121 — Accept ZIP drops across the
page](#4121)
adamziel added a commit that referenced this pull request Jul 21, 2026
@adamziel
[Website] Import ZIP contents before initial browser persistence (#4131)
a751c2c 
ZIP imports used to persist a fresh WordPress installation before
applying the
archive. The archive then rewrote that stored filesystem:

1. Boot fresh WordPress in MEMFS.
2. Copy the fresh site to browser storage.
3. Apply the ZIP to the running site.
4. Flush the rewritten site to browser storage again.

This PR applies the ZIP during the new site's first boot, before its
initial
browser-storage copy:

1. Boot fresh WordPress in MEMFS.
2. Apply the ZIP in MEMFS.
3. Copy the finished filesystem to browser storage once.

`createNewSiteFromZip()` registers the import as first-boot work. The
boot path
runs that work before the initial MEMFS-to-OPFS copy, and the call
reports
success only after that copy finishes.

If ZIP initialization or the first OPFS copy fails, the newly created
stored
site is removed and the previously active Playground is selected again.
When
OPFS is unavailable, the import uses a fresh temporary Playground. Its
new slug
forces React to boot a new iframe instead of reusing the previous
runtime.

The ZIP picker now delegates this lifecycle to `createNewSiteFromZip()`
instead
of coordinating site creation, client boot, import, and persistence
through
component effects.

This PR does not change which files a ZIP contains or how versioned and
legacy
ZIP contents are interpreted. Those rules are handled by #4141 and
#4130. This
PR changes when the imported filesystem is written to browser storage.

## Testing

1. Import a ZIP from both temporary and saved Playgrounds and confirm
the new
   site persists after reload.
2. Import a malformed ZIP and confirm no incomplete stored site remains.
3. Confirm the previously active Playground remains selected after a
failed
   stored-site import.

Unit coverage checks that ZIP initialization runs before the initial
OPFS copy
and that failed-import cleanup selects the requested previous site once.
Browser
coverage checks that a failed import leaves the stored-site list
unchanged,
including after reload.

## Stack

1. [#4139 — Export complete versioned Playground ZIP
snapshots](#4139)
— merged
2. [#4141 — Export and import all site files except Playground runtime
files](#4141) —
merged
3. [#4130 — Import versioned ZIP user content while retaining legacy
defaults](#4130) —
merged
4. [#4131 — Import ZIP contents before initial browser
persistence](#4131)
5. [#4132 — Keep ZIP preparation visible until the imported site is
ready](#4132)
6. [#4121 — Accept ZIP drops across the
page](#4121)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment