docs: engrave music on a page

[lens0021]

Requested by lens0021 · project thread

Score is the fourth extension this site documents and the second of Chart's kind: it wants a program of its own beside the bake. It does not run LilyPond itself — it sends the command to a Shellbox, which is what its own message asks for, since LilyPond has had no safe mode since 2.23.12 and a <score> is a program it will run.

This is the Score half of the original #796. The "let a bake reach more than one service" capability was split into #798, which has since merged; this branch is rebased onto main and is now Score-only, a single commit.

The Shellbox comes from upstream

Wikimedia already publishes one. mediawiki-libs-shellbox builds a score83 flavour — LilyPond from bookworm-backports, Ghostscript, ImageMagick, and the Noto fonts lyrics want — and runs it as the shellbox service in operations/deployment-charts. This takes that image and lets them keep it up to date, rather than wikven maintaining a Dockerfile full of LilyPond.

It is php-fpm alone, so it speaks FastCGI rather than HTTP and upstream puts an httpd in front of it. A services.json entry can name an image to pull and a sidecar to run in the service's own network namespace — which is how the two share a localhost in a pod. One address still reaches the pair.

An entry may also name a probe, and naming one means that path has to answer 200 rather than merely answer. An httpd says 502 on its own while what is behind it is still starting, and /healthz reaches Shellbox through the whole chain, so it is the readier signal.

Two quiet failures, documented

Both send the build down the local path, where a bake has no LilyPond, so the page fills with an error instead of music:

• The key under ShellboxUrls is score, the service. It is not score-lilypond, which is the route.
• ShellboxSecretKey is not optional even though MediaWiki lets it be: without it, getUrl() returns null and the command runs locally.

A score that cannot be engraved is published as an error box with the build none the wiser, as a chart was, so score-error-category joins WikvenFailOnCategories.

Checks

• The bake sends four requests to the Shellbox, and the page comes back with an <svg> and a PNG beside it, both files the build wrote.
• Broken on purpose: the ShellboxUrls route name, then the missing secret — each sent the work back to the local path with nothing said, which is what the page now warns about.
• All 28 bake assertions pass, verified end to end in CI: the upstream image pulled, the sidecar attached, /healthz answered, and the two bakes stayed byte-identical.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HnGL1B3zcDSmmc9XBAPcWg

[claude]

smoke is red on main too, with the same failure → it is flaky, and the re-run is green

Update: the re-run of smoke on this same commit (f88ca55) passed, and the PR is now mergeable_state: clean. So the test is flaky, not deterministically broken — my note below that it would "reproduce rather than flake" was wrong, and the record is corrected here rather than rewritten. The rest of the evidence still stands and is worth keeping, because the flake is real and recurring.

---

The one red check was smoke, failing in the browser step, not in anything this PR touches:

tests/e2e/citizen.spec.js:168:1 › Citizen's view-source tab is a button a reader can hit
Error: expect(received).toBeGreaterThanOrEqual(expected)
Expected: >= 703.8000000000001
Received:    0
> 195 | expect(box.width).toBeGreaterThanOrEqual(history.width * 0.9);

It hit main the same way, with byte-identical numbers, on both of the commits merged just before this branch was pushed:

run	commit	branch	smoke
35605660336	901f543	main	success
35606042296	73c8ddc (#794)	main	failure — same test, same numbers
35606877813	913d4f6 (#793)	main	failure — same test, same numbers
35607717340	f88ca55	this PR	failure, then success on re-run of the same commit

The pin this branch carries for the skin is the older one — Citizen: v3.22.0, since this branch predates #794's bump to v3.23.0 — and it failed exactly as main did on v3.23.0, so the skin bump was not the trigger either.

What this PR changes is green. From the run's log:

• 28 of 28 checks passed, 0 failed, 0 skipped — including the new scores check, which asserts the engraving is in the page rather than Score's error box.
• Two bakes of the same source are byte-identical.
• 64 of the 65 browser tests passed even on the red run; the one failure was the one above.

Four failures across three different commits, one of which then passed unchanged, is a flake worth fixing on its own rather than re-running past. box.width reads 0 while the same tab's href and icon mask both assert fine, which points at the measurement landing before the skin has finished laying the page actions out — boundingBox() is taken immediately after an attribute assertion, with no wait for a settled layout. That belongs in its own change, not in this diff.

---

Generated by Claude Code