refactor: use top-level fields as source of truth for resource metadata

- Simplified normalizeResourceInfo to promote metadata fields to top-level
- Updated WordsLinksViewer to use resource.title directly
- Updated TranslationNotesViewer to use resource.title directly
- Updated TranslationQuestionsViewer to use resource.title directly
- Removed fallback titles (metadata now always promoted via normalization)

This fixes the issue where localized resource titles weren't showing
in the viewer headers.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: abelpz

apps/tc-study/src/components/read/SimplifiedReadView.tsx

@@ -1000,16 +1000,8 @@ export function SimplifiedReadView({ initialLanguage }: SimplifiedReadViewProps
       const viewerProps: any = {
         resourceId: resource.id,
         resourceKey: resourceKey,
-      }
-      
-      // Add metadata - use stored metadata or resource object as fallback
-      if (resource.metadata != null) {
-        viewerProps.metadata = resource.metadata
-      } else if (resource.ingredients != null && resource.type === 'words') {
-        viewerProps.metadata = { ingredients: resource.ingredients, contentMetadata: { ingredients: resource.ingredients } }
-      } else {
-        // Use resource object itself as metadata fallback for other resource types
-        viewerProps.metadata = resource
+        // Metadata is now guaranteed to be populated via normalization
+        metadata: resource.metadata,
       }
 
       // Add onEntryLinkClick for entry-organized resources

apps/tc-study/src/components/resources/TranslationNotesViewer/index.tsx

@@ -6,11 +6,13 @@
  */
 
 import { useSignal, useSignalHandler } from '@bt-synergy/resource-panels'
-import { BookOpen, ExternalLink, Loader } from 'lucide-react'
+import { BookOpen, ExternalLink, Loader, FileText } from 'lucide-react'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { useCatalogManager, useCurrentReference, useResourceTypeRegistry } from '../../../contexts'
 import type { EntryLinkClickSignal, TokenClickSignal } from '../../../signals/studioSignals'
 import { checkDependenciesReady } from '../../../utils/resourceDependencies'
+import { getBookTitleStatic } from '../../../utils/bookNames'
+import { ResourceViewerHeader } from '../common/ResourceViewerHeader'
 import { TranslationNoteCard } from './components/TranslationNoteCard'
 import { useTranslationNotesContent } from './hooks/useTranslationNotesContent'
 import { useTATitles } from './hooks/useTATitles'
@@ -19,17 +21,19 @@ import { useAlignedTokens, useQuoteTokens, useScriptureTokens } from '../WordsLi
 import { generateSemanticIdsForQuoteTokens } from '../WordsLinksViewer/utils'
 import { TokenFilterBanner } from '../WordsLinksViewer/components/TokenFilterBanner'
 
+import type { ResourceInfo } from '../../../contexts/types'
+
 interface TranslationNotesViewerProps {
   resourceKey: string
   resourceId: string
-  metadata?: any
+  resource: ResourceInfo
   onEntryLinkClick?: (resourceKey: string, entryId: string) => void
 }
 
 export function TranslationNotesViewer({
   resourceKey,
   resourceId,
-  metadata,
+  resource,
   onEntryLinkClick,
 }: TranslationNotesViewerProps) {
   const currentRef = useCurrentReference()
@@ -404,6 +408,12 @@ export function TranslationNotesViewer({
 
   return (
     <div className="h-full flex flex-col">
+      <ResourceViewerHeader 
+        title={resource.title}
+        icon={FileText}
+        subtitle={resource.languageTitle}
+      />
+      
       {tokenFilter && (
         <TokenFilterBanner
           tokenFilter={tokenFilter}
@@ -442,7 +452,7 @@ export function TranslationNotesViewer({
               <div className="flex items-center gap-2 pb-2 border-b border-gray-200">
                 <BookOpen className="w-4 h-4 text-amber-600" />
                 <h3 className="text-sm font-semibold text-gray-700">
-                  {currentRef.book.toUpperCase()} {verse}
+                  {getBookTitleStatic(currentRef.book)} {verse}
                 </h3>
                 <span className="ml-auto px-2 py-0.5 bg-amber-100 text-amber-700 rounded-full text-xs font-medium">
                   {verseNotes.length}

apps/tc-study/src/components/resources/TranslationQuestionsViewer/index.tsx

@@ -7,12 +7,13 @@
 
 import type { ProcessedQuestions } from '@bt-synergy/resource-parsers'
 import type { ResourceViewerProps } from '@bt-synergy/resource-types'
-import { AlertCircle, CheckCircle, ChevronDown, ChevronUp, HelpCircle } from 'lucide-react'
+import { AlertCircle, CheckCircle, ChevronDown, ChevronUp, HelpCircle, MessageCircleQuestion } from 'lucide-react'
 import { useEffect, useMemo, useState } from 'react'
 import { useCurrentReference } from '../../../contexts'
 import { useLoaderRegistry } from '../../../contexts/CatalogContext'
+import { ResourceViewerHeader } from '../common/ResourceViewerHeader'
 
-export function TranslationQuestionsViewer({ resourceKey, metadata }: ResourceViewerProps) {
+export function TranslationQuestionsViewer({ resourceKey, resource }: ResourceViewerProps & { resource: any }) {
   const [questions, setQuestions] = useState<ProcessedQuestions | null>(null)
   const [loading, setLoading] = useState(false)
   const [error, setError] = useState<string | null>(null)
@@ -161,8 +162,15 @@ export function TranslationQuestionsViewer({ resourceKey, metadata }: ResourceVi
   }
 
   return (
-    <div className="h-full overflow-y-auto bg-gray-50 p-4 space-y-3">
-      {relevantQuestions.map((question, index) => {
+    <div className="h-full flex flex-col">
+      <ResourceViewerHeader 
+        title={resource.title}
+        icon={MessageCircleQuestion}
+        subtitle={resource.languageTitle}
+      />
+      
+      <div className="flex-1 overflow-y-auto bg-gray-50 p-4 space-y-3">
+        {relevantQuestions.map((question, index) => {
         const isExpanded = expandedQuestions.has(question.id)
 
         return (
@@ -212,6 +220,7 @@ export function TranslationQuestionsViewer({ resourceKey, metadata }: ResourceVi
           </div>
         )
       })}
+      </div>
     </div>
   )
 }

apps/tc-study/src/components/resources/WordsLinksViewer/index.tsx

@@ -32,7 +32,7 @@ import { generateSemanticIdsForQuoteTokens, parseTWLink } from './utils'
 export function WordsLinksViewer({
   resourceId,
   resourceKey,
-  metadata,
+  resource,
   wordsLinksContent,
   onEntryLinkClick,
 }: WordsLinksViewerProps) {
@@ -413,9 +413,9 @@ export function WordsLinksViewer({
   return (
     <div className="h-full flex flex-col">
       <ResourceViewerHeader 
-        title={metadata?.title || 'Translation Words Links'}
+        title={resource.title}
         icon={Link}
-        subtitle={metadata?.language_title}
+        subtitle={resource.languageTitle}
       />
 
       {tokenFilter && (

apps/tc-study/src/components/resources/WordsLinksViewer/types.ts

@@ -8,10 +8,12 @@ import type { ProcessedWordsLinks, TranslationWordsLink } from '@bt-synergy/reso
 
 export type { ProcessedWordsLinks, TranslationWordsLink }
 
+import type { ResourceInfo } from '../../../contexts/types'
+
 export interface WordsLinksViewerProps {
   resourceId: string
   resourceKey: string
-  metadata?: any
+  resource: ResourceInfo
   wordsLinksContent?: ProcessedWordsLinks
   onEntryLinkClick?: (resourceKey: string, entryId: string) => void
 }

apps/tc-study/src/components/studio/LinkedPanelsStudio.tsx

@@ -760,23 +760,21 @@ export function LinkedPanelsStudio() {
         viewerProps.isAnchor = isAnchor
       } else if (resource.type === 'words' || resource.category === 'words') {
         // TranslationWordsViewer needs metadata and onEntryLinkClick
-        viewerProps.metadata = resource.metadata || resource // Use stored metadata or resource as fallback
+        viewerProps.metadata = resource.metadata
         viewerProps.onEntryLinkClick = handleOpenEntry
       } else if (resource.type === 'words-links' || resource.category === 'words-links' || resource.type === 'twl') {
         // WordsLinksViewer needs metadata and onEntryLinkClick
-        viewerProps.metadata = resource.metadata || resource // Use stored metadata or resource as fallback
+        viewerProps.metadata = resource.metadata
         viewerProps.onEntryLinkClick = handleOpenEntry
       } else if (resource.type === 'notes' || resource.type === 'tn' || resource.type === 'questions' || resource.type === 'tq') {
         // Translation Notes/Questions viewers need metadata and onEntryLinkClick
-        viewerProps.metadata = resource.metadata || resource // Use stored metadata or resource as fallback
+        viewerProps.metadata = resource.metadata
         if (resource.type === 'notes' || resource.type === 'tn') {
           viewerProps.onEntryLinkClick = handleOpenEntry
         }
       } else {
-        // For any other viewer that might need metadata, provide it if available
-        if (resource.metadata) {
-          viewerProps.metadata = resource.metadata
-        }
+        // For any other viewer that might need metadata, provide it
+        viewerProps.metadata = resource.metadata
       }
 
       return <ViewerComponent {...viewerProps} />

apps/tc-study/src/contexts/types.ts

@@ -41,7 +41,13 @@ export interface ResourceInfo {
   category: string
   toc?: ResourceTOC
 
+  // Full ResourceMetadata object - ALWAYS populated via normalization
+  // This is the single source of truth for resource metadata
+  metadata: any // ResourceMetadata from @bt-synergy/resource-catalog (any for now to avoid circular deps)
+  
   // Additional metadata for resource management
+  // These fields are kept for backward compatibility and convenience,
+  // but metadata object should be the primary source
   language?: string
   languageCode?: string
   languageName?: string // Human-readable language name (e.g., "English", "español, Latinoamérica")
@@ -54,7 +60,6 @@ export interface ResourceInfo {
   ingredients?: any[] // Full ingredient objects from Door43
   version?: string
   contentStructure?: 'book' | 'entry' // How content is organized
-  metadata?: any // Full ResourceMetadata object for viewers that need it (e.g., TranslationWordsViewer)
   release?: any // Release object from Door43 API (contains tag_name, published_at, etc.)
 
   // Extended metadata for resource information display

apps/tc-study/src/lib/stores/workspaceStore.ts

@@ -11,6 +11,7 @@
 import { create } from 'zustand'
 import { immer } from 'zustand/middleware/immer'
 import type { ResourceInfo } from '../../contexts/types'
+import { normalizeResourceInfo } from '../../utils/normalizeResourceInfo'
 
 export interface PanelConfig {
   id: string // Unique panel ID (e.g., 'panel-1', 'panel-2', 'panel-3')
@@ -370,18 +371,21 @@ export const useWorkspaceStore = create<WorkspaceStore>()(
         version: collection.version,
         description: collection.description,
         resources: new Map(
-          (collection.resources || []).map((res: any) => [
-            `${res.owner}/${res.language}/${res.resourceId}`,
-            {
-              key: `${res.owner}/${res.language}/${res.resourceId}`,
+          (collection.resources || []).map((res: any) => {
+            const resourceKey = `${res.owner}/${res.language}/${res.resourceId}`
+            const resourceInfo: ResourceInfo = {
+              key: resourceKey,
               id: res.resourceId,
               title: res.displayName || res.resourceId,
               type: 'unknown',
+              category: 'unknown',
               owner: res.owner,
               language: res.language,
               server: res.server,
-            } as ResourceInfo
-          ])
+            }
+            // Normalize to ensure metadata is populated
+            return [resourceKey, normalizeResourceInfo(resourceInfo)]
+          })
         ),
         panels: collection.panelLayout?.panels?.map((panel: any, idx: number) => ({
           id: panel.id,
@@ -422,9 +426,13 @@ export const useWorkspaceStore = create<WorkspaceStore>()(
         if (!saved) return false
 
         const data = JSON.parse(saved)
+        
+        // Import normalization utility
+        const { normalizeResourceInfoMap } = require('../../utils/normalizeResourceInfo')
+        
         const workspace: WorkspacePackage = {
           ...data,
-          resources: new Map(data.resources || []),
+          resources: normalizeResourceInfoMap(new Map(data.resources || [])),
         }
 
         get().loadPackage(workspace)
@@ -531,6 +539,7 @@ export const useWorkspaceStore = create<WorkspaceStore>()(
               description: metadata.description || door43Data?.description,
               readme: metadata.longDescription || door43Data?.readme,
               license: typeof metadata.license === 'string' ? metadata.license : metadata.license?.id || door43Data?.license,
+              metadata: metadata, // ⭐ Include full metadata
             })
 
             added++
@@ -550,9 +559,12 @@ export const useWorkspaceStore = create<WorkspaceStore>()(
 
     // Resource management
     addResourceToPackage: (resource) => {
+      // Normalize resource to ensure metadata is always populated
+      const normalizedResource = normalizeResourceInfo(resource)
+      
       set((state) => {
         if (state.currentPackage) {
-          state.currentPackage.resources.set(resource.key, resource)
+          state.currentPackage.resources.set(normalizedResource.key, normalizedResource)
           state.isPackageModified = true
         }
       })

apps/tc-study/src/utils/normalizeResourceInfo.ts

@@ -0,0 +1,63 @@
+/**
+ * Resource Metadata Normalization Utility
+ * 
+ * Ensures all ResourceInfo objects have a complete metadata field,
+ * regardless of where they come from (UI, collections, preloaded, etc.)
+ */
+
+import type { ResourceInfo } from '../contexts/types'
+import type { ResourceMetadata } from '@bt-synergy/resource-catalog'
+
+/**
+ * Normalize a ResourceInfo object - promotes metadata to top-level fields
+ * 
+ * Top-level fields are the source of truth. If rich metadata exists (from Door43),
+ * we promote those fields to top-level so all viewers can access them consistently.
+ * 
+ * @param resource - ResourceInfo object (possibly with nested metadata)
+ * @returns ResourceInfo with promoted top-level fields
+ */
+export function normalizeResourceInfo(resource: ResourceInfo): ResourceInfo {
+  // If we have rich metadata from Door43 API, promote it to top-level
+  if (resource.metadata && typeof resource.metadata === 'object') {
+    return {
+      ...resource,
+      // Promote metadata fields to top-level (these become source of truth)
+      title: resource.metadata.title || resource.title,
+      language: resource.metadata.language || resource.language,
+      languageCode: resource.metadata.language || resource.languageCode,
+      languageTitle: resource.metadata.languageTitle || resource.languageTitle,
+      owner: resource.metadata.owner || resource.owner,
+      resourceId: resource.metadata.resourceId || resource.resourceId,
+      type: resource.metadata.type || resource.type,
+      subject: resource.metadata.subject || resource.subject,
+      description: resource.metadata.description || resource.description,
+      version: resource.metadata.version || resource.version,
+      // Keep metadata object for modal displays and detailed info
+      metadata: resource.metadata,
+    }
+  }
+  
+  // No metadata - top-level fields are already set, nothing to promote
+  return resource
+}
+
+/**
+ * Normalize an array of ResourceInfo objects
+ */
+export function normalizeResourceInfoArray(resources: ResourceInfo[]): ResourceInfo[] {
+  return resources.map(normalizeResourceInfo)
+}
+
+/**
+ * Normalize a Map of ResourceInfo objects
+ */
+export function normalizeResourceInfoMap(resourcesMap: Map<string, ResourceInfo>): Map<string, ResourceInfo> {
+  const normalized = new Map<string, ResourceInfo>()
+  
+  for (const [key, resource] of resourcesMap) {
+    normalized.set(key, normalizeResourceInfo(resource))
+  }
+  
+  return normalized
+}