Phase 05 M2: block-range locator and opt-in citation write routes

[dknauss]

Summary

What changed?

Phase 05, M2: the first REST routes that write bibliographies, as planned in the design memo (Tier 2).

1. Block-range locator (includes/block-locator.php)

• Finds each bibliography block's exact byte range in post_content. It uses WP_Block_Parser's delimiter grammar and the same document-order indexing as the read routes' {index}, so nested blocks are handled.
• Refuses malformed structure with 409: a stray closer, a mismatched closer, or a block left unclosed. A write never guesses where a block ends.
• Splices one block in place, then re-locates every block to prove that no other byte moved.
• Tested against a vendored copy of core's real WP_Block_Parser (tests/phpunit/wp-block-parser/, GPL, test-only), not the bootstrap's canned parse_blocks() mock. So it's checked on every push, not only in the runtime matrix.

2. Citation write routes (includes/write-routes.php)

The routes are off by default. A site opts in with add_filter( 'bibliography_builder_enable_write_routes', '__return_true' );, typically from an mu-plugin; this filter is the design memo's "companion-plugin flag". They live under /wp-json/bibliography/v1/posts/<id>/bibliographies/<ref>/citations:

Method	Path	Does
POST	…/citations	Add 1–50 CSL-JSON items. Duplicates, by the editor's rules, are skipped and reported.
PATCH	…/citations/<citation_id>	Change fields. null removes a field; id and type are locked. Works like the editor's field editor.
DELETE	…/citations/<citation_id>	Remove one citation. The response returns the whole entry, so it can be restored.
PUT	…/citations/order	Reorder. Numeric styles only; others return 409.

Every route:

• needs edit_post on the post;
• is a dry run unless dry_run=false;
• needs If-Match with the post's ETag to write: 428 without it, 412 when it's stale. The ETag is a hash of the content, not post_modified_gmt, so two saves in the same second can't collide.

A write rebuilds the block's markup with the PHP port of save(), splices only that block, and saves through wp_update_post() as an ordinary revision. While the routes are on, the read routes send the ETag.

Docs:

• docs/rest-write-routes.md: enabling, routes, responses, and caveats;
• the design memo (M2 marked done, with the decisions made);
• CLAUDE.md, the README, the CHANGELOG, and the metrics.

Why? The design memo's M2. Its prerequisites are now all on main: the PHP save() port (#97), locale-independent markup (#98, #99), and full citation styles (#103).

Known gap: BibTeX and BibLaTeX export strings need citation-js, so only the editor computes them. With per-entry Cite / Export on, entries written over REST show RIS and CSL-JSON links until the post is next saved in the editor, which then adds the missing strings. This is documented.

Validation

• composer test:php passes (310). It includes 9 locator tests against the real parser and 14 write-route tests. The route tests assert that every written block's markup is byte-identical to what save() renders for its attributes. The suite also passes with --order-by=random.

• composer lint:php and composer analyze:php pass.

• npm run lint:js and npm run test (872, also with --randomize) pass. No JS changed.

• verify-metrics.sh passes.

• Tested end to end in a real WordPress: Playground CLI 3.1.40, WordPress trunk, this build mounted, and the routes enabled by an mu-plugin. The steps ran through core's REST server with rest_do_request():

  • read the ETag;
  • dry-run an add (the post was unchanged);
  • 428 without If-Match, 412 with a stale one;
  • a real add, which skipped a duplicate within the same request;
  • PATCH, DELETE, and PUT on three different blocks;
  • PUT on an APA list returned 409;
  • 5 revisions were recorded.

  Afterwards the block editor loaded all 44 blocks as valid, with no unsaved changes and no page errors.

Checklist

• Linked issue or explained why none was needed: Phase 05 M2 in .planning/phases/05-writable-bibliography-rest/05-DESIGN-MEMO.md.
• 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 92.87305% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.20%. Comparing base (7fb1372) to head (674b964).

Files with missing lines	Patch %	Lines
includes/write-routes.php	91.32%	30 Missing ⚠️
includes/block-locator.php	97.75%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #104      +/-   ##
==========================================
+ Coverage   86.75%   87.20%   +0.45%     
==========================================
  Files          52       54       +2     
  Lines        5406     5847     +441     
  Branches      597      597              
==========================================
+ Hits         4690     5099     +409     
- Misses        235      267      +32     
  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.