view data fixes

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.