Phase 05 M3: block settings and reformat write routes

[dknauss]

Summary

What changed?

This adds Tier 3 of the writable REST design. M2 already shipped reorder and ETag, so M3 is these two routes. Both sit behind the same bibliography_builder_enable_write_routes filter and follow M2's rules: edit_post, dry run by default, and If-Match required. They use M2's write path too: the PHP port of save() rebuilds the markup, the change is spliced into only that block, and a check confirms nothing else in the post changed.

• PATCH /posts/{id}/bibliographies/{ref} changes block settings: headingText, outputJsonLd, outputCoins, outputCslJson, and outputCiteExport.

  • Citations are not touched.
  • An unknown setting or a wrong type gets 400.
  • A setting sent with its block.json default is left out of the block comment, the same way the editor's serializer drops it.
  • citationStyle is refused (400, bibliography_builder_style_needs_reformat), because a style change without reformatting would leave every entry in the old style.

• POST /posts/{id}/bibliographies/{ref}/reformat with { "style": "<key>" } mirrors the editor's handleCitationStyleChange:

  • it formats every entry in the new style, 50 at a time (the /format limit), up to the editor's 200-citation cap;
  • it keeps manual display text and the BibTeX and BibLaTeX export strings;
  • it stores entries in the new style's display order;
  • a heading still set to the old style's default becomes the new style's default. A PHP copy of the style registry's headingPlaceholder supplies those defaults, and a drift test pins it to the JS registry.
  • The stored CSL-JSON is untouched. Entries the formatter can't use fail the whole request with 409, listed in data.entries.

• Runtime smoke: every matrix cell now sends a real settings PATCH and a real reformat to APA over HTTP. It then checks:

  • the APA text on the text route;
  • the new heading and COinS on the front end;
  • that the block's markup still matches save().

  The PATCH shares its path with the public GET read route, so this also proves WordPress falls through to it (match_request_to_handler skips a route with no handler for the method).

• Dev Playground: borgesWrite.settings() and borgesWrite.reformat().

• Docs: docs/rest-write-routes.md (now "Bibliography write routes"), the README, CLAUDE.md, the CHANGELOG, the design memo (M3 status and how it differs from the sketch), the roadmap, and the metrics (PHP line count).

Why? It was requested ("start m3"), and it's the next milestone in the Phase 05 sequencing table. It also clears the M0–M3 blocker on write abilities (M5).

Validation

• npm run lint:js passes
• npm run lint:css: no CSS changes
• npm run lint:i18n passes (new PHP strings)
• npm run test passes (873)
• npm run build: no JS source changes
• composer test:php (318 tests), composer lint:php, Psalm, and verify-metrics.sh pass.
• PHPUnit covers:
  • settings, including the default-omission and 400 cases;
  • reformat from IEEE to APA (re-sorted, the other block untouched, markup equal to save());
  • override, export, and heading preservation (Chicago → ABNT → Chicago);
  • a 60-entry reformat across the 50-item chunks;
  • a citation with no ID;
  • bad styles and a 409 for entries it can't format;
  • the heading drift check.
• Tested in the block editor. The Docker matrix's new steps run in this PR's CI, and the dev blueprint picks up the new helpers from main after merge.

Checklist

• Linked issue or explained why none was needed: requested directly (Phase 05 M3).
• No sensitive details disclosed publicly

🤖 Generated with Claude Code

https://claude.ai/code/session_01KbVuMPN7YTcV27vwsG3LZ2

---

Generated by Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 93.75000% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.39%. Comparing base (ebef50c) to head (aaf7fdc).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
includes/write-routes.php	93.75%	11 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #106      +/-   ##
==========================================
+ Coverage   87.20%   87.39%   +0.18%     
==========================================
  Files          54       54              
  Lines        5847     6021     +174     
  Branches      597      597              
==========================================
+ Hits         5099     5262     +163     
- Misses        267      278      +11     
  Partials      481      481              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.