perf(docs): lazy-load search and highlight code at build time

[FarhanAliRaza]

Summary

• lazy-load the Inkeep docs search widget while preserving its keyboard shortcut, accessible labels, and pixel-stable handoff
• discover literal docs code blocks during an automatic production prepass, highlight them once with pinned Shiki 3.3.0, and embed the generated HTML in the final prerendered pages
• keep the existing client Shiki component in development and for genuinely dynamic code values
• remove prose-only Markdown components from the introduction route so they do not pull a second syntax-highlighting runtime into that page

Production builds still use the normal reflex export path and normal eager React hydration. There is no performance selector, deferred-hydration bootloader, event replay, or Lighthouse matrix in this PR.

Build behavior

StaticShikiPlugin owns the production flow:

1. Run a guarded discovery compile to collect literal code/theme/language requests.
2. Write a deterministic, content-addressed manifest.
3. Install the checked-in frozen Shiki runtime and generate every highlighted block in one JavaScript process.
4. Run the normal production render against that cache, failing on missing, stale, or mismatched entries.
5. Remove the temporary manifest, cache, and runtime after the build.

Dynamic code blocks and local development retain the existing client-side behavior.

Validation

• standard frontend-only reflex export completed successfully with no wrapper command or feature flags
• production discovery generated 1,232 cached blocks; the introduction artifact contains nine static Shiki blocks and its route module has no Shiki or React Syntax Highlighter import
• browser smoke test confirmed correct dark-theme token colors, working hydrated tabs, and no hydration/page errors
• 383 passed, 1 skipped in the docs test suite
• 24 passed in the focused static-Shiki regression suite
• uv run ruff check .
• uv run ruff format --check .
• uv run pyright reflex tests
• uv run pre-commit run --all-files
• built the reflex-site-shared wheel and verified the generator plus frozen runtime files are included
• changelog fragment check passes

Tradeoffs

• production docs builds perform one additional page-evaluation pass before the final render
• only literal code is statically highlighted; dynamic code continues to use the client component

[greptile-apps]

Greptile Summary

This PR reduces initial docs hydration work and adds build-time code highlighting. The main changes are:

• Lazy-loaded Inkeep docs search with keyboard handoff.
• Static Shiki discovery, cache generation, and render-time HTML consumption.
• Production plugin wiring for the docs static highlighting pipeline.
• Docs page updates that avoid eager markdown and code highlighter paths.
• Accessibility labels for overlay links, copy buttons, inputs, and docs controls.
• Tests for the Inkeep search behavior and static Shiki cache flow.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
packages/reflex-site-shared/src/reflex_site_shared/static_shiki.py	Adds the static Shiki build phases, cache validation, and production plugin lifecycle.
packages/reflex-site-shared/src/reflex_site_shared/components/blocks/code.py	Routes literal docs code blocks through cached static Shiki HTML when available.
packages/reflex-site-shared/src/reflex_site_shared/_generate_static_shiki.mjs	Generates a deterministic Shiki HTML cache from the discovery manifest.
docs/app/reflex_docs/views/inkeep.py	Adds a lightweight search placeholder that mounts the Inkeep widget on user intent.
docs/getting_started/introduction.md	Replaces selected markdown rendering with static-friendly Reflex components.

_{Reviews (2): Last reviewed commit: "perf(docs): highlight literal code block..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing FarhanAliRaza:codex/docs-hydration-ab (11e22c4) with main (9a5c4d3)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩