Skip to content

Sharpen codeblock-ownership.md with what changed since August - #18

Merged
KolesnikovKirill merged 1 commit into
mainfrom
docs/codeblock-line-ownership
Sep 4, 2026
Merged

KolesnikovKirill merged 1 commit into
mainfrom
docs/codeblock-line-ownership

Conversation

@KolesnikovKirill

Copy link
Copy Markdown
Member

What and why

The last unread item, deferred the same way as Playground: recorded and left open rather than implemented. docs/architecture/codeblock-ownership.md already 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. VfCodeBlock already calls onServerPrefetch, and Shiki's engine/javascript avoids 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 because code is arbitrary per-request text, not a fixed set of things to precompute.

So the realistic PHP-side choice is between:

  • a hard Node.js runtime dependency in Razor (what spatie/shiki-php does), or
  • progressive enhancement — Razor renders escaped, working markup (already what "Consumer guidance" in the existing doc prescribes), a controller adds color client-side via Shiki's browser bundle, and a flash of unhighlighted text is the unavoidable cost since there's nothing to precompute.

Progressive 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-showcase acknowledgement removed on the still-unmerged #17 was blocking verify here too — this branch forked from main before that landed. Same one-line fix, applied here as well; no conflict expected when both land.

Checks

npm run verify passes in full.

… 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.
@KolesnikovKirill
KolesnikovKirill merged commit 733417e into main Sep 4, 2026
9 checks passed
@KolesnikovKirill
KolesnikovKirill deleted the docs/codeblock-line-ownership branch September 4, 2026 12:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant