How to: turn on diagnostic logging

You want visibility into what the engine or an adapter is doing at a commit/event/native-bridge seam, without adding your own console.log calls that you’ll later have to remember to remove.

Turn it on

DEBUG=1 pnpm ios   # or: DEBUG=1 pnpx react-native start --reset-cache

Node reads DEBUG=1 natively (headless smokes); on-device, each example’s index.js mirrors it onto the global once at start — globalThis.__SYMBIOTE_DEBUG__ = process.env.DEBUG === '1' — so changing it needs a fresh Metro start (--reset-cache), not a rebuild. No env access at runtime? Set the escape hatch instead:

globalThis.__SYMBIOTE_DEBUG__ = true;

Reading/writing logs

Every diagnostic log goes through dlog, never a bare console.log:

import { dlog } from '@symbiote-native/engine';

dlog(`dispatchViewCommand "${commandName}" skipped: node not committed`);

dlog is a no-op (one property read, nothing emitted) unless isDebug() is true, so it costs nothing left in place — which is why existing dlog calls are never deleted, only added to. When you’re debugging a commit path, an event, or a native bring-up step and find a useful seam, leave a dlog there permanently rather than a temporary console.log.

Why this exists

dlog/isDebug live in core/engine/src/debug.ts and are exported from @symbiote-native/engine so every adapter shares one gating mechanism instead of each inventing its own flag. Grep for dlog( across core/ and adapters/ to see the seams already instrumented — commit timing, native command dispatch, ViewConfig resolution — before adding your own.