astro-tractstack 2.0.0-rc.44 → 2.0.0-rc.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-tractstack",
-  "version": "2.0.0-rc.44",
+  "version": "2.0.0-rc.45",
   "description": "Astro integration for TractStack - redeeming the web from boring experiences",
   "type": "module",
   "main": "dist/index.js",

package/templates/custom/minimal/CodeHook.astro

@@ -20,12 +20,10 @@ export interface Props {
 
 const { target, options, fullContentMap /*, resourcesPayload */ } = Astro.props;
 
-const enableBunny = import.meta.env.PUBLIC_ENABLE_BUNNY === 'true';
-
 export const components = {
   'featured-content': true,
   'list-content': true,
-  ...(enableBunny && { 'bunny-video': true }),
+  'bunny-video': import.meta.env.PUBLIC_ENABLE_BUNNY === 'true',
   epinet: true,
   // "custom-hero": true,  // Uncomment when you create CustomHero.astro
 };
@@ -36,7 +34,7 @@ export const components = {
     <ListContent options={options} contentMap={fullContentMap} />
   ) : target === 'featured-content' ? (
     <FeaturedContent options={options} contentMap={fullContentMap} />
-  ) : target === 'bunny-video' && enableBunny ? (
+  ) : target === 'bunny-video' && import.meta.env.PUBLIC_ENABLE_BUNNY ? (
     <BunnyVideoWrapper options={options} />
   ) : target === 'epinet' ? (
     <EpinetWrapper fullContentMap={fullContentMap} client:only="react" /> /* 

package/templates/custom/with-examples/CodeHook.astro

@@ -20,13 +20,11 @@ export interface Props {
 
 const { target, options, fullContentMap /*, resourcesPayload */ } = Astro.props;
 
-const enableBunny = import.meta.env.PUBLIC_ENABLE_BUNNY === 'true';
-
 export const components = {
   'custom-hero': true,
   'featured-content': true,
   'list-content': true,
-  ...(enableBunny && { 'bunny-video': true }),
+  'bunny-video': import.meta.env.PUBLIC_ENABLE_BUNNY === 'true',
   epinet: true,
 };
 ---
@@ -36,7 +34,7 @@ export const components = {
     <ListContent options={options} contentMap={fullContentMap} />
   ) : target === 'featured-content' ? (
     <FeaturedContent options={options} contentMap={fullContentMap} />
-  ) : target === 'bunny-video' && enableBunny ? (
+  ) : target === 'bunny-video' && import.meta.env.PUBLIC_ENABLE_BUNNY ? (
     <BunnyVideoWrapper options={options} />
   ) : target === 'custom-hero' ? (
     <CustomHero />

package/templates/src/components/search/SearchModal.tsx

@@ -10,7 +10,10 @@ import { Portal } from '@ark-ui/react/portal';
 import { MagnifyingGlassIcon, XMarkIcon } from '@heroicons/react/24/outline';
 import { useSearch } from '@/hooks/useSearch';
 import SearchResults from './SearchResults';
-import type { FullContentMapItem } from '@/types/tractstack';
+import type {
+  FullContentMapItem,
+  DiscoverySuggestion,
+} from '@/types/tractstack';
 
 interface SearchModalProps {
   isOpen: boolean;
@@ -24,14 +27,19 @@ export default function SearchModal({
   contentMap,
 }: SearchModalProps) {
   const [query, setQuery] = useState('');
+  const [selectedTerms, setSelectedTerms] = useState<string[]>([]);
   const inputRef = useRef<HTMLInputElement>(null);
   const {
+    suggestions,
+    isDiscovering,
+    discoverError,
     searchResults,
-    isLoading,
-    error,
-    totalResults,
-    executeSearch,
-    clearResults,
+    isRetrieving,
+    retrieveError,
+    discoverTerms,
+    selectSuggestion,
+    selectExactMatch,
+    clearAll,
   } = useSearch();
 
   useEffect(() => {
@@ -43,17 +51,17 @@ export default function SearchModal({
   useEffect(() => {
     if (!isOpen) {
       setQuery('');
-      clearResults();
+      setSelectedTerms([]);
+      clearAll();
     }
-  }, [isOpen, clearResults]);
+  }, [isOpen, clearAll]);
 
   useEffect(() => {
+    // Only trigger discovery if query has 3+ characters
     if (query.trim().length >= 3) {
-      executeSearch(query.trim());
-    } else {
-      clearResults();
+      discoverTerms(query);
     }
-  }, [query, executeSearch, clearResults]);
+  }, [query, discoverTerms]);
 
   const handleInputChange = (e: ChangeEvent<HTMLInputElement>) => {
     setQuery(e.target.value);
@@ -61,16 +69,106 @@ export default function SearchModal({
 
   const handleClose = () => {
     setQuery('');
-    clearResults();
+    setSelectedTerms([]);
+    clearAll();
     onClose();
   };
 
   const handleKeyDown = (e: KeyboardEvent) => {
     if (e.key === 'Escape') {
       handleClose();
+    } else if (e.key === 'Enter' && query.trim()) {
+      // Only proceed if we have suggestions or query is 3+ chars
+      if (query.trim().length < 3) return;
+
+      // If there's only one suggestion, select it
+      if (suggestions.length === 1) {
+        handleSuggestionSelect(suggestions[0]);
+      } else if (suggestions.length > 0) {
+        // Check for exact match first
+        const exactMatch = suggestions.find(
+          (s) => s.term.toLowerCase() === query.trim().toLowerCase()
+        );
+        if (exactMatch) {
+          handleSuggestionSelect(exactMatch);
+        } else {
+          // No exact match, select first suggestion
+          handleSuggestionSelect(suggestions[0]);
+        }
+      } else {
+        // No suggestions, do exact match search
+        handleExactMatch(query.trim());
+      }
+    }
+  };
+
+  const handleSuggestionClick = (suggestion: DiscoverySuggestion) => {
+    handleSuggestionSelect(suggestion);
+  };
+
+  const handleSuggestionSelect = (suggestion: DiscoverySuggestion) => {
+    // Add to selected terms if not already present
+    if (!selectedTerms.includes(suggestion.term)) {
+      setSelectedTerms((prev) => [...prev, suggestion.term]);
+    }
+
+    // Clear input and perform search
+    setQuery('');
+    selectSuggestion(suggestion);
+  };
+
+  const handleExactMatch = (term: string) => {
+    // Add to selected terms if not already present
+    if (!selectedTerms.includes(term)) {
+      setSelectedTerms((prev) => [...prev, term]);
+    }
+
+    // Clear input and perform search
+    setQuery('');
+    selectExactMatch(term);
+  };
+
+  const removeTerm = (indexToRemove: number) => {
+    setSelectedTerms((prev) =>
+      prev.filter((_, index) => index !== indexToRemove)
+    );
+    // Clear search results when removing terms
+    clearAll();
+    // Focus back on input
+    if (inputRef.current) {
+      inputRef.current.focus();
+    }
+  };
+
+  const getTypeColor = (type: string) => {
+    switch (type) {
+      case 'TOPIC':
+        return 'bg-purple-100 text-purple-800 border-purple-200';
+      case 'TITLE':
+        return 'bg-blue-100 text-blue-800 border-blue-200';
+      case 'CONTENT':
+        return 'bg-green-100 text-green-800 border-green-200';
+      default:
+        return 'bg-gray-100 text-gray-800 border-gray-200';
     }
   };
 
+  // Autocomplete logic - only show when we have suggestions and query is 3+ chars
+  const bestCompletion =
+    suggestions.length > 0 && query.length >= 3 ? suggestions[0].term : '';
+  const showCompletion =
+    bestCompletion.toLowerCase().startsWith(query.toLowerCase()) &&
+    query.length >= 3;
+
+  const showSuggestions =
+    suggestions.length > 0 && !searchResults && query.length >= 3;
+  const showResults = searchResults !== null;
+  const totalResults = searchResults
+    ? searchResults.storyFragmentResults.length +
+      searchResults.contextPaneResults.length +
+      searchResults.resourceResults.length
+    : 0;
+
   return (
     <Dialog.Root
       open={isOpen}
@@ -78,22 +176,57 @@ export default function SearchModal({
     >
       <Portal>
         <Dialog.Backdrop className="fixed inset-0 z-50 bg-black bg-opacity-50 backdrop-blur-sm" />
-        <Dialog.Positioner className="fixed inset-0 z-50 mx-auto max-w-5xl p-2 pt-16 md:p-4">
+        <Dialog.Positioner className="fixed inset-0 z-50 mx-auto max-w-3xl p-2 pt-16 md:p-4">
           <Dialog.Content
             className="bg-mywhite mx-auto w-full overflow-hidden rounded-lg shadow-2xl"
             style={{ height: '80vh' }}
           >
             {/* Fixed Header */}
             <div className="relative w-full border-b border-gray-200 p-4">
-              <input
-                ref={inputRef}
-                type="text"
-                value={query}
-                onChange={handleInputChange}
-                onKeyDown={handleKeyDown}
-                placeholder="Search content..."
-                className="text-mydarkgrey w-full border-none bg-transparent px-6 py-2 text-xl placeholder-gray-500 outline-none"
-              />
+              {/* Selected Terms Pills */}
+              {selectedTerms.length > 0 && (
+                <div className="mb-3 flex flex-wrap gap-2">
+                  {selectedTerms.map((term, index) => (
+                    <div
+                      key={index}
+                      className="flex items-center gap-1 rounded-full border border-blue-200 bg-blue-100 px-3 py-1 text-sm font-medium text-blue-800"
+                    >
+                      <span>{term}</span>
+                      <button
+                        onClick={() => removeTerm(index)}
+                        className="ml-1 rounded-full p-0.5 text-blue-600 hover:bg-blue-200 hover:text-blue-800"
+                        aria-label={`Remove ${term}`}
+                      >
+                        <XMarkIcon className="h-3 w-3" />
+                      </button>
+                    </div>
+                  ))}
+                </div>
+              )}
+
+              {!showResults && (
+                <div className="relative">
+                  <div className="relative w-full border-none bg-transparent px-6 py-2 text-xl">
+                    {/* Background layer with completion text */}
+                    {showCompletion && (
+                      <div className="pointer-events-none absolute inset-0 px-6 py-2 text-xl text-gray-400">
+                        {bestCompletion}
+                      </div>
+                    )}
+                    {/* Foreground input */}
+                    <input
+                      ref={inputRef}
+                      type="text"
+                      value={query}
+                      onChange={handleInputChange}
+                      onKeyDown={handleKeyDown}
+                      placeholder="Search content..."
+                      className="text-mydarkgrey relative z-10 w-full border-none bg-transparent text-xl placeholder-gray-500 outline-none"
+                      style={{ background: 'transparent' }}
+                    />
+                  </div>
+                </div>
+              )}
               <button
                 onClick={handleClose}
                 className="text-mydarkgrey hover:text-myblue absolute right-4 top-6 rounded-lg p-2 transition-colors hover:bg-gray-100"
@@ -108,29 +241,41 @@ export default function SearchModal({
               className="w-full overflow-y-auto"
               style={{ height: 'calc(80vh - 80px)' }}
             >
-              {query.length < 3 && (
+              {/* Initial State */}
+              {!query.trim() && selectedTerms.length === 0 && (
                 <div className="w-full p-8 text-center text-gray-500">
                   <MagnifyingGlassIcon className="mx-auto mb-4 h-16 w-16 text-gray-300" />
                   <p className="text-lg">Search across all content</p>
                   <p className="mt-2 text-sm">
-                    Type at least 3 characters to search pages, context, and
-                    resources
+                    Start typing to discover content suggestions
                   </p>
                 </div>
               )}
 
-              {query.length >= 3 && isLoading && (
+              {/* Show message for less than 3 characters */}
+              {query.trim() && query.trim().length < 3 && (
+                <div className="w-full p-8 text-center text-gray-500">
+                  <p className="text-lg">Keep typing...</p>
+                  <p className="mt-2 text-sm">
+                    Need at least 3 characters to search
+                  </p>
+                </div>
+              )}
+
+              {/* Discovery Loading */}
+              {query.trim().length >= 3 && isDiscovering && (
                 <div className="w-full p-8 text-center">
                   <div className="border-myblue inline-block h-8 w-8 animate-spin rounded-full border-b-2"></div>
-                  <p className="text-mydarkgrey mt-4">Searching...</p>
+                  <p className="text-mydarkgrey mt-4">Discovering...</p>
                 </div>
               )}
 
-              {query.length >= 3 && error && (
+              {/* Discovery Error */}
+              {query.trim().length >= 3 && discoverError && (
                 <div className="w-full p-8 text-center text-red-600">
-                  <p>Search failed: {error}</p>
+                  <p>Discovery failed: {discoverError}</p>
                   <button
-                    onClick={() => executeSearch(query.trim())}
+                    onClick={() => discoverTerms(query.trim())}
                     className="text-myblue mt-2 hover:underline"
                   >
                     Try again
@@ -138,21 +283,61 @@ export default function SearchModal({
                 </div>
               )}
 
-              {query.length >= 3 &&
-                !isLoading &&
-                !error &&
+              {/* Suggestion Pills */}
+              {showSuggestions && (
+                <div className="w-full p-6">
+                  <p className="text-mydarkgrey mb-4 text-sm font-medium">
+                    Suggestions ({suggestions.length})
+                  </p>
+                  <div className="flex flex-wrap gap-2">
+                    {suggestions.map((suggestion, index) => (
+                      <button
+                        key={index}
+                        onClick={() => handleSuggestionClick(suggestion)}
+                        className={`inline-flex items-center rounded-full border px-3 py-1.5 text-sm font-medium transition-all hover:shadow-md ${getTypeColor(suggestion.type)}`}
+                      >
+                        <span>{suggestion.term}</span>
+                      </button>
+                    ))}
+                  </div>
+                  <p className="text-mydarkgrey mt-4 text-xs">
+                    Click a suggestion or press Enter to search
+                  </p>
+                </div>
+              )}
+
+              {/* Retrieve Loading */}
+              {isRetrieving && (
+                <div className="w-full p-8 text-center">
+                  <div className="border-myblue inline-block h-8 w-8 animate-spin rounded-full border-b-2"></div>
+                  <p className="text-mydarkgrey mt-4">Searching...</p>
+                </div>
+              )}
+
+              {/* Retrieve Error */}
+              {retrieveError && (
+                <div className="w-full p-8 text-center text-red-600">
+                  <p>Search failed: {retrieveError}</p>
+                </div>
+              )}
+
+              {/* No Results */}
+              {!isRetrieving &&
+                !retrieveError &&
+                showResults &&
                 totalResults === 0 && (
                   <div className="w-full p-8 text-center text-gray-500">
-                    <p className="text-lg">No results found for "{query}"</p>
+                    <p className="text-lg">No results found</p>
                     <p className="mt-2 text-sm">
                       Try different keywords or check your spelling
                     </p>
                   </div>
                 )}
 
-              {query.length >= 3 &&
-                !isLoading &&
-                !error &&
+              {/* Search Results */}
+              {!isRetrieving &&
+                !retrieveError &&
+                showResults &&
                 totalResults > 0 && (
                   <SearchResults
                     results={searchResults}

package/templates/src/components/search/SearchResults.tsx

@@ -1,6 +1,7 @@
 import { useState, useMemo } from 'react';
 import { Pagination } from '@ark-ui/react/pagination';
-import type { SearchResults as SearchResultsType } from '@/hooks/useSearch';
+import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
+import type { CategorizedResults, FTSResult } from '@/types/tractstack';
 import type { FullContentMapItem } from '@/types/tractstack';
 import {
   getResourceUrl,
@@ -8,8 +9,10 @@ import {
   getResourceDescription,
 } from '@/utils/customHelpers';
 
+const VERBOSE = false;
+
 interface SearchResultsProps {
-  results: SearchResultsType;
+  results: CategorizedResults;
   contentMap: FullContentMapItem[];
   onResultClick: () => void;
 }
@@ -40,11 +43,26 @@ export default function SearchResults({
   const allResultItems = useMemo(() => {
     const items: ResultItem[] = [];
 
-    results.storyFragmentIds.forEach((id) => {
+    if (VERBOSE)
+      console.log('DEBUG SearchResults: Processing results', {
+        storyFragmentResults: results.storyFragmentResults.length,
+        contextPaneResults: results.contextPaneResults.length,
+        resourceResults: results.resourceResults.length,
+        contentMapSize: contentMap.length,
+      });
+
+    // Process StoryFragment results
+    results.storyFragmentResults.forEach((ftsResult: FTSResult, index) => {
+      if (VERBOSE) console.log(`DEBUG StoryFragment ${index}:`, ftsResult);
       const item = contentMap.find(
-        (item) => item.id === id && item.type === 'StoryFragment'
+        (item) => item.id === ftsResult.ID && item.type === 'StoryFragment'
       );
       if (item) {
+        if (VERBOSE)
+          console.log(
+            `DEBUG StoryFragment ${index}: Found in contentMap`,
+            item
+          );
         items.push({
           id: item.id,
           type: 'StoryFragment',
@@ -57,14 +75,23 @@ export default function SearchResults({
           url: `/${item.slug}`,
           imageSrc: item.thumbSrc || '/static.jpg',
         });
+      } else {
+        if (VERBOSE)
+          console.log(
+            `DEBUG StoryFragment ${index}: NOT found in contentMap for ID ${ftsResult.ID}`
+          );
       }
     });
 
-    results.contextPaneIds.forEach((id) => {
+    // Process ContextPane results
+    results.contextPaneResults.forEach((ftsResult: FTSResult, index) => {
+      if (VERBOSE) console.log(`DEBUG ContextPane ${index}:`, ftsResult);
       const item = contentMap.find(
-        (item) => item.id === id && item.type === 'Pane'
+        (item) => item.id === ftsResult.ID && item.type === 'Pane'
       );
       if (item) {
+        if (VERBOSE)
+          console.log(`DEBUG ContextPane ${index}: Found in contentMap`, item);
         items.push({
           id: item.id,
           type: 'ContextPane',
@@ -73,14 +100,24 @@ export default function SearchResults({
           url: `/context/${item.slug}`,
           imageSrc: '/static.jpg',
         });
+      } else {
+        if (VERBOSE)
+          console.log(
+            `DEBUG ContextPane ${index}: NOT found in contentMap for ID ${ftsResult.ID}`
+          );
       }
     });
 
-    results.resourceIds.forEach((id) => {
+    // Process Resource results
+    results.resourceResults.forEach((ftsResult: FTSResult, index) => {
+      if (VERBOSE) console.log(`DEBUG Resource ${index}:`, ftsResult);
       const item = contentMap.find(
-        (item) => item.id === id && item.type === 'Resource'
+        (item) => item.id === ftsResult.ID && item.type === 'Resource'
       );
       if (item) {
+        if (VERBOSE)
+          console.log(`DEBUG Resource ${index}: Found in contentMap`, item);
+
         const resourceUrl = getResourceUrl(item.categorySlug || '', item.slug);
         const resourceImage = getResourceImage(
           item.id,
@@ -93,6 +130,16 @@ export default function SearchResults({
           item.categorySlug || ''
         );
 
+        if (VERBOSE)
+          console.log(`DEBUG Resource ${index}: Helper results`, {
+            resourceUrl,
+            resourceImage,
+            description,
+            categorySlug: item.categorySlug,
+            slug: item.slug,
+            id: item.id,
+          });
+
         items.push({
           id: item.id,
           type: 'Resource',
@@ -103,9 +150,24 @@ export default function SearchResults({
           url: resourceUrl,
           imageSrc: resourceImage,
         });
+      } else {
+        if (VERBOSE)
+          console.log(
+            `DEBUG Resource ${index}: NOT found in contentMap for ID ${ftsResult.ID}`
+          );
+        if (VERBOSE)
+          console.log(
+            'DEBUG: Available resource IDs in contentMap:',
+            contentMap
+              .filter((item) => item.type === 'Resource')
+              .map((item) => ({ id: item.id, title: item.title }))
+          );
       }
     });
 
+    if (VERBOSE) console.log('DEBUG SearchResults: Final items', items);
+
+    // Sort by whether they have real images
     return items.sort((a, b) => {
       const aHasRealImage = a.imageSrc !== '/static.jpg';
       const bHasRealImage = b.imageSrc !== '/static.jpg';
@@ -114,17 +176,18 @@ export default function SearchResults({
       if (!aHasRealImage && bHasRealImage) return 1;
       return 0;
     });
-  }, [results]);
+  }, [results, contentMap]);
 
-  const totalPages = Math.ceil(allResultItems.length / ITEMS_PER_PAGE);
+  const totalResults = allResultItems.length;
+  const totalPages = Math.ceil(totalResults / ITEMS_PER_PAGE);
   const startIndex = (currentPage - 1) * ITEMS_PER_PAGE;
   const paginatedItems = allResultItems.slice(
     startIndex,
     startIndex + ITEMS_PER_PAGE
   );
 
-  const handlePageChange = (details: { page: number }) => {
-    setCurrentPage(details.page);
+  const handlePageChange = (page: number) => {
+    setCurrentPage(page);
   };
 
   const getResultBadge = (type: string, categorySlug?: string) => {
@@ -152,7 +215,7 @@ export default function SearchResults({
     }
   };
 
-  if (allResultItems.length === 0) {
+  if (totalResults === 0) {
     return null;
   }
 
@@ -160,13 +223,12 @@ export default function SearchResults({
     <div className="p-6">
       <div className="mb-6">
         <h2 className="text-mydarkgrey text-lg font-bold">
-          {allResultItems.length} result{allResultItems.length !== 1 ? 's' : ''}{' '}
-          found
+          {totalResults} result{totalResults !== 1 ? 's' : ''} found
         </h2>
         <p className="mt-1 text-sm text-gray-600">
           Showing {startIndex + 1}-
-          {Math.min(startIndex + ITEMS_PER_PAGE, allResultItems.length)} of{' '}
-          {allResultItems.length}
+          {Math.min(startIndex + ITEMS_PER_PAGE, totalResults)} of{' '}
+          {totalResults}
         </p>
       </div>
 
@@ -177,86 +239,65 @@ export default function SearchResults({
             className="rounded-lg border border-gray-200 p-4 transition-colors hover:bg-gray-100"
           >
             <a href={item.url} onClick={onResultClick} className="group block">
-              <div className="flex items-start gap-4">
+              <div className="flex flex-col md:flex-row md:items-start md:gap-4">
+                {/* Mobile: Full width image with overlay badge */}
                 <div
-                  className="bg-mydarkgrey flex-shrink-0 overflow-hidden rounded-lg p-1 md:hidden"
-                  style={{
-                    width: '100px',
-                    height: '56px',
-                  }}
-                  data-mobile-size="100x56"
+                  className="bg-mydarkgrey relative w-full overflow-hidden rounded-lg md:hidden"
+                  style={{ aspectRatio: '1200/630' }}
                 >
                   <img
                     src={item.imageSrc}
                     alt={item.title}
-                    className="h-full w-full rounded object-contain"
+                    className="h-full w-full object-contain"
                   />
+                  <div className="absolute left-2 top-2">
+                    {getResultBadge(item.type, item.categorySlug)}
+                  </div>
                 </div>
 
+                {/* Desktop: Side image with overlay badge */}
                 <div
-                  className="bg-mydarkgrey hidden flex-shrink-0 overflow-hidden rounded-lg p-1 md:block"
-                  style={{
-                    width: '240px',
-                    height: '135px',
-                  }}
-                  data-desktop-size="240x135"
+                  className="bg-mydarkgrey relative hidden flex-shrink-0 overflow-hidden rounded-lg md:block"
+                  style={{ width: '240px', height: '135px' }}
                 >
                   <img
                     src={item.imageSrc}
                     alt={item.title}
-                    className="h-full w-full rounded object-contain"
+                    className="h-full w-full object-contain"
                   />
+                  <div className="absolute left-2 top-2">
+                    {getResultBadge(item.type, item.categorySlug)}
+                  </div>
                 </div>
 
-                <div className="min-w-0 flex-1">
+                <div className="mt-3 min-w-0 flex-1 md:mt-0">
                   <div className="flex items-start justify-between gap-4">
                     <div className="flex-1">
-                      <div className="mb-2">
-                        <h3 className="text-mydarkgrey group-hover:text-myblue line-clamp-2 font-bold transition-colors">
-                          {item.title}
-                        </h3>
-                      </div>
-
-                      {(item.type === 'StoryFragment' ||
-                        item.type === 'Resource') &&
-                        item.description && (
-                          <p className="mb-2 line-clamp-2 text-sm text-gray-600">
-                            {item.description}
-                          </p>
-                        )}
-
+                      <h3 className="text-mydarkgrey group-hover:text-myblue mb-2 text-lg font-semibold transition-colors">
+                        {item.title}
+                      </h3>
+                      {item.description && (
+                        <p className="text-mydarkgrey mb-2 text-sm">
+                          {item.description}
+                        </p>
+                      )}
                       {item.topics && item.topics.length > 0 && (
                         <div className="mb-2 flex flex-wrap gap-1">
-                          {item.topics.slice(0, 3).map((topic) => (
+                          {item.topics.slice(0, 3).map((topic, idx) => (
                             <span
-                              key={topic}
-                              className="inline-flex items-center rounded-full bg-gray-100 px-2 py-1 text-xs text-gray-700"
+                              key={idx}
+                              className="bg-myoffwhite text-mydarkgrey rounded px-2 py-1 text-xs"
                             >
                               {topic}
                             </span>
                           ))}
                           {item.topics.length > 3 && (
-                            <span className="text-xs text-gray-500">
+                            <span className="text-mydarkgrey text-xs">
                               +{item.topics.length - 3} more
                             </span>
                           )}
                         </div>
                       )}
-
-                      <p className="truncate text-xs text-gray-500">
-                        {item.url}
-                      </p>
-
-                      {/* Mobile badge row */}
-                      <div className="mt-2 block md:hidden">
-                        {getResultBadge(item.type, item.categorySlug)}
-                      </div>
-                    </div>
-
-                    <div className="hidden flex-shrink-0 text-right md:block">
-                      <div className="mb-2">
-                        {getResultBadge(item.type, item.categorySlug)}
-                      </div>
                     </div>
                   </div>
                 </div>
@@ -267,42 +308,52 @@ export default function SearchResults({
       </div>
 
       {totalPages > 1 && (
-        <div className="mt-8 flex justify-center">
+        <div className="flex justify-center">
           <Pagination.Root
-            count={allResultItems.length}
+            count={totalResults}
             pageSize={ITEMS_PER_PAGE}
             page={currentPage}
-            siblingCount={1}
-            onPageChange={handlePageChange}
-            className="flex flex-wrap items-center gap-2"
+            onPageChange={(details) => handlePageChange(details.page)}
           >
-            <Pagination.Context>
-              {(pagination) =>
-                pagination.pages.map((page, index) =>
-                  page.type === 'page' ? (
-                    <Pagination.Item
-                      key={index}
-                      {...page}
-                      className={`cursor-pointer rounded-md px-3 py-2 text-sm ${
-                        page.value === currentPage
-                          ? 'bg-gray-900 text-white'
-                          : 'border border-gray-300 bg-white text-gray-700 hover:bg-gray-50'
-                      }`}
-                    >
-                      {page.value}
-                    </Pagination.Item>
-                  ) : (
-                    <Pagination.Ellipsis
-                      key={index}
-                      index={index}
-                      className="px-3 py-2 text-sm text-gray-500"
-                    >
-                      …
-                    </Pagination.Ellipsis>
+            <Pagination.PrevTrigger className="text-mydarkgrey hover:text-myblue mr-2 flex items-center gap-1 rounded px-3 py-2 text-sm font-medium transition-colors disabled:opacity-50">
+              <ChevronLeftIcon className="h-4 w-4" />
+              Previous
+            </Pagination.PrevTrigger>
+
+            <div className="flex items-center gap-1">
+              <Pagination.Context>
+                {(pagination) =>
+                  pagination.pages.map((page, index) =>
+                    page.type === 'page' ? (
+                      <Pagination.Item
+                        key={index}
+                        type="page"
+                        value={page.value}
+                        className={`rounded px-3 py-2 text-sm font-medium transition-colors ${
+                          page.value === currentPage
+                            ? 'bg-myblue text-white'
+                            : 'text-mydarkgrey hover:text-myblue'
+                        }`}
+                      >
+                        {page.value}
+                      </Pagination.Item>
+                    ) : (
+                      <span
+                        key={index}
+                        className="text-mydarkgrey px-2 text-sm"
+                      >
+                        {page.type === 'ellipsis' ? '...' : ''}
+                      </span>
+                    )
                   )
-                )
-              }
-            </Pagination.Context>
+                }
+              </Pagination.Context>
+            </div>
+
+            <Pagination.NextTrigger className="text-mydarkgrey hover:text-myblue ml-2 flex items-center gap-1 rounded px-3 py-2 text-sm font-medium transition-colors disabled:opacity-50">
+              Next
+              <ChevronRightIcon className="h-4 w-6" />
+            </Pagination.NextTrigger>
           </Pagination.Root>
         </div>
       )}

package/templates/src/hooks/useSearch.ts

@@ -1,179 +1,224 @@
 import { useState, useCallback, useRef, useMemo } from 'react';
 import { TractStackAPI } from '@/utils/api';
-
-export interface SearchResults {
-  storyFragmentIds: string[];
-  contextPaneIds: string[];
-  resourceIds: string[];
-}
+import type {
+  DiscoverySuggestion,
+  CategorizedResults,
+} from '@/types/tractstack';
 
 interface UseSearchReturn {
-  searchResults: SearchResults;
-  isLoading: boolean;
-  error: string | null;
-  totalResults: number;
-  executeSearch: (query: string) => void;
-  clearResults: () => void;
+  // Discovery phase
+  suggestions: DiscoverySuggestion[];
+  isDiscovering: boolean;
+  discoverError: string | null;
+
+  // Retrieve phase
+  searchResults: CategorizedResults | null;
+  isRetrieving: boolean;
+  retrieveError: string | null;
+
+  // Actions
+  discoverTerms: (query: string) => void;
+  selectSuggestion: (suggestion: DiscoverySuggestion) => void;
+  selectExactMatch: (term: string) => void;
+  clearAll: () => void;
 }
 
 const DEBOUNCE_MS = 100;
-const BACKEND_THROTTLE_MS = 1000;
+const BACKEND_THROTTLE_MS = 1200;
 
 export function useSearch(): UseSearchReturn {
-  const [searchResults, setSearchResults] = useState<SearchResults>({
-    storyFragmentIds: [],
-    contextPaneIds: [],
-    resourceIds: [],
-  });
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
+  // Discovery state
+  const [suggestions, setSuggestions] = useState<DiscoverySuggestion[]>([]);
+  const [isDiscovering, setIsDiscovering] = useState(false);
+  const [discoverError, setDiscoverError] = useState<string | null>(null);
+
+  // Retrieve state
+  const [searchResults, setSearchResults] = useState<CategorizedResults | null>(
+    null
+  );
+  const [isRetrieving, setIsRetrieving] = useState(false);
+  const [retrieveError, setRetrieveError] = useState<string | null>(null);
 
   const debounceRef = useRef<NodeJS.Timeout>();
   const lastSearchTimeRef = useRef<number>(0);
-  const queuedQueryRef = useRef<string | null>(null);
-  const queueTimeoutRef = useRef<NodeJS.Timeout>();
-  const isFirstSearchRef = useRef<boolean>(true);
-
+  const pendingQueryRef = useRef<string | null>(null);
+  const throttleTimeoutRef = useRef<NodeJS.Timeout>();
   const api = useMemo(() => new TractStackAPI(), []);
 
-  const performSearch = useCallback(
+  const performDiscovery = useCallback(
     async (query: string) => {
-      if (!query.trim() || query.trim().length < 3) {
+      if (!query.trim()) {
+        setSuggestions([]);
         return;
       }
 
-      setIsLoading(true);
-      setError(null);
+      setIsDiscovering(true);
+      setDiscoverError(null);
+      lastSearchTimeRef.current = Date.now();
 
       try {
-        const response = await api.search(query.trim());
+        const response = await api.discover(query.trim());
 
         if (response.success && response.data) {
-          setSearchResults(response.data);
-          lastSearchTimeRef.current = Date.now();
+          setSuggestions(response.data.suggestions);
         } else {
-          // Handle 429 silently - backend is protecting itself
-          if (response.error?.includes('too frequently')) {
-            // Don't set error for rate limiting, just maintain loading state
-            return;
-          }
-          setError(response.error || 'Search failed');
-          setSearchResults({
-            storyFragmentIds: [],
-            contextPaneIds: [],
-            resourceIds: [],
-          });
+          setDiscoverError(response.error || 'Discovery failed');
+          setSuggestions([]);
         }
       } catch (err) {
-        setError(err instanceof Error ? err.message : 'Search failed');
-        setSearchResults({
-          storyFragmentIds: [],
-          contextPaneIds: [],
-          resourceIds: [],
-        });
+        setDiscoverError(
+          err instanceof Error ? err.message : 'Discovery failed'
+        );
+        setSuggestions([]);
       } finally {
-        setIsLoading(false);
+        setIsDiscovering(false);
       }
     },
     [api]
   );
 
-  const processQueue = useCallback(() => {
-    if (queuedQueryRef.current) {
-      const queryToProcess = queuedQueryRef.current;
-      queuedQueryRef.current = null;
-      performSearch(queryToProcess);
-    }
-  }, [performSearch]);
+  const performRetrieve = useCallback(
+    async (term: string, isTopic: boolean = false) => {
+      setIsRetrieving(true);
+      setRetrieveError(null);
 
-  const executeSearchWithThrottling = useCallback(
-    (query: string) => {
-      const now = Date.now();
-      const timeSinceLastSearch = now - lastSearchTimeRef.current;
-
-      // First search or enough time has passed - execute immediately
-      if (
-        isFirstSearchRef.current ||
-        timeSinceLastSearch >= BACKEND_THROTTLE_MS
-      ) {
-        isFirstSearchRef.current = false;
-        performSearch(query);
-      } else {
-        // Queue the search and schedule it to run when throttle window expires
-        queuedQueryRef.current = query;
-
-        // Clear any existing queue timeout
-        if (queueTimeoutRef.current) {
-          clearTimeout(queueTimeoutRef.current);
-        }
+      try {
+        const response = await api.retrieve(term, isTopic);
 
-        // Schedule execution for when the throttle window expires
-        const remainingTime = BACKEND_THROTTLE_MS - timeSinceLastSearch;
-        queueTimeoutRef.current = setTimeout(processQueue, remainingTime);
+        if (response.success && response.data) {
+          setSearchResults(response.data);
+        } else {
+          setRetrieveError(response.error || 'Retrieval failed');
+          setSearchResults(null);
+        }
+      } catch (err) {
+        setRetrieveError(
+          err instanceof Error ? err.message : 'Retrieval failed'
+        );
+        setSearchResults(null);
+      } finally {
+        setIsRetrieving(false);
       }
     },
-    [performSearch, processQueue]
+    [api]
   );
 
-  const executeSearch = useCallback(
+  const executePendingSearch = useCallback(() => {
+    if (pendingQueryRef.current) {
+      const queryToExecute = pendingQueryRef.current;
+      pendingQueryRef.current = null;
+      performDiscovery(queryToExecute);
+    }
+  }, [performDiscovery]);
+
+  const discoverTerms = useCallback(
     (query: string) => {
-      // Clear existing debounce
+      // Clear existing debounce timer
       if (debounceRef.current) {
         clearTimeout(debounceRef.current);
       }
 
-      // Handle empty or short queries immediately
-      if (!query.trim() || query.trim().length < 3) {
-        setSearchResults({
-          storyFragmentIds: [],
-          contextPaneIds: [],
-          resourceIds: [],
-        });
-        setError(null);
-        setIsLoading(false);
+      // Clear existing throttle timer
+      if (throttleTimeoutRef.current) {
+        clearTimeout(throttleTimeoutRef.current);
+      }
+
+      // Clear results when starting new discovery
+      setSearchResults(null);
+      setRetrieveError(null);
+
+      // Handle empty queries immediately
+      if (!query.trim()) {
+        setSuggestions([]);
+        setDiscoverError(null);
+        setIsDiscovering(false);
+        pendingQueryRef.current = null;
         return;
       }
 
-      // Debounce the actual search execution
+      // Always store the latest query
+      pendingQueryRef.current = query;
+
+      // Debounce first - wait for user to stop typing
       debounceRef.current = setTimeout(() => {
-        executeSearchWithThrottling(query);
+        const now = Date.now();
+        const timeSinceLastSearch = now - lastSearchTimeRef.current;
+
+        // If enough time has passed since last search, execute immediately
+        if (timeSinceLastSearch >= BACKEND_THROTTLE_MS) {
+          executePendingSearch();
+        } else {
+          // Need to wait for throttle - schedule execution
+          const remainingTime = BACKEND_THROTTLE_MS - timeSinceLastSearch;
+          throttleTimeoutRef.current = setTimeout(
+            executePendingSearch,
+            remainingTime
+          );
+        }
       }, DEBOUNCE_MS);
     },
-    [executeSearchWithThrottling]
+    [executePendingSearch]
   );
 
-  const clearResults = useCallback(() => {
+  const selectSuggestion = useCallback(
+    (suggestion: DiscoverySuggestion) => {
+      // Clear suggestions
+      setSuggestions([]);
+      setDiscoverError(null);
+
+      // Perform retrieve based on suggestion type
+      const isTopic = suggestion.type === 'TOPIC';
+      performRetrieve(suggestion.term, isTopic);
+    },
+    [performRetrieve]
+  );
+
+  const selectExactMatch = useCallback(
+    (term: string) => {
+      // Clear suggestions
+      setSuggestions([]);
+      setDiscoverError(null);
+
+      // Check if term exists in current suggestions to determine if it's a topic
+      const matchingSuggestion = suggestions.find(
+        (s) => s.term.toLowerCase() === term.toLowerCase()
+      );
+      const isTopic = matchingSuggestion?.type === 'TOPIC';
+
+      performRetrieve(term, isTopic);
+    },
+    [suggestions, performRetrieve]
+  );
+
+  const clearAll = useCallback(() => {
     // Clear all timeouts
     if (debounceRef.current) {
       clearTimeout(debounceRef.current);
     }
-    if (queueTimeoutRef.current) {
-      clearTimeout(queueTimeoutRef.current);
+    if (throttleTimeoutRef.current) {
+      clearTimeout(throttleTimeoutRef.current);
     }
 
-    // Reset state
-    setSearchResults({
-      storyFragmentIds: [],
-      contextPaneIds: [],
-      resourceIds: [],
-    });
-    setIsLoading(false);
-    setError(null);
-    queuedQueryRef.current = null;
-    isFirstSearchRef.current = true;
+    // Reset all state
+    setSuggestions([]);
+    setIsDiscovering(false);
+    setDiscoverError(null);
+    setSearchResults(null);
+    setIsRetrieving(false);
+    setRetrieveError(null);
+    pendingQueryRef.current = null;
   }, []);
 
-  const totalResults =
-    searchResults.storyFragmentIds.length +
-    searchResults.contextPaneIds.length +
-    searchResults.resourceIds.length;
-
   return {
+    suggestions,
+    isDiscovering,
+    discoverError,
     searchResults,
-    isLoading,
-    error,
-    totalResults,
-    executeSearch,
-    clearResults,
+    isRetrieving,
+    retrieveError,
+    discoverTerms,
+    selectSuggestion,
+    selectExactMatch,
+    clearAll,
   };
 }

package/templates/src/types/tractstack.ts

@@ -443,3 +443,20 @@ export interface BunnyPlayer {
 export interface PlayerJS {
   Player: new (elementId: string) => BunnyPlayer;
 }
+
+export interface DiscoverySuggestion {
+  term: string;
+  type: 'CONTENT' | 'TOPIC' | 'TITLE';
+}
+
+export interface FTSResult {
+  ID: string;
+  Relevance: number;
+  Term: string;
+}
+
+export interface CategorizedResults {
+  storyFragmentResults: FTSResult[];
+  contextPaneResults: FTSResult[];
+  resourceResults: FTSResult[];
+}

package/templates/src/utils/api.ts

@@ -1,3 +1,9 @@
+import type {
+  DiscoverySuggestion,
+  FTSResult,
+  CategorizedResults,
+} from '@/types/tractstack';
+
 export interface APIResponse<T = any> {
   success: boolean;
   data?: T;
@@ -138,14 +144,19 @@ export class TractStackAPI {
     });
   }
 
-  async search(query: string): Promise<
-    APIResponse<{
-      storyFragmentIds: string[];
-      contextPaneIds: string[];
-      resourceIds: string[];
-    }>
-  > {
-    return this.post('/api/v1/nodes/panes/search', { query });
+  async discover(
+    query: string
+  ): Promise<APIResponse<{ suggestions: DiscoverySuggestion[] }>> {
+    return this.get(`/api/v1/search/discover?q=${encodeURIComponent(query)}`);
+  }
+
+  async retrieve(
+    term: string,
+    isTopic: boolean = false
+  ): Promise<APIResponse<CategorizedResults>> {
+    return this.get(
+      `/api/v1/search/retrieve?term=${encodeURIComponent(term)}&topic=${isTopic}`
+    );
   }
 
   async getContent(slug: string): Promise<APIResponse> {