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):

   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