view data fixes

docs/architecture/website/BUILDERS.md

@@ -36,7 +36,7 @@ Transform API DTOs directly into ViewData for templates.
 **Pattern**:
 ```typescript
 export class LeagueViewDataBuilder {
-  static build(apiDto: LeagueApiDto): LeagueDetailViewData {
+  static build(apiDto: LeagueApiDto): LeagueDetailViewData extends ViewData {
     return {
       leagueId: apiDto.id,
       name: apiDto.name,
@@ -192,7 +192,7 @@ export class RaceResultsDataTransformer {
 ✅ **Correct**: Use ViewDataBuilder
 ```typescript
 export class RaceResultsViewDataBuilder {
-  static build(...): RaceResultsViewData { ... }
+  static build(...): RaceResultsViewData extends ViewData { ... }
 }
 ```
 

docs/architecture/website/VIEW_DATA.md

@@ -39,18 +39,21 @@ const [viewModel, setViewModel] = useState<ViewModel | null>(null);
 
 useEffect(() => {
   const apiDto = await apiClient.get();
-  const vm = ViewModelBuilder.build(apiDto);
+  const viewData = ViewDataBuilder.build(apiDto);
+  const vm = ViewModelBuilder.build(viewData);
   setViewModel(vm);
 }, []);
 
-// Template receives ViewData from ViewModel
-return viewModel ? <Template viewData={viewModel.viewData} /> : null;
+// Template receives ViewData directly
+return viewModel ? <Template viewData={viewData} /> : null;
 ```
 
 Templates MUST NOT compute derived values.
 
 ViewData Builders MUST NOT call the API.
 
+**Important:** ViewModels are built from ViewData, not directly from DTOs. This ensures ViewModels are decoupled from the API transport layer.
+
 ## 4) Formatting and SEO
 
 ViewData is responsible for providing **fully formatted strings** to Templates for Server-Side Rendering (SSR).
@@ -72,7 +75,18 @@ Reason: SSR and browser outputs can differ.
 Localization MUST NOT depend on runtime locale APIs.
 If localized strings are required, they MUST be provided as deterministic inputs (for example via API-provided labels or a deterministic code-to-label map) and passed through ViewData Builders into ViewData.
 
-## 5) Relationship to Display Objects
+## 5) Relationship to ViewModels
+
+ViewData serves as the stable, serializable contract between the server and client. It is:
+- The input for Templates (both SSR and Client)
+- The input for ViewModelBuilders (Client-side state initialization)
+
+ViewModels are built from ViewData, not from DTOs. This ensures:
+- ViewModels remain decoupled from API transport concerns
+- ViewModels can be initialized from any source that provides ViewData
+- The ViewModel layer is purely for client-side interactive state
+
+## 6) Relationship to Display Objects
 
 Display Objects are used to implement formatting/mapping, but their instances MUST NOT be stored inside ViewData.
 

docs/architecture/website/VIEW_MODELS.md

@@ -76,7 +76,7 @@ This repository distinguishes **Page DTO**, **ViewModel**, and **ViewData**:
 Rules (website):
 
 1) View Models are created in client code only.
-2) View Models are created from Page DTOs.
+2) View Models are created from **ViewData** (not from DTOs).
 3) Templates MUST NOT accept View Models; Templates accept ViewData only.
 4) View Models MUST compose Display Objects and produce ViewData (primitive outputs only).