# Logging and Dev-Mode Guidance

This document explains how bitvid routes browser logs, how inline scripts can
re-use the shared logger, and what operators must do with the dev-mode flag when
promoting builds.

## Picking the right channel

bitvid ships a frozen logger at `js/utils/logger.js` with two channels:

- `logger.dev`: Emits only when `IS_DEV_MODE` is truthy. Use this channel for
  verbose traces, performance probes, and feature flag experimentation that
  should disappear from production consoles. The `logger.dev.debug` helper is
  available for especially noisy traces that you want to keep isolated to local
  development sessions.
- `logger.user`: Always available and automatically prefixes output with
  `[bitvid]`. Use this channel for operator-facing warnings and errors that help
  diagnose issues in production.

When adding new messages, classify them by the audience:

| Scenario | Recommended channel | Notes |
| --- | --- | --- |
| Debugging a new feature locally | `logger.dev.debug`/`logger.dev.info` | Remove or downgrade before launching if they no longer serve a purpose. |
| Non-fatal recoverable issues users should investigate | `logger.user.warn` | Provide actionable context so operators know what failed. |
| Fatal errors that block playback or payments | `logger.user.error` | Escalate with a clear message and include relevant IDs or URLs. |
| Metrics or noisy traces that only help during QA | `logger.dev.*` | Wrap expensive logging in conditional checks when possible. |

Avoid direct `console.*` calls—routing everything through the logger keeps the
production console clean and guarantees dev-mode gates behave consistently.

## Using the logger from inline scripts

The logger is exposed as a frozen global so inline scripts can share the same
API without additional bundling:

```js
const { dev, user } = window.bitvidLogger;

dev.log("rendering upload modal preview");
user.warn("Playback manifest missing expected resolution tag");
```

If you need to guard logic by environment, rely on the companion global set in
`js/config.js`:

```js
if (window.__BITVID_DEV_MODE__) {
  window.bitvidLogger.dev.info("Hydrating admin widgets in dev mode");
}
```

The globals are populated as soon as `js/config.js` loads. Check for their
existence before using them in third-party contexts that may execute earlier.

## Adjusting the dev-mode flag for deployments

The source of truth lives in `config/instance-config.js`:

- Set `IS_DEV_MODE = true` while developing locally so the dev logger and other
  diagnostics are available.
- Flip `IS_DEV_MODE = false` before shipping a production build. This change
  propagates to `isDevMode` (the module export), `window.__BITVID_DEV_MODE__`,
  and `logger.dev`, silencing development-only messages.

Always commit the flag change alongside deployment-ready configuration tweaks.
Forgetting to update the flag leaves verbose traces in user consoles and can
expose experimental behavior intended only for QA environments.