Add chat panel persistence and improve pin button styling

- Persist chat panel state across page navigation using Astro View Transitions
- Add transition:persist wrapper to maintain React component instance
- Add subtle cross-fade animation (150ms) with reduced-motion support
- Fix pin button active state to match hover colors with deep-thinking bg
- Fix pin button icon size to match close button (14x14, strokeWidth 1.5)
- Fix border color reset bug when toggling pin state off
- Remove deprecated viewTransitions option from astro.config.mjs
- Add design document for chat panel persistence feature

Author: larkiny

astro.config.mjs

@@ -25,7 +25,6 @@ export default defineConfig({
   description:
     'The Algorand Developer Portal is the go-to resource for developers building on Algorand.',
   output: 'static',
-  viewTransitions: true,
   integrations: [
     starlight({
       title: 'Algorand Developer Portal',

docs/plans/2026-02-11-chat-panel-persistence-design.md

@@ -0,0 +1,151 @@
+# Chat Panel Persistence Design
+
+This document describes the implementation of persistent chat panel state across page navigation in the Algorand Developer Portal.
+
+## Problem
+
+Currently, when users navigate to a different page (including clicking source links in AI chat responses), the chat panel's React component unmounts and remounts, losing:
+
+- The current conversation with the AI
+- Scroll position in the chat
+- Any in-progress AI responses
+
+This creates a frustrating experience, especially when the AI provides links to documentation pages that the user wants to explore while maintaining their chat context.
+
+## Solution
+
+Use Astro View Transitions with `transition:persist` to keep the chat panel React component mounted across page navigations.
+
+## Architecture
+
+```
+Page A                          Page B
+┌─────────────────────┐        ┌─────────────────────┐
+│  ┌───────────────┐  │        │  ┌───────────────┐  │
+│  │ Main Content  │  │ ────── │  │ Main Content  │  │
+│  └───────────────┘  │ fade   │  └───────────────┘  │
+│  ┌───────────────┐  │        │  ┌───────────────┐  │
+│  │  Chat Panel   │ ═══════════  │  Chat Panel   │  │ ← persisted
+│  │  (React)      │  │ stays  │  │  (same inst.) │  │
+│  └───────────────┘  │ alive  │  └───────────────┘  │
+└─────────────────────┘        └─────────────────────┘
+```
+
+- Main page content cross-fades between pages (~150ms animation)
+- Chat panel wrapper is marked with `transition:persist` - same React instance survives
+- Kapa SDK context and conversation state are naturally preserved
+- No serialization/deserialization of state needed
+
+## Persistence Level
+
+**Within-session persistence**: The conversation stays alive as long as the browser tab is open. It survives page navigation but not tab close/refresh. This matches user expectations - chat context is maintained while browsing, but a fresh session starts when returning later.
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| `src/components/CustomThemeProvider.astro` | Add `<ViewTransitions />` and wrap chat panel with `transition:persist` |
+| `src/styles/global.css` | Add View Transitions timing/easing CSS |
+| `astro.config.mjs` | Remove deprecated `viewTransitions: true` option |
+
+## Implementation Details
+
+### CustomThemeProvider.astro
+
+```astro
+---
+import Default from '@astrojs/starlight/components/ThemeProvider.astro';
+import AIChatPanel from './AIChatPanel.tsx';
+import { ViewTransitions } from 'astro:transitions';
+---
+
+<Default {...Astro.props}><slot /></Default>
+
+<!-- View Transitions enabled site-wide -->
+<ViewTransitions />
+
+<!-- Chat panel persists across navigation -->
+<div transition:persist="ai-chat-panel">
+  <AIChatPanel client:only='react' />
+</div>
+```
+
+### global.css additions
+
+```css
+/* ——— View Transitions ——— */
+
+/* Subtle cross-fade for page content */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation-duration: 150ms;
+  animation-timing-function: ease-out;
+}
+
+/* Chat panel doesn't animate during transitions (it persists) */
+::view-transition-old(ai-chat-panel),
+::view-transition-new(ai-chat-panel) {
+  animation: none;
+}
+
+/* Respect reduced motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(root),
+  ::view-transition-new(root) {
+    animation: none;
+  }
+}
+```
+
+### astro.config.mjs cleanup
+
+Remove the deprecated option:
+
+```diff
+export default defineConfig({
+  site: 'https://dev.algorand.co',
+  output: 'static',
+- viewTransitions: true,
+  integrations: [
+```
+
+## Edge Cases & Considerations
+
+### `chat-pinned` class on `<html>`
+
+When View Transitions swap pages, the `<html>` element is replaced. The React component's `useEffect` that manages the `chat-pinned` class will re-run after navigation, so the pinned layout state should self-heal. This needs verification during testing.
+
+### Backdrop behavior during transitions
+
+The backdrop overlay (when chat is open in floating mode) is part of the persisted component, so it should remain visible during transitions. No special handling needed.
+
+### Browser compatibility
+
+View Transitions are supported in:
+- Chrome 111+ (March 2023)
+- Edge 111+
+- Opera 97+
+- Safari 18+ (September 2024)
+- Firefox: Behind flag, not yet default
+
+For unsupported browsers, navigation falls back to standard full-page loads. The chat state will be lost in these cases, which is acceptable degradation.
+
+## Testing Plan
+
+1. Open chat panel and start a conversation
+2. Click a sidebar navigation link → verify conversation persists
+3. Click a source link in an AI response → verify conversation persists
+4. Test with chat pinned → verify pinned layout persists correctly
+5. Test the page transition animation looks smooth
+6. Test on mobile viewport
+7. Test with `prefers-reduced-motion` enabled
+
+## Rollback Plan
+
+If View Transitions cause issues:
+1. Remove `<ViewTransitions />` from CustomThemeProvider.astro
+2. Remove the `transition:persist` wrapper
+3. Remove View Transitions CSS from global.css
+4. Restore `viewTransitions: true` in astro.config.mjs (if needed for other reasons)
+
+The chat panel will revert to its previous behavior (state lost on navigation).

src/components/ChatInterface.tsx

@@ -193,19 +193,22 @@ export default function ChatInterface({ canPin = false }: ChatInterfaceProps) {
           {canPin && (
             <button
               onClick={toggleChatPinned}
-              className='chat-panel-btn'
-              style={styles.headerBtn}
+              className={isPinned ? '' : 'chat-panel-btn'}
+              style={{
+                ...styles.headerBtn,
+                ...(isPinned ? styles.pinBtnActive : {}),
+              }}
               title={isPinned ? 'Unpin panel' : 'Pin panel'}
             >
               {isPinned ? (
                 // Unpinned icon (floating mode)
                 <svg
-                  width='16'
-                  height='16'
+                  width='14'
+                  height='14'
                   viewBox='0 0 24 24'
                   fill='none'
                   stroke='currentColor'
-                  strokeWidth='2'
+                  strokeWidth='1.5'
                   strokeLinecap='round'
                   strokeLinejoin='round'
                 >
@@ -215,12 +218,12 @@ export default function ChatInterface({ canPin = false }: ChatInterfaceProps) {
               ) : (
                 // Pinned icon (docked mode)
                 <svg
-                  width='16'
-                  height='16'
+                  width='14'
+                  height='14'
                   viewBox='0 0 24 24'
                   fill='none'
                   stroke='currentColor'
-                  strokeWidth='2'
+                  strokeWidth='1.5'
                   strokeLinecap='round'
                   strokeLinejoin='round'
                 >
@@ -582,10 +585,16 @@ const styles: Record<string, React.CSSProperties> = {
     padding: 0,
     background: 'var(--sl-color-gray-6)',
     border: '1px solid var(--sl-color-gray-5)',
+    borderColor: 'var(--sl-color-gray-5)', // Explicit to properly reset after active state
     color: 'var(--sl-color-gray-3)',
     cursor: 'pointer',
     borderRadius: '0.375rem',
-    transition: 'border-color 0.15s, color 0.15s',
+    transition: 'border-color 0.15s, color 0.15s, background 0.15s',
+  },
+  pinBtnActive: {
+    color: '#01DC94',
+    borderColor: '#01DC94',
+    background: 'rgba(255, 127, 72, 0.15)',
   },
   messages: {
     flex: 1,

src/components/CustomThemeProvider.astro

@@ -1,6 +1,7 @@
 ---
 import Default from '@astrojs/starlight/components/ThemeProvider.astro';
 import AIChatPanel from './AIChatPanel.tsx';
+import { ViewTransitions } from 'astro:transitions';
 ---
 
 <script is:inline>
@@ -13,4 +14,11 @@ import AIChatPanel from './AIChatPanel.tsx';
 </script>
 
 <Default {...Astro.props}><slot /></Default>
-<AIChatPanel client:only='react' />
+
+<!-- View Transitions enabled site-wide for smooth page navigation -->
+<ViewTransitions />
+
+<!-- Chat panel persists across navigation to maintain conversation state -->
+<div transition:persist="ai-chat-panel">
+  <AIChatPanel client:only='react' />
+</div>

src/styles/global.css

@@ -418,3 +418,26 @@ html.chat-pinned .main-pane {
     display: none !important;
   }
 }
+
+/* ——— View Transitions ——— */
+
+/* Subtle cross-fade for page content */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation-duration: 150ms;
+  animation-timing-function: ease-out;
+}
+
+/* Chat panel doesn't animate during transitions (it persists) */
+::view-transition-old(ai-chat-panel),
+::view-transition-new(ai-chat-panel) {
+  animation: none;
+}
+
+/* Respect reduced motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(root),
+  ::view-transition-new(root) {
+    animation: none;
+  }
+}