refactor: Relocate real-time mutation broadcasts to model hooks

DECISIONS.md

@@ -59,6 +59,27 @@ We created `app/Services/ActivityService.php` to centralize the creation of syst
 *   **Polymorphic Subject Linking**: System messages are linked to relevant entities (e.g., a `User` who joined a dynamic, a `Ledger` that was created) via a polymorphic `subject` relationship on the `messages` table. This allows system messages on the dashboard to link directly to the relevant entity.
 *   **Seeder Refactoring**: The `DatabaseSeeder` was refactored to use the `ActivityService` to generate all system messages, ensuring consistency.
 
+### 8. Event-Driven Automated System Logging
+We relocated the dynamic system activity message generation out of individual controller endpoints and into the **Eloquent `Mutation` Model's `booted` -> `created` event hook**.
+*   **Unified generation:** Any mutation creation (whether occurring via a controller submission, an automated Pest test factory, or seeders during `php artisan db:seed`) now automatically and reliably generates correct system log messages.
+*   **Database Seeder fixed:** Reverted the database seeder (`DatabaseSeeder.php`) back to using standard clean Eloquent creations. Since model events automatically trigger, `php artisan db:seed` executes cleanly and builds a rich, fully populated database history with system messages out-of-the-box.
+
+### 9. Standardized Policy-Driven UI Capabilities (`can` prop)
+To maintain strict data security and clean up front-end markup, we eliminated unstandardized, hardcoded client-side role checks (like `isOwner` properties or manual `pivot.role === 'owner'` checks) and replaced them completely with dynamic **policy-driven capabilities** returned directly from Laravel policies as `can` objects.
+*   **Centralized checks:** Both the dynamic and ledger show routes return a standard `can` prop to the frontend (e.g., `can: { update: boolean, close: boolean }`).
+*   **Polymorphic Resource Capabilities:** Each mutation model is wrapped in `MutationResource` which appends its own localized policy checks (`update` for approving suggestions, `void` for voiding) at the individual record level.
+*   **State-based policies:** The `MutationPolicy` methods enforce both ownership authorization and state-based business constraints simultaneously (e.g., a mutation can be approved/updated *only* if its status is currently `'pending'`; and can be voided *only* if its status is not `'voided'`). This keeps the Vue templates purely declarative (e.g., `v-if="mutation.can.update"`) and automatically protects the backend controllers against illegal state transitions.
+
+### 10. Ledger-Scoped Predefined Mutation Templates ("Rewards")
+Predefined mutations act as point-based templates ("purchases" or reusable chores) and belong strictly to specific **Ledgers** instead of broad Dynamics.
+*   **Domain Alignment:** Moving the resource nesting under ledgers (`dynamics.ledgers.predefined-mutations`) aligns perfectly with the mental model of spending points on a ledger.
+*   **Type-Less Rewards:** To simplify both the database schema and UI/UX, we eliminated the explicit `type` column ('reward' vs. 'penalty') from predefined mutations. They act as generic point-carrying "Rewards" whose amount can naturellement be positive (earning points) or negative (making a purchase / deducting points) without requiring restrictive explicit categorization.
+
+### 11. Silent XHR Chat Pagination & Smooth Scrolling UX
+To optimize chat-feed performance and improve overall user experience:
+*   **Silent pagination (No URL pollution):** Rather than using Inertia `router.get` visits which push `?page=x` into the browser URL and break history during page reloads, we implemented a **silent background fetch** (using native browser `fetch()`) that queries our dedicated messages JSON API endpoints and prepends older messages silently to the feed.
+*   **Scroll Preservation:** Added `preserveScroll: true` to the Inertia `form.post` call in `Chat.vue` to prevent the active page scroll position from jumping or shifting when a new message is successfully submitted.
+
 ## Initial Database Schema
 
 I will start with a basic schema and evolve it as I build features.

GEMINI.md

@@ -14,4 +14,19 @@ Welcome to the Ledgerrz codebase! This file defines the persistent guidelines, a
 *   **PHP/Laravel:** PHP 8.4 & Laravel 13. Adhere to typed parameters and return values. Ensure controllers extend properly and use required authorization traits (e.g., `AuthorizesRequests`).
 *   **Frontend Styling (BEM):** Replaced direct Tailwind inline utility-class markup with **BEM (Block, Element, Modifier)**. All custom component styles must live inside `<style scoped>` blocks with a relative `@reference "../../css/app.css"` directive to pull variables without duplications.
 *   **Real-time Broadcasting:** Powered by `@laravel/echo-vue` with fallback configurations and Vite deduplication rules configured in `vite.config.ts`.
-*   **Testing:** Powered by Pest PHP (v4). Every backend controller, event, or model change must be validated by running `vendor/bin/pest`.
+*   **Testing & Isolation:** Powered by Pest PHP (v4). Every backend controller, event, or model change must be validated by running tests. To prevent local `.env` variables from polluting the CLI test execution (causing CSRF/session 419 errors), **always** run tests in an isolated environment using:
+    ```bash
+    env -i PATH="$PATH" php artisan test
+    ```
+*   **Standardized Authorization (`can` prop):** Never write manual role checks (such as `pivot.role === 'owner'`) or hardcoded boolean flags (such as `isOwner`) inside Vue pages or components. Instead, always leverage Laravel policies on the backend and pass permissions reactively to the frontend as structured `can` objects (e.g., `can: { update: boolean, close: boolean }`).
+*   **Vue-Defined Breadcrumbs Layout:** All page-specific breadcrumbs should be declared locally inside the page's `.vue` file rather than returned from controllers. For dynamic, prop-dependent paths, always use the Inertia v3 layout callback function inside `defineOptions`:
+    ```typescript
+    defineOptions({
+        layout: (props: any) => ({
+            breadcrumbs: [
+                { title: 'Dynamics', href: route('dynamics.index') },
+                { title: props.dynamic.name, href: route('dynamics.show', props.dynamic.id) }
+            ]
+        })
+    });
+    ```

IDEA.md

@@ -40,4 +40,28 @@ During this session, we successfully built out and verified several core archite
 5. **Broadcasts, Environment & Verification**:
    * Configured real-time notifications utilizing Laravel Reverb.
    * Documented CLI environment test pollution learnings inside `AGENTS.md` to prevent future CSRF `419` errors.
-   * Ensured full production assets compilation (`npm run build`) and achieved **45/45 passing Pest PHP tests with 206 assertions**.
+   * Ensured full production assets compilation (`npm run build`) and achieved **45/45 passing Pest PHP tests with 206 assertions**.
+
+6. **Ledger-Scoped Predefined Mutation Templates ("Rewards")**:
+   * Associated reusable point-based predefined mutation templates under specific Ledgers rather than broad Dynamics, mapping perfectly to the mental model of spending points on a ledger.
+   * Designed them purely as "Rewards" with positive or negative point amounts (handling both demerit-purchases and chores), removing the obsolete `type` categorization for a simpler, type-less, and sleeker UI/UX.
+
+7. **User Activity Profiling & Detail Pages**:
+   * Created a dynamic user detail page (`dynamics.users.show`) scoped to each dynamic. It displays a participant's role, custom display name, fallback real name, and a clean chronological listing of their 10 most recent mutations (activities) in that dynamic.
+
+8. **Polymorphic System Message placeholders & Dynamic Client-Side Linking**:
+   * Refactored system log activity messages to use native `<user:userId>` placeholders and associated them with polymorphic `subject_id` and `subject_type` objects.
+   * On the client-side, the chat component parses these placeholders into rich, clickable links to User Profiles, and dynamically matches and wraps referenced ledger names into links pointing directly to the ledger show page.
+   * Added backend-side placeholder resolution inside `ActivityService` for the dashboard, ensuring unread system logs translate cleanly to real names across multiple dynamics.
+
+9. **Vite/Inertia v3 Layout Callback Breadcrumbs**:
+   * Utilized Inertia v3's powerful new layout callback API inside Vue page `defineOptions` to reactively resolve page-specific dynamic breadcrumbs at runtime using parsed page props, making the pages self-contained and keeping PHP controllers beautifully slim.
+
+10. **Silent background Chat Pagination & Smooth Scrolling UX**:
+    * Implemented silent background XHR queries (using native browser `fetch()`) on our dedicated message JSON API routes to load older chat pages, completely bypassing browser history/URL pollution and preserving page state on refreshes.
+    * Integrated `preserveScroll: true` inside chat form submissions to completely prevent scroll jumps when sending messages.
+
+11. **Standardized Policy-Driven UI Capabilities**:
+    * Eliminated unstandardized client-side role checks and boolean flags, replacing them with structured `can` capability objects returned directly from Laravel policies.
+    * Combined permission validation with state-based business constraints in `MutationPolicy` (e.g., suggestions can be approved/rejected only if `'pending'`; and voided only if not `'voided'`), securing both the frontend action buttons and backend controllers simultaneously.
+    * Achieved **65/65 passing Pest PHP tests with 333 assertions**.

app/Http/Controllers/DynamicController.php

@@ -62,7 +62,7 @@ class DynamicController extends Controller
             'dynamic' => new DynamicResource($dynamic),
             'ledgers' => LedgerResource::collection($dynamic->ledgers),
             'participants' => UserResource::collection($dynamic->participants),
-            'messages' => MessageResource::collection($dynamic->chat->messages()->with(['user', 'media'])->latest()->paginate(10)),
+            'messages' => MessageResource::collection($dynamic->chat->messages()->with(['user', 'media'])->latest()->paginate(\App\Models\Message::PAGINATION_COUNT)),
             'can' => [
                 'update' => $request->user()->can('update', $dynamic),
             ],
@@ -73,7 +73,7 @@ class DynamicController extends Controller
     {
         $this->authorize('view', $dynamic);
 
-        return MessageResource::collection($dynamic->chat->messages()->with(['user', 'media'])->latest()->paginate(10));
+        return MessageResource::collection($dynamic->chat->messages()->with(['user', 'media'])->latest()->paginate(\App\Models\Message::PAGINATION_COUNT));
     }
 
     /**

app/Http/Controllers/LedgerController.php

@@ -87,7 +87,7 @@ class LedgerController extends Controller
             'ledger' => new LedgerResource($ledger),
             'mutations' => MutationResource::collection($ledger->mutations),
             'participants' => UserResource::collection($dynamic->participants),
-            'messages' => MessageResource::collection($dynamic->chat->messages()->with(['user', 'media'])->latest()->paginate(10)),
+            'messages' => MessageResource::collection($dynamic->chat->messages()->with(['user', 'media'])->latest()->paginate(\App\Models\Message::PAGINATION_COUNT)),
             'can' => [
                 'update' => $request->user()->can('update', $ledger),
                 'close' => $request->user()->can('close', $ledger),
@@ -99,7 +99,7 @@ class LedgerController extends Controller
     {
         $this->authorize('view', $ledger);
 
-        return MessageResource::collection($dynamic->chat->messages()->with(['user', 'media'])->latest()->paginate(10));
+        return MessageResource::collection($dynamic->chat->messages()->with(['user', 'media'])->latest()->paginate(\App\Models\Message::PAGINATION_COUNT));
     }
 
     /**

app/Http/Controllers/MutationController.php

@@ -71,9 +71,6 @@ class MutationController extends Controller
             return $mutation;
         });
 
-        // Broadcast the real-time creation event!
-        broadcast(new MutationCreated($mutation));
-
         return redirect()->route('dynamics.ledgers.show', [$dynamic, $ledger]);
     }
 
@@ -149,9 +146,6 @@ class MutationController extends Controller
         }
         broadcast(new MessageSent($dynamicMsg));
 
-        // Broadcast the real-time update event!
-        broadcast(new MutationUpdated($mutation));
-
         return redirect()->back();
     }
 

app/Models/Message.php

@@ -14,6 +14,8 @@ class Message extends Model
     /** @use HasFactory<MessageFactory> */
     use HasFactory;
 
+    const PAGINATION_COUNT = 6;
+
     protected $fillable = [
         'chat_id',
         'user_id',

app/Models/Mutation.php

@@ -92,6 +92,15 @@ class Mutation extends Model
                 ]);
             }
             broadcast(new MessageSent($dynamicMsg));
+
+            // Trigger the real-time creation broadcast dynamically
+            broadcast(new \App\Events\MutationCreated($mutation));
+        });
+
+        static::updated(function (Mutation $mutation) {
+            if ($mutation->wasChanged('status')) {
+                broadcast(new \App\Events\MutationUpdated($mutation));
+            }
         });
     }
 

resources/js/components/Chat.vue

@@ -2,7 +2,7 @@
 import { useForm, usePage, router } from '@inertiajs/vue3';
 import { useEcho, echoIsConfigured, configureEcho } from '@laravel/echo-vue';
 import { Paperclip, Info } from '@lucide/vue';
-import { ref, computed } from 'vue';
+import { ref, computed, watch } from 'vue';
 import { route } from 'ziggy-js';
 
 const props = withDefaults(
@@ -33,39 +33,86 @@ const props = withDefaults(
             } | null;
         }>;
         dynamicId: string;
+        ledgerId?: string | null;
         initialMessages?: {
             data: Array<any>;
-            next_page_url: string | null;
+            next_page_url?: string | null;
+            links?: {
+                next: string | null;
+            } | null;
+            current_page?: number;
+            meta?: {
+                current_page: number;
+            } | null;
         } | null;
     }>(),
     {
         participants: () => [],
         initialMessages: null,
+        ledgerId: null,
     }
 );
 
+const getNextPageUrl = (paginator: any) => {
+    return paginator?.links?.next ?? paginator?.next_page_url ?? null;
+};
+
+const getCurrentPage = (paginator: any) => {
+    return paginator?.meta?.current_page ?? paginator?.current_page ?? 1;
+};
+
 const messages = ref(
     props.initialMessages
         ? props.initialMessages.data.slice().reverse()
         : (props.chat.messages || []).slice()
 );
-const nextPageUrl = ref(props.initialMessages?.next_page_url || null);
+const nextPageUrl = ref(getNextPageUrl(props.initialMessages));
+const currentPageNum = ref(1);
+
+watch(
+    () => props.initialMessages,
+    (newVal) => {
+        if (newVal && getCurrentPage(newVal) === 1) {
+            messages.value = newVal.data.slice().reverse();
+            nextPageUrl.value = getNextPageUrl(newVal);
+            currentPageNum.value = 1;
+        }
+    },
+    { deep: true }
+);
+
+watch(
+    () => props.chat.messages,
+    (newVal) => {
+        if (!props.initialMessages && newVal) {
+            messages.value = newVal.slice();
+        }
+    },
+    { deep: true }
+);
 
 function loadMoreMessages() {
     if (!nextPageUrl.value) {
         return;
     }
 
-    router.get(nextPageUrl.value, {}, {
-        preserveState: true,
-        preserveScroll: true,
-        only: ['messages'],
-        onSuccess: (page) => {
-            const newMessages = page.props.messages as { data: Array<any>; next_page_url: string | null };
-            messages.value = [...newMessages.data.reverse(), ...messages.value];
-            nextPageUrl.value = newMessages.next_page_url;
-        },
-    });
+    currentPageNum.value++;
+
+    const apiRouteName = props.ledgerId ? 'dynamics.ledgers.messages' : 'dynamics.messages';
+    const apiParams = props.ledgerId ? [props.dynamicId, props.ledgerId] : [props.dynamicId];
+    const url = route(apiRouteName, [...apiParams, { page: currentPageNum.value }]);
+
+    fetch(url)
+        .then((res) => res.json())
+        .then((json) => {
+            const data = json?.data || [];
+            messages.value = [...data.slice().reverse(), ...messages.value];
+            nextPageUrl.value = getNextPageUrl(json);
+        })
+        .catch((err) => {
+            console.error('Failed to load older messages:', err);
+            currentPageNum.value--;
+        });
 }
 
 if (!echoIsConfigured()) {
@@ -217,6 +264,7 @@ function isOwnMessage(messageUserId: number | null): boolean {
 
 function submit() {
     form.post(route('chats.messages.store', props.chat.id), {
+        preserveScroll: true,
         onSuccess: () => {
             form.reset();
 

resources/js/components/MutationList.vue

@@ -170,25 +170,25 @@ function getAmountClass(amount: number): string {
 
                 <!-- Owner Approve/Reject Actions -->
                 <div
-                    v-if="mutation.can.update || mutation.can.void"
+                    v-if="mutation.can?.update || mutation.can?.void"
                     class="c-mutation-list__actions"
                 >
                     <button
-                        v-if="mutation.can.update"
+                        v-if="mutation.can?.update"
                         @click="updateStatus(mutation.id, 'approved')"
                         class="c-mutation-list__approve-btn"
                     >
                         Approve
                     </button>
                     <button
-                        v-if="mutation.can.update"
+                        v-if="mutation.can?.update"
                         @click="updateStatus(mutation.id, 'rejected')"
                         class="c-mutation-list__reject-btn"
                     >
                         Reject
                     </button>
                     <button
-                        v-if="mutation.can.void"
+                        v-if="mutation.can?.void"
                         @click="voidMutation(mutation.id)"
                         class="c-mutation-list__void-btn"
                     >

resources/js/pages/Dynamics/Index.vue

@@ -114,6 +114,7 @@ defineProps<{
 
 .c-dynamics-index__item-desc {
     @apply mt-2 text-sm text-gray-600 dark:text-gray-400;
+    white-space: pre-line;
 }
 
 .c-dynamics-index__empty {

resources/js/pages/Ledgers/Show.vue

@@ -275,7 +275,7 @@ function isOwnerUser(userId: number): boolean {
                 @open-lightbox="openLightbox"
             />
 
-            <Chat :chat="dynamic.chat" :initial-messages="messages" :participants="dynamic.participants" :dynamic-id="dynamic.id" />
+            <Chat :chat="dynamic.chat" :initial-messages="messages" :participants="dynamic.participants" :dynamic-id="dynamic.id" :ledger-id="ledger.id" />
         </div>
     </div>