Implement custom Kapa support handoff chat with polished codeblock UX

.env.example

@@ -4,11 +4,19 @@
 # Values below are PUBLIC (they're shipped to the browser by Astro's
 # `envField`, and live behind rate limiting / allow-lists on the vendor side).
 
-# Kapa Custom Frontend integration ID for the "Ask AI" button in the header.
-# If unset, the Ask AI button is hidden and the site still runs normally.
-# Get yours at: https://app.kapa.ai/admin
+# Kapa Website Widget integration ID for the "Ask AI" button in the sidebar.
+# If unset, docs falls back to the shared widget integration ID used in preview/prod.
+# Get yours at: https://app.kapa.ai/admin (Integrations → Widget → Copy integration ID).
+# The same value is passed to the widget as `data-website-id`.
+# PUBLIC_KAPA_INTEGRATION_ID=f31c5644-dd65-4f49-9762-bf580062afa8
 PUBLIC_KAPA_INTEGRATION_ID=
 
+# Optional Kapa project ID used to build internal conversation links in
+# "Create ticket" email drafts:
+#   https://app.kapa.ai/<PROJECT_ID>/conversations/<THREAD_ID>
+# You can find this in the Kapa dashboard URL while viewing the project.
+PUBLIC_KAPA_PROJECT_ID=
+
 # RudderStack analytics — required for docs_404 event tracking and page analytics.
 # Without these, no analytics events are sent and the weekly 404 monitor will
 # report zero data. Set both in the Vercel project environment (all environments).
@@ -21,3 +29,12 @@ PUBLIC_KAPA_INTEGRATION_ID=
 #   directive in vercel.json (a mismatch silently blocks all events in the browser).
 PUBLIC_RUDDERSTACK_WRITE_KEY=
 PUBLIC_RUDDERSTACK_DATA_PLANE_URL=
+
+# Server-side handoff forwarding endpoint used by /api/support-handoff.
+# This should point at the DevX service endpoint that creates Front
+# conversations from docs chat handoff requests.
+SUPPORT_HANDOFF_ENDPOINT_URL=
+
+# Optional shared secret sent as an authorization bearer token when
+# forwarding to SUPPORT_HANDOFF_ENDPOINT_URL.
+SUPPORT_HANDOFF_SHARED_SECRET=

astro.config.mjs

@@ -28,6 +28,11 @@ export default defineConfig({
 				access: 'public',
 				optional: true,
 			}),
+			PUBLIC_KAPA_PROJECT_ID: envField.string({
+				context: 'client',
+				access: 'public',
+				optional: true,
+			}),
 			PUBLIC_RUDDERSTACK_WRITE_KEY: envField.string({
 				context: 'client',
 				access: 'public',
@@ -43,6 +48,16 @@ export default defineConfig({
 				access: 'public',
 				optional: true,
 			}),
+			SUPPORT_HANDOFF_ENDPOINT_URL: envField.string({
+				context: 'server',
+				access: 'secret',
+				optional: true,
+			}),
+			SUPPORT_HANDOFF_SHARED_SECRET: envField.string({
+				context: 'server',
+				access: 'secret',
+				optional: true,
+			}),
 		},
 	},
 	integrations: [
@@ -61,15 +76,24 @@ export default defineConfig({
 				baseUrl: 'https://github.com/warpdotdev/docs/edit/main/',
 			},
 			lastUpdated: true,
-			// Soft-wrap long lines by default. Expressive Code defaults to
-			// `overflow-x: auto` for `<pre>`, which combined with macOS's
-			// auto-hidden scrollbars made wide lines silently truncate.
-			// `wrap: true` adds the `.wrap` class so EC's `white-space: pre-wrap`
-			// kicks in; leading indents are preserved via its `span.indent` rule.
+			// Keep long lines unwrapped so code blocks use horizontal scrolling.
+			// This aligns docs behavior with the side chat renderer and preserves
+			// exact line shape for commands and snippets.
 			expressiveCode: {
 				defaultProps: {
-					wrap: true,
+					wrap: false,
 				},
+				// IMPORTANT: Expressive Code's Vite plugin rewrites Shiki's bundled
+				// theme registry (shiki/dist/themes.mjs) and strips every theme not
+				// listed as a *string* in its `themes` config. Starlight passes its
+				// themes as objects, so the registry is emptied for the entire Vite
+				// module graph — including the Kapa side-chat island, whose runtime
+				// createHighlighter(['github-light', 'github-dark']) then throws
+				// "theme is not included in this bundle" and falls back to plaintext.
+				// Keeping the registry intact restores chat code block highlighting.
+				// Only the requested themes are ever fetched at runtime (lazy chunks),
+				// so this does not bloat the pages served to visitors.
+				removeUnusedThemes: false,
 				// Map languages Shiki doesn't bundle to a safe fallback. PromQL
 				// blocks live in platform/self-hosting/monitoring.mdx;
 				// without this alias every build emits noisy "language could not be