# Frontend context

Read `ai/shared.md` first. This file covers frontend-specific rules.

## Current state

The Vue frontend has not been scaffolded yet. The backend has Inertia Laravel
installed and an Inertia route, but there is no `package.json`, Vue source
tree, Vite configuration, or frontend test setup.

- Do not create the frontend unless the user explicitly asks.
- Do not invent a frontend directory, package manager, dependency version, or
  command before the scaffold establishes it.
- When the frontend is created, update this file with its actual paths,
  package versions, scripts, and testing tools.

## Vue conventions

Apply these rules once a Vue 3 frontend exists:

- Use the Composition API and `<script setup lang="ts">`.
- Use PascalCase component filenames.
- Keep page, component, composable, and store responsibilities distinct.
- Prefer small components with explicit props and emitted events.
- Keep component styles scoped unless the scaffold establishes a deliberate
  global styling system.
- Follow the routing and page conventions established by the chosen Inertia
  or Vue Router scaffold. Do not mix the two approaches without an explicit
  architectural reason.
- Inspect similar files before introducing a new component, composable, store,
  or data-access pattern.

## TypeScript

- Enable and preserve strict mode.
- Do not use `any`. Model unknown external values as `unknown` and narrow or
  validate them.
- Derive types from runtime schemas when a schema library is adopted. Do not
  maintain a hand-written type that can drift from its validation schema.
- Validate payloads at trust boundaries, especially backend responses and
  user-submitted forms.
- Keep request and response types close to the API or store boundary that owns
  them.
- Add a path alias only when it is configured consistently in Vite,
  TypeScript, tests, and Cypress.

## State and API access

- Use the state-management approach chosen by the scaffold consistently.
- Keep server data fetching and transformation at an API/store boundary, not
  scattered through presentation components.
- Represent loading, empty, success, validation-error, and unexpected-error
  states explicitly.
- Do not cast unchecked JSON directly to an application interface.
- Keep read and write payload types separate when their shapes differ.

## Testing

Use layered tests once the frontend test setup exists:

- Unit tests cover pure transformations, composables, store logic, computed
  values, and formatting.
- Component tests cover rendering, events, form behavior, and conditional UI.
- Cypress tests cover routing, multi-page flows, and request wiring.
- Prefer the cheapest layer that proves the behavior.
- Import test functions explicitly rather than relying on globals unless the
  scaffold deliberately configures globals.
- Build test data with small typed builders instead of repeated bare object
  literals.

## Frontend/backend test boundary

- Mock backend requests in frontend tests.
- A frontend test should verify how the UI consumes a response and which
  request it sends, not retest Laravel's business rules.
- Test backend persistence, validation, authentication, and mail behavior in
  PHPUnit.
- Keep mocked response bodies typed against the frontend's exported API or
  store types.
- When runtime schemas exist, parse mock-builder output through the same
  schema so drift fails at the test boundary.

## Before completing frontend work

- Run the formatter, linter, type checker, unit tests, and Cypress scripts
  defined by the frontend's `package.json`.
- Do not substitute a hand-picked subset for the repository's eventual full
  frontend gate.
- If the frontend cannot run because the scaffold or a required service is
  absent, report the precise environmental or baseline failure.