# portal.Rhemawavetech.com

SvelteKit 2 + Svelte 5 (runes) + Tailwind CSS v4 + Prisma 7 + PostgreSQL + Better-Auth.

## Quick start

```sh
npm install          # engine-strict=true in .npmrc
npm run prepare      # svelte-kit sync (generate types)
npm run dev          # vite dev on :5173
```

Requires `.env` with at least `DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`.

## Commands

| npm run ...                | What it does                                     |
| -------------------------- | ------------------------------------------------ |
| `check`                    | `svelte-kit sync && svelte-check` (typecheck)    |
| `lint`                     | `prettier --check . && eslint .` (order matters) |
| `format`                   | `prettier --write .`                             |
| `test`                     | `vitest --run` (single run)                      |
| `test:unit`                | `vitest` (watch mode)                            |
| `migrate -- --name <name>` | Create a Prisma migration                        |
| `deploy`                   | Apply pending migrations                         |
| `build`                    | Production build (adapter-node)                  |

## Testing quirks

- **Two Vitest projects**: `client` (Playwright/Chromium headless, `src/**/*.svelte.{test,spec}.{js,ts}`) and `server` (node env, everything else — `src/**/*.{test,spec}.{js,ts}` excluding `.svelte.*`). Tests co-located beside source files.
- **`expect: { requireAssertions: true }`** — every test must assert something. No assertions = test fails.
- **All route tests mock `$lib/db`** (Prisma client) and `$lib/auth-client`/`$lib/auth` via `vi.mock()`. Stub factories in `src/lib/test-utils.ts`.
- **No `.env.test`** — mocking `$lib/db` makes real DB unnecessary.
- **Mock `$app/forms`** for any component using `use:enhance` — provide `enhance: () => () => {}` (action → destroy fn).
- **Mock TipTap** for client tests rendering ProclamationForm — the Svelte 5 component mock pattern is a function `($anchor: Element) => { …; $anchor.replaceWith(div); }`.

## Architecture notes

- **Route groups**: `(protected)/` requires auth + profile; `(user)/` is user-facing; `admin/` requires roleId <= 3 (STAFF+).
- **Admin forms**: Each route has its own form component (e.g. `ProclamationForm.svelte`, `CategoryForm.svelte`). The generic `AdminForm.svelte` / `AdminPage.svelte` were **deleted**. Registry config (`registry.ts`) still provides metadata, list fields, search fields, relation options, etc., but forms are hand-written per route.
- **Prisma client** generated to `src/lib/generated/prisma/` (not `node_modules/.prisma/client`). Lazy singleton via Proxy in `src/lib/db.ts`.
- **Better-Auth** server instance in `src/lib/auth.ts`, browser client in `src/lib/auth-client.ts`. Session fetched in `src/hooks.server.ts`.
- **Roles**: integer hierarchy (SUPER=1, ADMIN=2, STAFF=3, USER=4). `canAccessAdmin` checks roleId <= 3.
- **Payments are stubbed** (`src/lib/payments.ts` — setTimeout + console.log).

## Formatting conventions

- Tabs, single quotes, no trailing commas, 100 print width (enforced by Prettier).
- Svelte 5 runes only (`$state`, `$derived`, `$effect`, `$props`). No legacy stores (`writable`, `derived`, etc.).

---

## Svelte 5 Runes Gotchas & Patterns

### `$state` initialization vs `$effect` sync

State variables declared with `$state('')` are set once on component mount. To keep them in sync with a changing `$props()` value, use a **separate `$effect`**:

```svelte
<script lang="ts">
	let { record = {} as Record<string, unknown> } = $props();

	let name = $state('');
	let freq = $state('');

	// Sync local state when prop changes
	$effect(() => {
		name = String(record.name ?? '');
		freq = String(record.solfeggioFrequencyId ?? '');
	});
</script>
```

This is the **only correct pattern** for form fields that edit an existing record. Do NOT initialize `$state` directly from the prop — that only captures the initial value and won't re-sync when the parent changes the record (e.g. switching from one row to another in a modal).

### `$effect` ordering matters

Effects run in declaration order. If you have multiple effects, the first one's writes are applied before the second one runs. This matters for the `dirty` flag:

```svelte
let dirty = $state(false);

// Runs first — resets dirty on mount / record change
$effect(() => {
	dirty = false;
});

// Runs second — syncs field values
$effect(() => {
	name = String(record.name ?? '');
	// …
});
```

Both effects run synchronously during mount, so by the time the browser paints, all state is consistent.

### `bind:value` on `<select>` is broken with `$effect`-driven state

**DO NOT USE** `bind:value={stateVar}` on `<select>` elements when the state is set from a `$effect`. Svelte 5's select binding does not respond to `$state` changes triggered inside `$effect`. Instead:

**Use `selected` on `<option>` + `onchange` on `<select>`:**

```svelte
<select name="solfeggioFrequencyId" onchange={(e) => freq = (e.target as HTMLSelectElement).value}>
	<option value="">-- Select --</option>
	{#each options as opt (opt.value)}
		<option value={opt.value} selected={String(opt.value) === freq}>{opt.label}</option>
	{/each}
</select>
```

This pattern applies to ALL `<select>` elements in form components. The `value={stateVar}` prop directive also does not work reliably — always use `selected` on options.

### `bind:value` on `<input>` works fine

Unlike `<select>`, `bind:value` on `<input type="text">` works correctly with `$effect`-driven state. Feel free to use it for text inputs.

### `$props()` destructuring

Always destructure `$props()` with defaults:

```svelte
let {
	record = {} as Record<string, unknown>,
	fieldErrors = {} as Record<string, string>,
	isSuper = false,
}: { record?: Record<string, unknown>; … } = $props();
```

The type annotation on the destructuring object is REQUIRED for Svelte 5 to infer prop types. Default values are used when the parent doesn't pass that prop.

### Component mocking for client tests

When mocking a Svelte 5 component in `vi.mock`, use a function that takes `($anchor, props)`:

```ts
vi.mock('$lib/components/tiptap/TipTap.svelte', () => ({
	default: ($anchor: Element, _props: Record<string, unknown>) => {
		const div = document.createElement('div');
		div.setAttribute('data-testid', 'tiptap-mock');
		$anchor.replaceWith(div);
	}
}));
```

---

## Testing Patterns & Gotchas

### What tests to write

For every admin route, write BOTH:

1. **Server test** (`page.server.spec.ts`): Test the `load` function and all `actions` (upsert, delete). Cover role-based access control (Super vs non-Super content stripping, rejection of unauthorized mutations). Mock `$lib/db` and `$lib/svelte-admin/crud`.

2. **Client test** (`Component.svelte.spec.ts`): Test the form component rendering in Playwright/Chromium. Cover:
   - All fields render
   - Pre-fill on edit (name input, select values)
   - Conditional field visibility (e.g. content hidden for non-Super)
   - Submit button disabled/enabled by dirty state
   - No visual regression testing — only functional assertions.

### Available Playwright/Vitest Browser Locator API

These methods are available on `page` from `vitest/browser`:

| Method              | Works? | Example                                       |
| ------------------- | ------ | --------------------------------------------- |
| `getByRole`         | ✅     | `page.getByRole('textbox', { name: 'Name' })` |
| `getByText`         | ✅     | `page.getByText('Content')`                   |
| `getByPlaceholder`  | ✅     | `page.getByPlaceholder('Email Address')`      |
| `getByAltText`      | ✅     | `page.getByAltText('Sign In with Google')`    |
| `getByTestId`       | ✅     | `page.getByTestId('tiptap-mock')`             |
| `getByLabel`        | ❌     | Not available in this version                 |
| `getByDisplayValue` | ❌     | Not available in this version                 |

For label-identified elements, use `getByRole` with `name` option:

- Text inputs → `getByRole('textbox', { name: /^Name$/ })`
- Selects → `getByRole('combobox', { name: /^Frequency$/ })`
- Buttons → `getByRole('button', { name: 'Save' })`

**Always use regex `{ name: /^Exact$/ }`** for role queries to avoid strict-mode violations from substring matches (e.g. `'Category'` matching both `'Category'` and `'Sub-Category'`).

### Querying select values in client tests

Since `bind:value` on selects doesn't work with `$effect`-driven state, and we use `selected` on `<option>` instead, you can check the select's value directly:

```ts
const el = (await page
	.getByRole('combobox', { name: /^Frequency$/ })
	.element()) as HTMLSelectElement;
expect(el.value).toBe('2');
```

The `.element()` call returns the underlying DOM element. This works synchronously because `selected` is set during render.

### Server test patterns

**Always call `vi.clearAllMocks()` in `beforeEach`.**

Mock `$lib/db` with the exact Prisma model methods the code under test uses:

```ts
vi.mock('$lib/db', () => ({
	prisma: {
		proclamation: {
			findMany: vi.fn(),
			findUnique: vi.fn(),
			create: vi.fn(),
			update: vi.fn(),
			delete: vi.fn()
		},
		proclamationCategory: { findMany: vi.fn() }
	}
}));
```

Mock `$lib/svelte-admin/crud` when the route uses custom upsert/delete logic:

```ts
vi.mock('$lib/svelte-admin/crud', () => ({
	loadRecords: vi.fn(),
	deleteRecord: vi.fn(),
	superFormErrorsToFieldErrors: vi.fn(() => ({ error: '', fieldErrors: {} }))
}));
```

Use `createLocals(mockUser({ roleId: 4 }) as any)` to simulate different user roles.
Use `createFormRequest({ name: 'test' })` for form submissions.
Use `.catch((e) => e)` + `isHttpError()` for error assertions.

### `createLocals` nuances

- `createLocals()` (no arg) → unauthenticated (session is `undefined`).
- `createLocals(mockUser() as any)` → authenticated with the mock user object.
- Cast to `any` when passing to load/action functions: `{ locals: createLocals(mockUser()) } as any`.

### `vi.mock` hoisting

All `vi.mock()` calls must be at the top level of the test file. Values needed inside `vi.mock` factories must use `vi.hoisted()`:

```ts
const { mockFn } = vi.hoisted(() => ({ mockFn: vi.fn() }));
vi.mock('$lib/some-module', () => ({ default: mockFn }));
```

Imports of the mocked module must come AFTER `vi.mock()` calls.

---

## Admin Form Architecture

### Per-route form components

Each admin route under `admin/[model]/` has its own form component (e.g. `ProclamationForm.svelte`). These components:

- Receive `record`, `fieldErrors`, `formError`, `relationOptionsData`, and model-specific extras (e.g. `categories`, `isSuper`) as props.
- Use `$state` + `$effect` for field values (see "Svelte 5 Runes Gotchas" above).
- Use `selected` on `<option>` for selects.
- Use `oninput` on the `<form>` to track dirty state: `<form oninput={markDirty}>`.
- Submit via `action="?/upsert"` with SvelteKit's `use:enhance`.

### Server actions

Routes with custom requirements (like proclamation's Super-only restriction) override the generic `upsertRecord`/`deleteRecord` with their own actions. The generic functions in `crud.ts` are still available and used by simpler routes.

### Super-only proclamation restriction

- **Load**: content field is stripped from records for non-Super users before returning.
- **Upsert**: returns `{ success: false, error: 'Only Super admins can edit proclamations' }` for non-Super.
- **Delete**: same early return for non-Super; delegates to `deleteRecord` for Super.
- **Content field in form**: wrapped in `{#if isSuper}` block — hidden from non-Super users.
- **Row click / New button**: disabled for non-Super in `+page.svelte`.

### Dirty-state submit pattern

When editing an existing record (`record.id` is truthy), the submit button is disabled until the user modifies at least one field. The form tracks dirtiness with `let dirty = $state(false)` and a `markDirty()` handler:

```svelte
<form oninput={markDirty}>
	<button disabled={!!record?.id && !dirty}>Save</button>
</form>
```

The `$effect` resets `dirty = false` on mount (when the record prop changes).

---

## Generated / build artifacts

- `.svelte-kit/` — SvelteKit generated types (gitignored)
- `src/lib/generated/prisma/` — Prisma client output (not gitignored; regenerate with `npx prisma generate`)