feat(frontend): M1 frontend foundation (Vue 3 + Inertia 3 + TypeScript, Node 24)

.github/workflows/ci.yml

@@ -33,6 +33,12 @@ jobs:
           coverage: none
           tools: composer:v2
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
       - name: Validate Composer
         run: composer validate --strict
 
@@ -53,5 +59,44 @@ jobs:
       - name: Static analysis
         run: vendor/bin/phpstan analyse --no-progress
 
+      - name: Install frontend dependencies
+        run: npm ci
+
+      # The only frontend build in CI: the Inertia feature tests below
+      # render @vite and need public/build/manifest.json.
+      - name: Build frontend
+        run: npm run build
+
       - name: Run tests
         run: php artisan test
+
+  frontend:
+    name: Node 24 / Vue 3
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Show Node version
+        run: node --version && npm --version
+
+      # engine-strict in .npmrc makes this fail on any Node other than ^24.15.
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Run tests
+        run: npm test
+
+      # Last, so a newly published advisory does not hide the results above.
+      - name: Audit production dependencies
+        run: npm audit --omit=dev

.npmrc

@@ -1,2 +1,3 @@
 ignore-scripts=true
 audit=true
+engine-strict=true

.nvmrc

@@ -0,0 +1 @@
+24

app/Http/Middleware/HandleInertiaRequests.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Illuminate\Http\Request;
+use Inertia\Middleware;
+
+class HandleInertiaRequests extends Middleware
+{
+    /**
+     * Locales written right to left.
+     *
+     * @var list<string>
+     */
+    private const array RTL_LOCALES = ['ar'];
+
+    /**
+     * The root template that's loaded on the first page visit.
+     *
+     * @var string
+     */
+    protected $rootView = 'app';
+
+    /**
+     * Define the props that are shared by default.
+     *
+     * Keep in sync with resources/js/types/shared.ts until ADR-0018
+     * replaces it with generated types.
+     *
+     * @return array<string, mixed>
+     */
+    public function share(Request $request): array
+    {
+        $locale = app()->getLocale();
+
+        return [
+            ...parent::share($request),
+            'locale' => $locale,
+            'direction' => in_array($locale, self::RTL_LOCALES, true) ? 'rtl' : 'ltr',
+        ];
+    }
+}

bootstrap/app.php

@@ -1,5 +1,6 @@
 <?php
 
+use App\Http\Middleware\HandleInertiaRequests;
 use Illuminate\Foundation\Application;
 use Illuminate\Foundation\Configuration\Exceptions;
 use Illuminate\Foundation\Configuration\Middleware;
@@ -12,7 +13,9 @@
         health: '/up',
     )
     ->withMiddleware(function (Middleware $middleware): void {
-        //
+        $middleware->web(append: [
+            HandleInertiaRequests::class,
+        ]);
     })
     ->withExceptions(function (Exceptions $exceptions): void {
         $exceptions->shouldRenderJsonWhen(

composer.json

@@ -7,6 +7,7 @@
     "license": "MIT",
     "require": {
         "php": "^8.5",
+        "inertiajs/inertia-laravel": "^3.0",
         "laravel/framework": "^13.17",
         "laravel/tinker": "^3.0"
     },

docs/engineering/definition-of-done.md

@@ -8,8 +8,11 @@ item that *does* apply is not.
 ## Always
 
 - [ ] Acceptance criteria / the stated problem are actually satisfied.
-- [ ] `composer check` passes locally — `composer validate --strict`,
-      `composer audit`, Pint, PHPStan, Pest.
+- [ ] The local gate passes, in this order (the frontend is built before
+      `composer check` because the Inertia feature tests read the Vite
+      manifest): `npm ci` → `npm run build` → `composer check`
+      (`composer validate --strict`, `composer audit`, Pint, PHPStan, Pest)
+      → `npm run typecheck` → `npm test` → `npm audit --omit=dev`.
 - [ ] CI is green on the PR.
 - [ ] No secrets, credentials, or real data committed.
 - [ ] The diff is focused — no unrelated refactoring, formatting sweeps, or

docs/engineering/security.md

@@ -63,6 +63,19 @@ endpoints.
 
 - `composer audit` runs in CI and in `composer check`. A new advisory fails the
   build; triage it before merging unrelated work.
+- `npm audit --omit=dev` runs last in the `Node 24 / Vue 3` CI job and is
+  blocking. It covers every package shipped to browsers. An advisory that
+  reaches a production dependency blocks merging immediately.
+- Development-only npm advisories do not block CI, but each one is recorded
+  below with its package chain, why it is accepted and when it was last
+  reassessed. Reassess with a full `npm audit` whenever `@vue/test-utils` or
+  `vitest` is updated, and at the start of each milestone.
+
+  | Advisory | Chain | Why accepted | Last reassessed |
+  |---|---|---|---|
+  | [GHSA-3g3m-2fjr-6pw4](https://github.com/advisories/GHSA-3g3m-2fjr-6pw4) (moderate, `glob` 13.0.6) | `@vue/test-utils` → `js-beautify` → `glob` | Test-time only; never bundled or shipped. No fixed `@vue/test-utils` 2.5.x yet; `npm audit fix --force` would downgrade to 2.4.11 | 2026-11-05 |
+  | [GHSA-g3hv-75wg-m249](https://github.com/advisories/GHSA-g3hv-75wg-m249) (moderate, `minimatch` 10.2.6) | `@vue/test-utils` → `js-beautify` → `editorconfig` / `glob` → `minimatch` | Same as above; inputs are our own repository paths, not untrusted patterns | 2026-11-05 |
+
 - Add a dependency only when this phase needs it. Prefer a small, maintained
   package or a few lines of first-party code over a large transitive tree.