This directory contains the Svelte 5 frontend application and NUI bridge for gPhone, a custom smartphone resource for FiveM.
$state, $derived, $effect) for component-local state only. Global state is writable/derived stores in src/services/ and src/shell/state/, one file per domain. This split is a policy rather than a leftover: see AGENTS.md §4, which is the authority, and do not introduce .svelte.ts rune-based state modules or convert existing stores.src/app.css, a flat utility layer in src/app-utilities.cssweb/
├── e2e/ # Playwright End-to-End test suites
│ ├── apps/ # Individual app E2E tests (Admin, Bank, Blabber, Bluetooth Share, Calculator, Camera,
│ │ # Contacts, Mail, Media, Messages, Notes, Phone, Settings, Sound, Store)
│ ├── app-residency.spec.ts
│ ├── deep-link.spec.ts # the dev `?app=` deep link
│ ├── deep-links.spec.ts # notification deep-link routing
│ ├── display.spec.ts
│ ├── defects.spec.ts
│ ├── error_boundary.spec.ts
│ ├── home-grid.spec.ts # icon drag/drop, dock, drawer
│ ├── home-search.spec.ts
│ ├── keybinds.spec.ts
│ ├── navigation.spec.ts
│ ├── notifications.spec.ts
│ ├── nui.spec.ts
│ ├── settings-persistence.spec.ts
│ └── theme-modes.spec.ts
├── src/
│ ├── apps/ # One directory per app (admin, bank, blabber, calculator, camera, contacts, hodlr, mail,
│ │ # marketplace, media, messages, notes, phone, settings, snek, store)
│ ├── shell/ # The OS itself: Shell.svelte, PhoneFrame, Launcher, ToastHost, VolumeHud, ErrorBoundary
│ │ └── state/ # State the phone owns (appDrawer, appEvents, audio, bluetooth, bootstrap, catalog, charge,
│ │ # devtools, display, dock, homeGrid, homeGridSettings, iconDrag, keybinds, navigation,
│ │ # notificationSettings, onboarding, registry, remoteAppSecurity, search, searchResults,
│ │ # seedFromImage, shade, signal, theme, time, toast, wallpaper)
│ ├── services/ # Client-side cache of each core service (account, admin, call, camera, contacts,
│ │ # conversations, highscores, mail, marketplace, media, notifications, reports, settings)
│ │ # plus the two factories they are built from: createCrudStore, createPagedStore. An
│ │ # add-on's store — Notes, Blabber, Hodlr — lives beside its app in src/apps/ instead;
│ │ # see AGENTS.md §8/§11.
│ ├── sdk/ # @gphone/sdk — the only thing apps may import
│ │ └── ui/ # UI primitives and icons apps build with
│ ├── nui/ # The bridge: transport adapters, fetchNui, useNuiEvent, browser mocks
│ ├── lib/ # Helpers with no gPhone state and no I/O (debug, dragRatio, dragScroll, errors,
│ │ # filterByQuery, formatters, isBrowser, longPressDrag, m3, markdown, pointerDrag,
│ │ # useScrollDetect)
│ └── main.ts # Mounts shell/Shell.svelte
├── package.json
└── playwright.config.ts
gPhone includes a full suite of automated unit (Vitest) and Playwright End-to-End (E2E) tests.
Run unit test suites covering the core service caches (account, admin, call, camera, contacts, conversations, highscores, mail, marketplace, media, notifications, reports, settings) and the createCrudStore/createPagedStore factories behind them, shell state (appDrawer, appEvents, audio, bluetooth, bootstrap, catalog, charge, display, dock, homeGrid, homeGridSettings, iconDrag, keybinds, navigation, onboarding, registry, remoteAppSecurity, searchResults, shade, signal, theme, time, toast, wallpaper), transport adapters, SDK helpers and boundaries, and the pure helpers in lib/:
pnpm test:unit
The Playwright test suite covers full application flows, NUI events, app error boundaries, interactive notification deep-linking, and form validation across all phone apps:
# Run full headless E2E test suite
pnpm test:e2e
# Visually observe tests running in a single-worker headed Chrome window
pnpm test:e2e:headed
# Serve the HTML Web View Report at http://localhost:9323
pnpm test:e2e:report
gPhone uses a pluggable ITransportAdapter abstraction layer to handle event communication across runtime environments:
MockTransportAdapter): Running pnpm dev launches the web app on http://localhost:5173. Callbacks dynamically resolve from MockRegistry data fixtures.NuiTransportAdapter): Inside FiveM, callbacks issue fetch('https://<resource>/<event>') requests and handle incoming NUI window.message events seamlessly.WebSocketTransportAdapter): Connects gPhone to external WebSockets with automatic reconnection, timeouts, and transparent NUI event broadcasting for remote control and external browser sync.