OSIT-AE-App-Svelte/documentation/GUIDE__Development.md

# Aether Development SOP (Frontend)
> **Version:** 1.2 (2026-03-17)
> **Location:** documentation/GUIDE__Development.md

## 1. Verification (The "Test-First" Mandate)
**Rule:** No code is to be committed unless it has passed local verification.

### Required Checks
1. **Svelte Integrity:** `npx svelte-check`
   - **Zero Tolerance:** If a task introduces even a single svelte-check warning or error, it must not be merged. Resolve all warnings before committing.
2. **Type Safety:** Ensure interfaces in `src/lib/types/ae_types.ts` match backend schemas.
3. **Reactivity Check:** Verify Svelte 5 runes (`$state`, `$derived`) are not creating race conditions with Dexie `liveQuery`.
4. **Build Check:** For major changes, run `npm run build:staging` to ensure no SSR or build-time failures.
5. **Integration Tests:** For changes to badge print, event layouts, or auth/store logic, run the relevant Playwright test file(s):
   ```bash
   npx playwright test tests/event_badge_render.test.ts tests/event_badge_attendee_workflow.test.ts
   ```
   Run the full suite with `npm run test:integration`. The badge tests (`event_badge_*.test.ts`) are the canonical integration test template.

## 2. Commit Policy
- **Atomic Commits:** One component or one logic fix per commit. Do not batch unrelated changes.
- **Safety:** Use `~/tmp/gemini_trash` for file removal; never use `rm` directly on source files.
- **Secrets:** Never commit `.env`, API keys, or passwords.

## 3. Coordination (The Handshake)
You are not working in a vacuum. Coordinate with the Backend Agent via MCP tools.

### Mandatory Messaging Triggers
- **Data Requirements:** When a UI feature requires a new field or endpoint.
- **API Failures:** When a V3 endpoint returns unexpected data or errors.
- **Blocked:** If stuck in a loop or lacking information, use `ae_send_message` to ask the Backend Agent, or flag for Scott.

### Tools
- `ae_send_message` / `ae_inbox` — agent-to-agent messaging
- `ae_task_list` / `ae_task_add` / `ae_task_complete` — shared Kanban board
- `ae_log_work` — log activity to daily journal

## 4. Continuity (Before Starting Work)
1. Review `documentation/TODO__Agents.md` for active tasks.
2. Check `~/agents_sync/README.md` for fleet status and cross-agent tasks.
3. Describe your plan before making code changes across multiple files.

## 5. Key Documentation

| File | Purpose |
| --- | --- |
| `documentation/TODO__Agents.md` | Active task list — read first |
| `documentation/GUIDE__AE_API_V3_for_Frontend.md` | V3 API reference (authoritative) |
| `documentation/GUIDE__SvelteKit2_Svelte5_DexieJS.md` | Dexie + liveQuery patterns |
| `documentation/GEMINI__Svelte_and_Me.md` | Svelte 5 runes patterns |
| `documentation/AE__Architecture.md` | System architecture overview |
| `documentation/AE__Naming_Conventions.md` | Naming rules |
| `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` | Electron/Launcher reference |
| `tests/README.md` | Playwright test guide — shared helpers, hard-won lessons, demo IDs |

## 6. URL Parameters

URL params consumed by the app. Params are read by layouts and applied on mount.

### Global (active on all routes — read by `src/routes/+layout.svelte`)

| Param | Values | Effect |
| --- | --- | --- |
| `iframe` | `true` / `false` | Enables iframe mode — hides the AE system bar for all users by default, suppresses sign-in/passcode UI |
| `show_menu` | `true` | Override: show the AE system bar inside an iframe. Intended for admins/trusted users who need menu access while testing an embed. |
| `hide_menu` | `true` | Explicitly hide the AE system bar outside of iframe mode (e.g. fullscreen kiosk pages). |
| `theme` | theme name | Applies a theme on load, then removes param from URL (no history entry) |
| `theme_mode` | `light` / `dark` | Applies theme mode on load, then removes param from URL |

### IDAA Module (`/idaa/` routes)

| Param | Values | Consumed by | Effect |
| --- | --- | --- | --- |
| `iframe` | `true` | `idaa/+layout.svelte` | Hides IDAA nav chrome |
| `uuid` | Novi UUID | `idaa/(idaa)/+layout.svelte` | Sets Novi UUID → triggers member auth lookup |

### IDAA Video Conferences (`/idaa/video_conferences`)

| Param | Values | Effect |
| --- | --- | --- |
| `uuid` | Novi UUID | Member identity for Jitsi JWT |
| `key` | site key string | Site auth key |
| `room` | room name | Jitsi room name |
| `moderator` | `true` | Grants moderator role + JWT, enables lobby and activity logging |
| `domain` | hostname | Jitsi server (default: `jitsi.dgrzone.com`) |
| `start_muted` | `true` | Start audio muted |
| `start_hidden` | `true` | Start video off |
| `incoming_msg_sound` | `true` | Disable incoming message sound |
| `participant_joined_sound` | `true` | Disable participant joined sound |
| `participant_left_sound` | `true` | Disable participant left sound |
| `reaction_sound` | `true` | Disable reaction sound |
| `raise_hand_sound` | `true` | Disable raise hand sound |

### Events Launcher (`/events/[id]/launcher`)

| Param | Values | Effect |
| --- | --- | --- |
| `session_id` | session ID | Pre-selects a session on load |
| `iframe` | `true` | Iframe mode flag |
| `launcher_menu` | show/hide | Show/hide launcher menu chrome |
| `launcher_header` | show/hide | Show/hide launcher header |
| `launcher_footer` | show/hide | Show/hide launcher footer |

### Events Sign-In (`/events/[id]/sign_in_out`)

| Param | Values | Effect |
| --- | --- | --- |
| `person_id` | person ID | Pre-fill attendee |
| `person_pass` | passphrase | Auto-authenticate attendee |
| `presentation_id` | ID | Pre-select presentation |
| `presenter_id` | ID | Pre-select presenter |
| `session_id` | ID | Pre-select session |

### Badges (`/events/[id]/badges/print_list`)

| Param | Values | Effect |
| --- | --- | --- |
| `printed_status` | filter value | Filter badge list by print status |
| `badge_type_code` | code string | Filter badge list by type |