simulation and debugging

introduction

the native simulation environment provides rapid iteration during development. unlike production builds, simulators connect directly to your local development server and support hot reloading.

simulation mode

simulation mode automatically injects your development server url into the native runtime. the framework starts your server if it is not already running.

ios simulation

1dstrn simulate --ios

the framework searches for available ios simulators on your system. it prefers already booted devices and falls back to the latest available iphone model.

requirements:

• xcode installed with command line tools
• at least one ios simulator configured in xcode

the simulator displays console output from both the swift runtime and your javascript application. press r to reload the webview. press q to terminate.

android simulation

1dstrn simulate --android

the framework checks for connected physical devices first. if none are found, it searches for configured android virtual devices and launches the first one automatically.

requirements:

• android sdk installed
• platform tools available (adb)
• at least one avd configured in android studio

the emulator may take up to a minute to boot. the framework waits for the device to become ready before installing and launching your application.

android maps localhost to 10.0.2.2 automatically. your development server must be accessible at this address from within the emulator.

desktop simulation

1dstrn simulate --desktop

the desktop runtime opens a native window powered by the tauri webview. this behaves identically to a browser but with access to native system apis through the bridge.

requirements:

• rust toolchain installed
• tauri cli available

desktop simulation is the fastest iteration cycle. the window can be resized and responds to standard keyboard shortcuts. the console displays output from both the rust runtime and javascript environment.

simulation vs production

simulation and production modes differ in several critical ways:

the most important distinction is url resolution. simulators receive the development server url via DSTRN_DEV_URL environment variable. production builds use the url configured in config/native.js or fall back to your app config.

if your production builds show a white screen, verify that the configured url is reachable and returns valid html. see common issues for troubleshooting steps.

debugging

the framework includes an integrated debug bar that provides realtime performance monitoring, network inspection, console logs, and dom analysis. the debug bar automatically activates in local development and can be toggled via the bottom bar interface.

key features:

• server timing and query profiling
• memory leak detection and cpu monitoring
• network request inspection with full headers and payloads
• console log aggregation with stack traces
• live dom inspector with visualization
• socket event monitoring
• component state tracking

the debug bar integrates with native webviews and provides the same experience across ios, android, and desktop platforms.

ios debugging

ios webview debugging works through safari developer tools:

1. enable develop menu in safari preferences
2. launch your app in the simulator
3. open safari develop menu
4. select simulator > your app > wkwebview

you now have full access to the javascript console, network inspector, and dom viewer. breakpoints and step debugging work as expected.

runtime logs from swift appear in the xcode console or terminal output where you launched the simulation command.

android debugging

android webview debugging uses chrome devtools:

1. launch your app in the emulator or on a physical device
2. open chrome and navigate to chrome://inspect
3. find your app in the remote targets list
4. click inspect to open devtools

webview debugging is enabled automatically in debug builds. the framework injects network adapters that map localhost to the emulator's host ip.

use adb logcat to view native runtime logs:

1adb logcat -s dstrn:V

desktop debugging

desktop applications support devtools through the tauri webview. right click anywhere in the window and select inspect element.

console output appears both in the devtools console and the terminal where you launched the simulation. rust logs use the [dstrn] prefix.

common issues

white screen on launch

symptom: the app launches but displays only a white screen with no content.

in simulation mode:

verify your development server is running and accessible:

1curl http://localhost:825

for android, test the emulator mapping:

1adb shell curl http://10.0.2.2:825

if the curl succeeds but the app shows white, check the browser console for javascript errors.

in production builds:

the most common cause is an unreachable or misconfigured url. production builds do not receive the development url automatically.

check your native configuration:

1// config/native.js
2export default {
3  index: 'https://your-actual-domain.com',
4};

if index is null, verify that Config('app.url') and Config('app.port') point to your production server.

if your server requires network connectivity, consider implementing a static fallback so the app can function offline.

network requests failing

cors errors in ios:

ios requires explicit cors headers for cross origin requests. if your api runs on a different domain than your frontend, ensure your server includes proper cors headers.

refused to connect in android:

android blocks cleartext http by default. if your development or production server uses http instead of https, you must enable cleartext traffic in the manifest.

the framework allows cleartext by default in debug builds. production builds enforce https unless explicitly configured otherwise.

localhost not reachable:

on android, localhost refers to the emulator itself, not your development machine. all localhost references are automatically rewritten to 10.0.2.2 by the network polyfill.

on ios and desktop, localhost works as expected.

static assets not loading

if your css or javascript files return 404 errors, verify the paths match your server configuration.

native webviews resolve relative urls against the page url. if your page loads from https://api.example.com/ but your assets are served from https://cdn.example.com/, use absolute urls in your html.

the static fallback site resolves assets against the bundle root. paths like /css/dstrn.css work correctly in both remote and local mode.

javascript errors

check the javascript console for error messages and stack traces. the framework's error handler displays detailed debugging information in local mode.

common causes:

• undefined variables due to missing polyfills
• cors issues blocking network requests
• timing issues where dom elements are accessed before ready

the native bridge is available at window.dstrnBridge on all platforms. if your code depends on native features, verify the bridge exists before calling methods.

log output

native runtimes emit standardized log messages:

1[dstrn] loading remote: https://api.example.com
2[dstrn] webview ready
3[dstrn] load failed: network error
4[dstrn] attempting fallback

simulation mode is more verbose than production. in production, only critical errors and state changes are logged.

you can filter native logs by platform:

1# ios
2xcrun simctl spawn booted log stream --predicate 'processImagePath contains "dframework"'
3 
4# android
5adb logcat -s dstrn:V
6 
7# desktop
8# logs appear in terminal where simulate was run