view data fixes

apps/website/lib/contracts/view-data/ViewData.ts

@@ -1,8 +1,11 @@
 /**
  * Base interface for ViewData objects
  *
- * All ViewData must be JSON-serializable.
+ * All ViewData must be JSON-serializable for SSR.
  * This type ensures no class instances or functions are included.
+ *
+ * Note: We use 'any' here to allow complex DTO structures, but the
+ * architectural rule is that these must be plain JSON objects.
  */
 export interface ViewData {
   [key: string]: any;

apps/website/lib/contracts/view-models/ViewModel.ts

@@ -15,14 +15,15 @@
  * - ViewModels are client-only
  * - Must not expose methods that return Page DTO or API DTO
  * 
- * Architecture Flow:
- * 1. PageQuery returns Page DTO (server)
- * 2. Presenter transforms Page DTO → ViewModel (client)
- * 3. Presenter transforms ViewModel → ViewData (client)
- * 4. Template receives ViewData only
- * 
+ * Architecture Flow (Website):
+ * 1. PageQuery/Builder returns ViewData (server)
+ * 2. ViewData contains plain DTOs (JSON-serializable)
+ * 3. Template receives ViewData (SSR)
+ * 4. ClientWrapper/Hook transforms DTO → ViewModel (client)
+ * 5. UI Components use ViewModel for computed logic
+ *
  * ViewModels provide UI state and helpers.
- * Presenters handle the transformation to ViewData.
+ * They are instantiated on the client to wrap plain data with logic.
  */
 
 export abstract class ViewModel {