Sharpen codeblock-ownership.md with what changed since August - #18
Merged
Merged
Conversation
… nothing new docs/architecture/codeblock-ownership.md already decided this on 2026-08-13 and already told Razor consumers to render escaped source with an app-owned pre-highlighting option. What it didn't have was confirmation of its own reconsideration criterion 2 -- "highlighting ownership for browser, Node SSR, and PHP is explicit." Browser and Node SSR are answered now, and weren't obvious in August: VfCodeBlock already calls onServerPrefetch, and Shiki's engine/javascript avoids WASM entirely, so highlighting runs in Node today without a browser. PHP stays open on purpose. Checked rather than assumed: no native PHP engine reproduces Shiki's output. The one established integration, spatie/shiki-php, shells out to a real Node process per render rather than reimplementing the engine -- which is exactly the "two engines obliged to agree" risk the icon-line decision escaped by precomputing, except an arbitrary code string has nothing to precompute. The realistic PHP-side choice is between that Node dependency and progressive enhancement (escaped markup, a client controller adds color, a flash of unhighlighted text is the unavoidable cost since there is nothing to precompute). Progressive enhancement is named as the likely direction because it matches everything else this migration built; it is not adopted here as a decision, since no real Razor consumer has asked for it yet. Also removed the same stale check:frozen-showcase acknowledgement fixed on the still-unmerged playground-ownership branch -- this branch forked from main before that landed, and it blocks verify here too.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What and why
The last unread item, deferred the same way as Playground: recorded and left open rather than implemented.
docs/architecture/codeblock-ownership.mdalready decided this on 2026-08-13 — this strengthens that document, it doesn't replace it (see #17 for why that distinction matters: the first attempt at the Playground write-up made exactly the mistake of not checking for an existing decision first).What's actually new here
The existing document's reconsideration criterion 2 — "highlighting ownership for browser, Node SSR, and PHP is explicit" — was an open checkbox nobody had answered since August. Two thirds of it are answered now, checked rather than assumed:
Browser and Node SSR: confirmed.
VfCodeBlockalready callsonServerPrefetch, and Shiki'sengine/javascriptavoids the WASM Oniguruma engine entirely — highlighting already runs in Node today, no browser required.PHP: still open, and the reason is worth recording. No native PHP engine reproduces Shiki's output. The one established integration,
spatie/shiki-php, doesn't reimplement the engine — it shells out to a real Node process per render. That's the exact "two engines obliged to agree" risk the icon-line decision escaped by precomputing every combination once; it doesn't apply the same way here becausecodeis arbitrary per-request text, not a fixed set of things to precompute.So the realistic PHP-side choice is between:
spatie/shiki-phpdoes), orProgressive enhancement is named as the likely direction, because it's the one consistent with every other adapter in this line. It is not adopted as a decision — no real Razor consumer has asked for this yet, and criteria 1, 3, 4, and 5 in the existing document remain entirely unaddressed.
Also fixed
The
check:frozen-showcaseacknowledgement removed on the still-unmerged #17 was blockingverifyhere too — this branch forked frommainbefore that landed. Same one-line fix, applied here as well; no conflict expected when both land.Checks
npm run verifypasses in full.