Add a theme contract gate for derived themes

[next-devin]

Closes #63.

A Spark-derived store theme never updates from this repo, so a fix that lands here does not reach it. The failure this gate targets is silent: the storefront renders, apps stay installed and enabled in the dashboard, and only the events go missing. Checkout keeps working, because the platform renders {% pixels %} from its own layout, which is what hides it.

#63 asked whether Spark should carry something that lets a derived theme discover it is missing a required block. This is that, built around the case the issue did not anticipate: a theme that had the block, was verified, and lost it again when an older working copy was republished over it.

What is here

theme-contract.json declares the integration points a derived theme must keep. One entry today: {% pixels %} in layouts/base.html, required since 1.3.0, with the reason the gate prints on failure.

scripts/check-theme-contract.py asserts them against either a working copy or a live theme:

python3 scripts/check-theme-contract.py --root path/to/theme
NTK_APIKEY=<key> python3 scripts/check-theme-contract.py \
    --store https://<store>.29next.store --theme-id <id>

The live mode is the one that matters. A store carries several theme copies, and republishing an old one undoes a patch applied to the active theme without touching it.

The gate reads more than the tag:

• comments are masked, so a commented-out tag does not satisfy the contract
• a child template that overrides the block without the tag fails, which a plain text search passes
• a theme with no readable templates fails rather than reporting success

pixels is also added to REQUIRED_BASE_BLOCKS in check-templates.py, so dropping the block from Spark itself fails CI.

Why the other two options in #63 were not taken

An upgrade note helps only at the moment someone forks. An inventory would not have caught the case that prompted this, since that theme was already in ours and already patched. Neither survives a republish.

Verification

make contract and make verify-theme pass. 78 tests pass, 11 of them new, including the child-override case and a regression test for the contract defaulting to Spark's own copy rather than the theme being checked.

Run against real derived themes, the gate reproduced known-bad layouts and confirmed known-good ones, with the rendered storefront agreeing with the template read in every case. Anything it found is a store-side fix and does not belong in this repo.

Notes for review

• Requirements should stay few. This is for integration points whose absence is invisible, not for style or structure.
• The remote mode filters the template list client-side because the admin API's ?name= parameter is ignored and returns everything.
• The gate deliberately has no fleet-sweep mode. Sweeping needs a store list and credentials, which do not belong in a public repo.
• Verify on the published storefront, never the Theme Editor preview. The preview does not render the tracker frames, so it shows this fault whether or not the theme has it.

🤖 Generated with Claude Code