Mandate ledger — 2026-07-22 · screenshots · throttling · void/catch-all · publishing · README

Per the "Owner Mandates Become Ledgers" standing instruction in CLAUDE.md: the owner's words are transcribed verbatim, one row per clause. Completion is claimed row by row, never in summary. A clause that never became a row is the root failure mode this file exists to prevent.

Source: owner message, 2026-07-22 (single message, Cowork session). Follow-up answers via AskUserQuestion are recorded in Clarifications.

Ledger

Second message, 2026-07-22 — the platform matrix

Fifth message, 2026-07-22 — Fabric 1.21.x, and screenshots handed off

Answer to C40, recorded because it is the design premise. Yes. Client and server on the same Minecraft version share the network protocol, and this bridge is an ordinary vanilla custom-payload packet — so a Fabric 1.21.x client talks to a Paper 1.21.x server natively. Two things it does not mean: (1) they share no code — Fabric compiles against the deobfuscated client via Yarn, the plugin against the Bukkit API, so only bytes can cross, which is why the protocol is plain text; (2) 1.21.x is one API for the plugin (api-version: '1.21', whole line) but not one protocol for a client, which can only join a server of its exact version. Hence the mod is built per version — one line in client/fabric/gradle.properties.

Fourth message, 2026-07-22 — no wands, client-side interface, and honesty about screenshots

Verdict on automated screenshots (C38). The owner's instinct is right, with one correction. The harness works: CI boots a real server with the real plugin, drives eight scripted scenes, and writes eight PNGs. What does not work is the headless renderer. prismarine-viewer prerenders its block textures when the npm package is published, is not maintained in step with Minecraft releases, and fails silently because its mesher runs in a Web Worker. Five cycles found and fixed four real problems (a missing dependency, a wrong API call, a version mismatch, and mineflayer's physics overriding every camera teleport) and it still draws nothing.

So: the browser-renderer path is judged a dead end and should not receive more time. Two things are worth keeping instead:

1. The scene script is the valuable part, and it is renderer-independent. It builds every scene, positions the camera and fires the despawns. Pointing it at a real client — the client backend, already scaffolded — reuses all of it, and is the only way to photograph particles anyway (clause C3).
2. A manual capture mode is a legitimate answer. scripts/local-playtest.ps1 already boots a local server the owner can join. Adding a flag that builds the same eight scenes and then waits means the owner joins, presses F2 eight times, and drops the files in — repeatable, scripted, and honest about the one step a human does.

Recommendation: try the client backend once; if it also proves fragile, ship manual capture with the scripted scenes and stop pretending otherwise.

Third message, 2026-07-22 — the in-world toggle button

Design decision for C25 (recorded because it reinterprets "client targets"). The button is built server-side, using vanilla-visible Interaction + TextDisplay entities and a chest GUI. Reasoning: a client mod that does not exist yet cannot ship a button, whereas a server-side control works today for every player — vanilla, Fabric, NeoForge, or any modpack — with nothing to install and no version-lock between client and server. The client-mod path is not abandoned: C28 is satisfied by a documented plugin-messaging channel that a future client mod (or any third-party mod) can use to render a richer UI over the same state.

Clarifications

Asked via AskUserQuestion, 2026-07-22, before execution:

Phases

Not-done list (S9)

1. The captured frames are blank — blocked-with-evidence (C1, C2, C3, C6)

The harness is built, wired into CI and Docs, and runs green end to end: it boots Paper 1.21.11 with the plugin, joins with the director bot, builds all eight scenes, and writes eight PNGs plus a manifest. But every frame is bare sky. Files existing is not screenshots working, so this is recorded as blocked, not done, and the job fails itself via a blank-frame guard rather than publishing empty art.

What has been ruled OUT (each by a real CI run, not by reasoning):

Second investigation round (runs 29952521790 → 29954038565). Three more causes found and fixed, one of them a genuine bug:

Where it stands after all of that: frames are still byte-identical. Since the camera is now demonstrably in the right places, the camera is ruled out and the remaining cause is squarely the browser scene renders nothing. Note also that the canvas pixel probe reports distinctColours:1, first:"0,0,0" — a WebGL canvas read back through drawImage without preserveDrawingBuffer cannot see the scene, so that probe is inconclusive by construction; puppeteer's own screenshot goes through the compositor and remains the source of truth.

Two ways forward, in order of cost:

1. Walk the version back further. prismarine-viewer 1.33.0's asset range may not reach 1.21.4 either. mcVersion is a workflow input, so trying 1.20.4 and then 1.19.4 is a one-word change per run and needs no code. If a version renders, the harness is finished.
2. Switch to the client backend. A real Minecraft client under Xvfb does not depend on prismarine-viewer at all, and it is the only backend that can photograph particles — which is clause C3, the thing the owner asked for first. The scaffold already exists (clientBackend() + the Xvfb/ffmpeg install step, gated on engine: client). Given that the viewer path has now cost five cycles and still cannot draw a block, this is probably the better investment.

What is still open, with the next probe for each:

1. bot.entity.position.y is pinned at -59.0 in every frame even though the director is /tped to y+6 (and to y+8 for the load shot). X and Z track correctly. So either mineflayer is not applying the vertical component of a server teleport, or the server is snapping the spectator to the surface. Either way the camera may be sitting in the terrain. Probe: log bot.entity.position immediately after each /tp, and use bot.waitForTicks + an explicit bot.entity.position.set() or a /tp with rotation (/tp <x> <y> <z> <yaw> <pitch>) instead of lookAt.
2. prismarine-viewer's browser scene may simply never receive geometry. Probe: in page.evaluate, read window.viewer?.world / count scene.children and log it. That single number distinguishes "no data" from "data present but not drawn" and should be the very next thing tried — it is ~10 lines and one CI cycle.
3. Fallback if the viewer proves unworkable: the client backend (real Minecraft under Xvfb) is already scaffolded and is the only backend that can photograph particles anyway. Switching effort there may be a better use of the next cycle than debugging a renderer we do not control.

2. Not attempted this session

• The v1.5.0 release itself — everything is on dev; no PR into main, no tag, no back-merge. Deliberate: shipping a release whose headline feature produces blank images would be shipping a lie.
• Folia (C21/C22) — planned in detail in platform-targets.md, not built. Needs a PlatformScheduler plus a shared-state audit that v1.5.0's throttle maps enlarged.
• Fabric / NeoForge / Sponge / Quilt / Velocity editions (C21/C22) — each is a separate implementation; core/ extraction is the prerequisite and is itself a full session.
• Paper API deprecation warnings — pre-existing in DespawnBlockIntoAir, DespawnIntoCooker, DespawnIntoVoid. They violate the ship contract's "no deprecation warnings left to rot" clause and should be cleared before v1.5.0 is tagged.
• Modrinth / CurseForge / Hangar projects — the workflows are written and gated on token secrets, but nothing can publish until the owner creates the projects and adds the secrets/variables (listed at the end of platform-targets.md).