feat(frontend): add runtime-configurable loading tips with branded dots (#817)

## Summary
- Replace joke loading messages with educational tips about ACP features
- Add 4 branded loading dots (#0066B1, #522DAE, #F40000, white) at 2x
size
- Make tips runtime-configurable via `LOADING_TIPS` environment variable
- Add markdown link support in tips using `[text](url)` syntax

## Changes
- **New API endpoint**: `/api/config/loading-tips` serves tips from env
var with fallback
- **New hook**: `useLoadingTips()` with React Query caching (staleTime:
Infinity)
- **Shared constants**: `lib/loading-tips.ts` for default tips
- **Updated LoadingDots**: 4 colored dots, markdown link parsing,
improved contrast

## Configuration
Set `LOADING_TIPS` env var as JSON array:
```bash
LOADING_TIPS='["Tip: First tip", "Tip: Second tip", "[Link text](https://example.com)"]'
```

Or use a ConfigMap (example in artifacts folder).

## Test plan
- [ ] Verify loading dots appear during AI response generation
- [ ] Verify tips rotate every 8 seconds
- [ ] Test with `LOADING_TIPS` env var set to custom JSON
- [ ] Test markdown links render as clickable
- [ ] Verify fallback to defaults when env var not set

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Ambient Code Bot <bot@ambient-code.local>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 3 people

components/frontend/.env.example

@@ -42,6 +42,11 @@ IMAGE_COMPRESSION_TARGET=358400
 # This is only used for strategy constraints that check context.environment.
 # NEXT_PUBLIC_UNLEASH_ENV_CONTEXT_FIELD=development
 
+# Loading tips shown during AI response generation (optional)
+# JSON array of strings. If not set, defaults to built-in tips.
+# Example: LOADING_TIPS='["Tip: First tip here", "Tip: Second tip here"]'
+# LOADING_TIPS=
+
 # Langfuse Configuration for User Feedback
 # These are used by the /api/feedback route to submit user feedback scores
 # Get your keys from your Langfuse instance: Settings > API Keys

components/frontend/src/app/api/config/loading-tips/route.ts

@@ -0,0 +1,20 @@
+import { env } from '@/lib/env';
+import { DEFAULT_LOADING_TIPS } from '@/lib/loading-tips';
+
+export async function GET() {
+  let tips = DEFAULT_LOADING_TIPS;
+
+  if (env.LOADING_TIPS) {
+    try {
+      const parsed = JSON.parse(env.LOADING_TIPS);
+      if (Array.isArray(parsed) && parsed.length > 0 && parsed.every(t => typeof t === 'string')) {
+        tips = parsed;
+      }
+    } catch {
+      // Invalid JSON, fall back to defaults
+      console.warn('LOADING_TIPS environment variable contains invalid JSON, using defaults');
+    }
+  }
+
+  return Response.json({ tips });
+}

components/frontend/src/components/ui/message.tsx

@@ -6,6 +6,8 @@ import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import type { Components } from "react-markdown";
 import { formatTimestamp } from "@/lib/format-timestamp";
+import { useLoadingTips } from "@/services/queries/use-loading-tips";
+import { DEFAULT_LOADING_TIPS } from "@/lib/loading-tips";
 
 export type MessageRole = "bot" | "user";
 
@@ -97,39 +99,78 @@ const defaultComponents: Components = {
   ),
 };
 
-const LOADING_MESSAGES = [
-  "Pretending to be productive",
-  "Downloading more RAM",
-  "Consulting the magic 8-ball",
-  "Teaching bugs to behave",
-  "Brewing digital coffee",
-  "Rolling for initiative",
-  "Surfing the data waves",
-  "Juggling bits and bytes",
-  "Tipping my fedora",
-  "Reticulating splines",
-];
+/**
+ * Parse markdown-style links [text](url) in a string and return React elements
+ */
+function parseMarkdownLinks(text: string): React.ReactNode {
+  const linkRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
+  const parts: React.ReactNode[] = [];
+  let lastIndex = 0;
+  let match;
+
+  while ((match = linkRegex.exec(text)) !== null) {
+    // Add text before the link
+    if (match.index > lastIndex) {
+      parts.push(text.slice(lastIndex, match.index));
+    }
+    // Validate URL scheme to prevent javascript: injection
+    const href = match[2];
+    const isSafeUrl = href.startsWith('https://') || href.startsWith('http://');
+    // Add the link (or plain text if URL is unsafe)
+    parts.push(
+      isSafeUrl ? (
+        <a
+          key={match.index}
+          href={href}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="text-primary hover:underline"
+        >
+          {match[1]}
+        </a>
+      ) : (
+        <span key={match.index}>{match[1]}</span>
+      )
+    );
+    lastIndex = match.index + match[0].length;
+  }
+
+  // Add remaining text after last link
+  if (lastIndex < text.length) {
+    parts.push(text.slice(lastIndex));
+  }
+
+  return parts.length > 0 ? parts : text;
+}
 
 export const LoadingDots = () => {
+  const { data } = useLoadingTips();
+  const tips = data?.tips ?? DEFAULT_LOADING_TIPS;
+
   const [messageIndex, setMessageIndex] = React.useState(() =>
-    Math.floor(Math.random() * LOADING_MESSAGES.length)
+    Math.floor(Math.random() * tips.length)
   );
 
+  // Reset index when tips array changes to prevent undefined access
+  React.useEffect(() => {
+    setMessageIndex((prev) => prev % tips.length);
+  }, [tips.length]);
+
   React.useEffect(() => {
     const intervalId = setInterval(() => {
-      setMessageIndex((prevIndex) => (prevIndex + 1) % LOADING_MESSAGES.length);
+      setMessageIndex((prevIndex) => (prevIndex + 1) % tips.length);
     }, 8000);
     return () => clearInterval(intervalId);
-  }, []);
+  }, [tips.length]);
 
   return (
     <div className="flex items-center mt-2">
       <svg
-        width="24"
-        height="8"
-        viewBox="0 0 24 8"
+        width="56"
+        height="16"
+        viewBox="0 0 56 16"
         xmlns="http://www.w3.org/2000/svg"
-        className="mr-2 text-primary"
+        className="mr-2"
       >
         <style>
           {`
@@ -148,36 +189,48 @@ export const LoadingDots = () => {
               animation-delay: 0s;
             }
             .loading-dot-2 {
-              animation-delay: 0.2s;
+              animation-delay: 0.15s;
             }
             .loading-dot-3 {
-              animation-delay: 0.4s;
+              animation-delay: 0.3s;
+            }
+            .loading-dot-4 {
+              animation-delay: 0.45s;
             }
           `}
         </style>
         <circle
           className="loading-dot loading-dot-1"
-          cx="4"
-          cy="4"
-          r="3"
-          fill="currentColor"
+          cx="8"
+          cy="8"
+          r="6"
+          fill="#0066B1"
         />
         <circle
           className="loading-dot loading-dot-2"
-          cx="12"
-          cy="4"
-          r="3"
-          fill="currentColor"
+          cx="22"
+          cy="8"
+          r="6"
+          fill="#522DAE"
         />
         <circle
           className="loading-dot loading-dot-3"
-          cx="20"
-          cy="4"
-          r="3"
-          fill="currentColor"
+          cx="36"
+          cy="8"
+          r="6"
+          fill="#F40000"
+        />
+        <circle
+          className="loading-dot loading-dot-4"
+          cx="50"
+          cy="8"
+          r="6"
+          fill="#FFFFFF"
+          stroke="#9CA3AF"
+          strokeWidth="1"
         />
       </svg>
-      <span className="ml-2 text-xs text-muted-foreground/60">{LOADING_MESSAGES[messageIndex]}</span>
+      <span className="ml-2 text-xs text-muted-foreground">{parseMarkdownLinks(tips[messageIndex])}</span>
     </div>
   );
 };

components/frontend/src/lib/env.ts

@@ -31,6 +31,9 @@ type EnvConfig = {
   UNLEASH_URL?: string;
   UNLEASH_CLIENT_KEY?: string;
   UNLEASH_APP_NAME?: string;
+
+  // Loading tips (server-side, optional JSON array)
+  LOADING_TIPS?: string;
 };
 
 function getEnv(key: string, defaultValue?: string): string {
@@ -74,6 +77,7 @@ export const env: EnvConfig = {
   UNLEASH_URL: getOptionalEnv('UNLEASH_URL'),
   UNLEASH_CLIENT_KEY: getOptionalEnv('UNLEASH_CLIENT_KEY'),
   UNLEASH_APP_NAME: getOptionalEnv('UNLEASH_APP_NAME') || 'ambient-code-platform',
+  LOADING_TIPS: getOptionalEnv('LOADING_TIPS'),
 };
 
 /**

components/frontend/src/lib/loading-tips.ts

@@ -0,0 +1,17 @@
+/**
+ * Default loading tips shown during AI response generation.
+ * These are used as fallback when LOADING_TIPS env var is not configured.
+ * Tips support markdown-style links: [text](url)
+ */
+export const DEFAULT_LOADING_TIPS = [
+  "Tip: Clone sessions to quickly duplicate your setup for similar tasks",
+  "Tip: Export chat transcripts as Markdown or PDF for documentation",
+  "Tip: Add multiple repositories as context for cross-repo analysis",
+  "Tip: Stopped sessions can be resumed without losing your progress",
+  "Tip: Check MCP Servers to see which tools are available in your session",
+  "Tip: Repository URLs are remembered for quick re-use across sessions",
+  "Tip: Adjust temperature and max tokens in session settings for different tasks",
+  "Tip: Connect Google Drive to export chats directly to your Drive",
+  "Tip: Load custom workflows from your own Git repositories",
+  "Tip: Use the artifacts panel to browse and download files created by AI",
+];

components/frontend/src/services/api/config.ts

@@ -0,0 +1,18 @@
+/**
+ * Config API service
+ * Handles runtime configuration endpoints
+ */
+
+import { apiClient } from './client';
+
+export type LoadingTipsResponse = {
+  tips: string[];
+};
+
+/**
+ * Get loading tips from runtime configuration
+ * Falls back to defaults if not configured
+ */
+export async function getLoadingTips(): Promise<LoadingTipsResponse> {
+  return apiClient.get<LoadingTipsResponse>('/config/loading-tips');
+}

components/frontend/src/services/queries/use-loading-tips.ts

@@ -0,0 +1,20 @@
+/**
+ * React Query hook for loading tips
+ */
+
+import { useQuery } from '@tanstack/react-query';
+import { getLoadingTips } from '@/services/api/config';
+
+/**
+ * Hook to get loading tips from runtime configuration
+ * Cached indefinitely since tips rarely change
+ */
+export function useLoadingTips() {
+  return useQuery({
+    queryKey: ['config', 'loading-tips'],
+    queryFn: getLoadingTips,
+    staleTime: Infinity, // Tips don't change often, cache for session lifetime
+    gcTime: Infinity, // Keep in cache for entire session, even when unmounted
+    retry: 1, // Only retry once, fall back to defaults on failure
+  });
+}