Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Generated differential CSS corpus for the PHP transformer

Open
  • Is something wrong?
#2,892 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
15/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
php
Domain
testing-qa, tooling

Research direction

Start from php-transformer/tools/visual-parity/tests/inline-declaration-priority.mjs, which shows the transform-and-render-in-Chromium comparison at 390px and 1440px that the corpus would reuse. The work is a seeded generator of small pages with a <style> block, a batched PHP runner, a JSON report, and a README, so 'done' means the four acceptance points hold, including reproducing the #1914, #2183, #1837 and #1941 families. Scope and feature catalog need maintainer agreement before coding.

Written by the indexing model from the issue text.

Description

Problem

Most transformer defects are found by importing real sites. A random sample of 100 merged fix PRs across Blocks Engine, Static Site Importer and Data Liberation Agent (since 2026-08-18) found that 61 of 63 defects reproduce on a small synthetic page. Many are core CSS behavior rather than site-specific shapes:

  • #1914: :where() contents counted toward specificity
  • #2183: custom property names lowercased
  • #1837: custom properties declared inside a media query skipped by var() resolution
  • #1941: grid items keeping their automatic minimum size

Because these are core CSS semantics, they can be enumerated ahead of time. Finding them one customer URL at a time is slow and expensive.

php-transformer/tools/visual-parity/tests/ already has the right primitive. inline-declaration-priority.mjs transforms HTML with the PHP transformer, renders source and output in Chromium at 390px and 1440px, and asserts equal computed style and box per element. There are 27 of these tests, each hand-written for one case.

Proposal

A generated differential corpus over that primitive:

  1. Grammar. A deterministic, seeded generator of small standalone pages: a few elements plus a <style> block, combining one or two features from a declared catalog. Slice 1 covers these feature families:
    • Selectors: descendant, child, sibling and adjacent-sibling combinators; :where()/:is()/:not(); attribute selectors; specificity ties.
    • Cascade: source order, !important (inline and stylesheet), @layer, @media, custom properties (case, fallbacks, scope, declared inside @media).
    • Layout: block flow and margin collapse, flex, grid (template, automatic minimum size, gap), positioning, aspect-ratio.
    • Box model and typography: shorthands vs longhands, logical properties, units (em/rem/%/vw/clamp()), line-height, inheritance.
    • Common recognizer inputs: headings, lists, figures with captions, links styled as buttons, and image-and-text pairs.
  2. Runner. For each generated case, transform once in PHP and render source and output in Chromium at the existing viewports. Compare computed style for a declared property set, plus the box of every marked source element. Batch the PHP calls in one process so the corpus runs in minutes.
  3. Report, not gate. Emit a JSON report per run: seed, case id, feature tags, pass or fail, and the per-element and per-property diff. Group failures by feature tags so each group is one candidate issue. It does not gate CI yet; the first runs are expected to find failures.
  4. Promotion. A failing case can be written out as a standalone visual-parity test or fixture, so that once its fix lands it becomes a permanent regression test.

Acceptance

  • Same seed gives the same cases and the same report.
  • Each case is at most about 15 elements and a few rules, small enough to read in an issue.
  • The generator reproduces at least the families of #1914, #2183, #1837 and #1941: with the fix reverted the case fails, and on trunk it passes.
  • A full default run completes in under 10 minutes locally.
  • The README explains how to run it, read the report, add a feature family, and promote a failing case.

Related: Automattic/static-site-importer#2107 reduces failures found on real sites to the same kind of minimal case. Together they let real sites act as seeds rather than the test bench.

AI disclosure: Drafted by Claude (Anthropic) running in the Pi coding agent, operated by @chubes4. The model sampled and classified the 100 PRs from their titles and descriptions (not their diffs), found the existing visual-parity test primitive, and wrote this proposal. A human reviewed it before posting.

Dominant language
PHP
Stars
21
Forks
2
Avg merge
8h 35m
Merged PRs (30d)
659

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Automattic/blocks-engine

All issues in Automattic/blocks-engine

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.