Gotchas

Gotchas

Do not hand-edit the generated Notes runtime

Edit _tools/catalog-sources/apps/odd-notes/src/ and run npm run build:notes. CI rebuilds the asset and rejects drift.

App updates are version-driven

Changing JavaScript, CSS, or bundle bytes updates SHA256 but does not make the Shop show Update. Bump both the source metadata version and bundle manifest version before rebuilding.

Playground and PATCH

The Playground request bridge has dropped JSON bodies from PATCH in tested configurations while preserving editable WordPress POST requests. ODD Notes updates therefore use POST /odd-notes/v1/notes/{id}. Do not change this back without a Playground regression test.

updatedAtMs is not a client clock

version and updatedAtMs come from WordPress and form the concurrency token. Typing may update the display timestamp, but it must preserve both tokens until WordPress returns a successful save.

Playground origins are shared

Temporary sites can share playground.wordpress.net and user ID 1. A localStorage key containing only the user ID can leak a draft into another Playground. Use the server-generated ODD Notes installation UUID; if an old runtime cannot supply one on Playground, disabling recovery is safer than sharing unscoped data.

Identical stale requests are retries, not conflicts

A browser can save successfully and lose the response. The retry then carries stale tokens even though WordPress already has the requested content. The service returns the current note with HTTP 200 in that case. Only different content produces 409.

Catalog cache and integrity errors

If registry size/hash metadata and bundle bytes disagree, do not weaken verification. Confirm the Pages deploy completed, compare the hosted registry and bundle, refresh the catalog once, and retest with a cache-busted launcher.

Use the right Playground

• /go/dev/ tests main plus OpenStation 1.1.0.
• /go/preview/ tests the preview catalog.
• /go/ tests the pinned WordPress.org release.

The stable demo cannot prove an unreleased plugin runtime fix.

Native windows register for authenticated users

OpenStation window registration is user/capability-aware. WP-CLI smoke checks for odd-app-odd-notes must run with --user=1 (or another real user), not the anonymous CLI context.

Cached WordPress files do not imply an installed database

Local Docker may recreate MySQL while .e2e/wp/wp-config.php survives. The runner must check wp core is-installed, not merely the existence of WordPress files.