@flighthq/debug 0.1.0

package/dist/debug.d.ts

@@ -0,0 +1,7 @@
+import type { DebugOptions, DebugSubsystemHooks, DebugSubsystemName } from '@flighthq/types';
+export declare function disableDebug(): void;
+export declare function enableDebug(options?: Readonly<DebugOptions>): void;
+export declare function isDebugEnabled(): boolean;
+export declare function registerDebugSubsystem(name: DebugSubsystemName, hooks: Readonly<DebugSubsystemHooks>): void;
+export declare function unregisterDebugSubsystem(name: DebugSubsystemName): boolean;
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAqB,MAAM,iBAAiB,CAAC;AAOhH,wBAAgB,YAAY,IAAI,IAAI,CAOnC;AASD,wBAAgB,WAAW,CAAC,OAAO,GAAE,QAAQ,CAAC,YAAY,CAAM,GAAG,IAAI,CActE;AAGD,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAOD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAE3G;AAID,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAE1E"}

package/dist/debug.js

@@ -0,0 +1,131 @@
+import { addLogSink, clearLogChannelLevels, createTextLogFormatter, getLogLevel, removeLogSink, setLogChannelLevel, setLogLevel, } from '@flighthq/log';
+import { LogLevel } from '@flighthq/types';
+// The one call that returns Flight to the zero-debug baseline: removes the sink enableDebug
+// installed, restores the log levels it raised, and runs the disable-guards binding of every
+// subsystem it switched on. No-op when debug is not enabled (idempotent, sentinel — not a throw).
+// After this, importing @flighthq/debug costs nothing and no debug output is produced.
+export function disableDebug() {
+    if (!_enabled)
+        return;
+    for (const hooks of _enabledSubsystems)
+        hooks.disableGuards?.();
+    _enabledSubsystems.length = 0;
+    _removeDebugSink();
+    _restoreDebugLevels();
+    _enabled = false;
+}
+// The friendly entry point to Flight's diagnostics. Installs a dev console LogSink (a text-formatted
+// one by default; override with `options.sink`), raises the global log level (default
+// LogLevel.Debug) and the per-channel levels of the selected subsystems plus any explicit
+// `options.channels`, and runs each selected subsystem's registered guard-enabler. `options.subsystems`
+// selects which registered subsystems to switch on; omit it to switch on every registered subsystem.
+// Idempotent: a second call while already enabled is a no-op (disableDebug first to re-enable with
+// different options).
+export function enableDebug(options = {}) {
+    if (_enabled)
+        return;
+    const level = options.level ?? LogLevel.Debug;
+    const subsystems = _resolveDebugSubsystems(options.subsystems);
+    const channels = _collectDebugChannels(subsystems, options.channels);
+    _savedGlobalLevel = getLogLevel();
+    _applyDebugLevels(level, channels);
+    _installDebugSink(options.sink ?? _createDefaultDebugSink());
+    for (const hooks of subsystems) {
+        hooks.enableGuards?.();
+        _enabledSubsystems.push(hooks);
+    }
+    _enabled = true;
+}
+// Whether enableDebug is currently in effect (a sink is installed and levels/guards are raised).
+export function isDebugEnabled() {
+    return _enabled;
+}
+// Registers a diagnostic subsystem's wiring — the log channels whose verbosity enableDebug should
+// raise and the guard-enabler/-disabler bindings it should run for `name`. A package's thin debug
+// adapter (or the app) calls this so enableDebug(['render']) can drive the subsystem without
+// @flighthq/debug importing it. Last-write-wins; vendor-prefix custom subsystem names ('acme.Foo')
+// to avoid colliding with built-ins.
+export function registerDebugSubsystem(name, hooks) {
+    _subsystems.set(name, hooks);
+}
+// Removes a subsystem registration. Returns false when nothing was registered under `name`
+// (sentinel, not a throw). Does not affect an already-active debug session.
+export function unregisterDebugSubsystem(name) {
+    return _subsystems.delete(name);
+}
+const _subsystems = new Map();
+const _enabledSubsystems = [];
+let _enabled = false;
+let _installedSink = null;
+let _savedGlobalLevel = LogLevel.Verbose;
+// Raises the global level and every selected channel's level to `level` for the session.
+function _applyDebugLevels(level, channels) {
+    setLogLevel(level);
+    for (const channel of channels)
+        setLogChannelLevel(channel, level);
+}
+// Gathers the channels to raise: every selected subsystem's channels plus any explicit extras.
+function _collectDebugChannels(subsystems, extra) {
+    const channels = [];
+    for (const hooks of subsystems) {
+        if (hooks.channels !== undefined)
+            channels.push(...hooks.channels);
+    }
+    if (extra !== undefined)
+        channels.push(...extra);
+    return channels;
+}
+// The default dev sink: formats each entry as a human-readable line and writes it to the matching
+// console method. Dev-only — this is the one place @flighthq/debug touches the console, and the
+// package is never in a shipping bundle.
+function _createDefaultDebugSink() {
+    const formatter = createTextLogFormatter({ levelPrefix: true });
+    return (entry) => {
+        if (typeof console === 'undefined')
+            return;
+        const method = _consoleMethods[entry.level] ?? 'log';
+        // eslint-disable-next-line no-console -- the dev debug sink; writing to the console is its job.
+        console[method](formatter(entry));
+    };
+}
+// Installs the debug sink and records it so disableDebug can remove exactly this one.
+function _installDebugSink(sink) {
+    _installedSink = sink;
+    addLogSink(sink);
+}
+// Removes the installed debug sink, if any.
+function _removeDebugSink() {
+    if (_installedSink === null)
+        return;
+    removeLogSink(_installedSink);
+    _installedSink = null;
+}
+// Resolves the subsystem hooks to drive: the named ones when `names` is given (unregistered names
+// are skipped), otherwise every registered subsystem.
+function _resolveDebugSubsystems(names) {
+    if (names === undefined)
+        return [..._subsystems.values()];
+    const resolved = [];
+    for (const name of names) {
+        const hooks = _subsystems.get(name);
+        if (hooks !== undefined)
+            resolved.push(hooks);
+    }
+    return resolved;
+}
+// Restores the global level enableDebug saved and clears the per-channel overrides it raised. Debug
+// owns per-channel verbosity for the duration of a session, so disabling wipes those overrides back
+// to inheriting the global level.
+function _restoreDebugLevels() {
+    setLogLevel(_savedGlobalLevel);
+    clearLogChannelLevels();
+}
+const _consoleMethods = {
+    [LogLevel.None]: 'log',
+    [LogLevel.Error]: 'error',
+    [LogLevel.Warn]: 'warn',
+    [LogLevel.Info]: 'info',
+    [LogLevel.Debug]: 'debug',
+    [LogLevel.Verbose]: 'log',
+};
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"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"}

package/dist/debugTiming.d.ts

@@ -0,0 +1,6 @@
+import type { LogTimer } from '@flighthq/types';
+export declare function beginDebugSpan(name: string, channel?: string | null): LogTimer | null;
+export declare function endDebugSpan(timer: Readonly<LogTimer> | null): number;
+export declare function markDebugFrame(label?: string, channel?: string | null): void;
+export declare function measureDebugSpan<T>(name: string, fn: () => T, channel?: string | null): T;
+//# sourceMappingURL=debugTiming.d.ts.map

package/dist/debugTiming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugTiming.d.ts","sourceRoot":"","sources":["../src/debugTiming.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAShD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,GAAG,IAAW,GAAG,QAAQ,GAAG,IAAI,CAE3F;AAKD,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,GAAG,MAAM,CAErE;AAMD,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,GAAG,IAAW,GAAG,IAAI,CAGlF;AAMD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,GAAE,MAAM,GAAG,IAAW,GAAG,CAAC,CAO/F"}

package/dist/debugTiming.js

@@ -0,0 +1,42 @@
+import { endLogTimer, logDebug, startLogTimer } from '@flighthq/log';
+import { isDebugEnabled } from './debug';
+// Opens a named timing span, but only while a debug session is active: returns a LogTimer to hand to
+// endDebugSpan, or null when debug is disabled (production, or before enableDebug). Gating here is the
+// point — with debug off, opening a span is one boolean check and allocates nothing, so span
+// instrumentation left in shipping code costs effectively nothing. Pair every non-null result with
+// endDebugSpan (measureDebugSpan brackets both for a single synchronous call).
+export function beginDebugSpan(name, channel = null) {
+    return isDebugEnabled() ? startLogTimer(name, channel) : null;
+}
+// Closes a span opened by beginDebugSpan, emitting its elapsed-time Debug entry through the active
+// debug sink and returning the elapsed milliseconds. A null timer — debug was disabled when the span
+// opened — is a no-op returning -1, the sentinel for "not measured".
+export function endDebugSpan(timer) {
+    return timer === null ? -1 : endLogTimer(timer);
+}
+// Emits a frame-boundary marker while a debug session is active, so the per-frame span entries between
+// two markers can be read against the frame they fell in. `label` names the frame; omit it to tag the
+// marker with a process-monotonic frame counter. No-op (and no counter advance) when debug is disabled,
+// so a per-frame call in the app loop costs a single boolean check in production.
+export function markDebugFrame(label, channel = null) {
+    if (!isDebugEnabled())
+        return;
+    logDebug({ frame: label ?? ++_debugFrameNumber }, channel);
+}
+// Brackets a synchronous function as a timing span: times `fn` while a debug session is active,
+// emitting one elapsed-time entry, and returns `fn`'s result. When debug is disabled `fn` still runs —
+// only the timing is skipped — so wrapping a call never changes behavior, only observability. The span
+// is closed even if `fn` throws.
+export function measureDebugSpan(name, fn, channel = null) {
+    const timer = beginDebugSpan(name, channel);
+    try {
+        return fn();
+    }
+    finally {
+        endDebugSpan(timer);
+    }
+}
+// Monotonic id handed to unlabeled frame markers. Not reset between sessions — a marker's job is to
+// correlate span entries with a frame boundary, for which a unique ascending id suffices.
+let _debugFrameNumber = 0;
+//# sourceMappingURL=debugTiming.js.map

package/dist/debugTiming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugTiming.js","sourceRoot":"","sources":["../src/debugTiming.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGrE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,qGAAqG;AACrG,uGAAuG;AACvG,6FAA6F;AAC7F,mGAAmG;AACnG,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,UAAyB,IAAI;IACxE,OAAO,cAAc,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAChE,CAAC;AAED,mGAAmG;AACnG,qGAAqG;AACrG,qEAAqE;AACrE,MAAM,UAAU,YAAY,CAAC,KAAgC;IAC3D,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,uGAAuG;AACvG,sGAAsG;AACtG,wGAAwG;AACxG,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,UAAyB,IAAI;IAC1E,IAAI,CAAC,cAAc,EAAE;QAAE,OAAO;IAC9B,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE,iBAAiB,EAAE,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED,gGAAgG;AAChG,uGAAuG;AACvG,uGAAuG;AACvG,iCAAiC;AACjC,MAAM,UAAU,gBAAgB,CAAI,IAAY,EAAE,EAAW,EAAE,UAAyB,IAAI;IAC1F,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,oGAAoG;AACpG,0FAA0F;AAC1F,IAAI,iBAAiB,GAAG,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './debug';
+export * from './debugTiming';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './debug';
+export * from './debugTiming';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/debug",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/log": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Opt-in diagnostics umbrella over @flighthq/log — an open subsystem registry driving per-channel log levels, guard-enablers, and a dev console sink",
+  "sideEffects": false
+}

package/src/debug.test.ts

@@ -0,0 +1,197 @@
+import {
+  clearLogChannelLevels,
+  clearLogSinks,
+  createMemoryLogSink,
+  getLogChannelLevel,
+  getLogLevel,
+  getMemoryLogSinkEntries,
+  log,
+  setLogLevel,
+} from '@flighthq/log';
+import type { MemoryLogSink } from '@flighthq/log';
+import { LogLevel } from '@flighthq/types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { disableDebug, enableDebug, isDebugEnabled, registerDebugSubsystem, unregisterDebugSubsystem } from './debug';
+
+// Subsystem names touched by the tests, unregistered between each so the module-global registry
+// never leaks state across cases.
+const testSubsystemNames = ['render', 'input', 'audio', 'acme.custom'];
+
+function readMemory(sink: MemoryLogSink): readonly unknown[] {
+  return getMemoryLogSinkEntries(sink);
+}
+
+beforeEach(() => {
+  if (isDebugEnabled()) disableDebug();
+  for (const name of testSubsystemNames) unregisterDebugSubsystem(name);
+  clearLogSinks();
+  clearLogChannelLevels();
+  setLogLevel(LogLevel.Verbose);
+});
+
+afterEach(() => {
+  if (isDebugEnabled()) disableDebug();
+  for (const name of testSubsystemNames) unregisterDebugSubsystem(name);
+  clearLogSinks();
+  clearLogChannelLevels();
+  setLogLevel(LogLevel.Verbose);
+});
+
+describe('disableDebug', () => {
+  it('removes the installed sink so a later log does not reach it', () => {
+    const memory = createMemoryLogSink(16);
+    registerDebugSubsystem('render', { channels: ['render'] });
+    enableDebug({ subsystems: ['render'], sink: memory.sink });
+
+    log(LogLevel.Debug, 'before', 'render');
+    expect(readMemory(memory)).toHaveLength(1);
+
+    disableDebug();
+    log(LogLevel.Debug, 'after', 'render');
+    expect(readMemory(memory)).toHaveLength(1);
+  });
+
+  it('runs each enabled subsystem disableGuards binding', () => {
+    const disableGuards = vi.fn();
+    registerDebugSubsystem('render', { disableGuards });
+    enableDebug({ subsystems: ['render'], sink: createMemoryLogSink(1).sink });
+
+    expect(disableGuards).not.toHaveBeenCalled();
+    disableDebug();
+    expect(disableGuards).toHaveBeenCalledTimes(1);
+  });
+
+  it('restores the global level and clears the channel overrides it raised', () => {
+    setLogLevel(LogLevel.Warn);
+    registerDebugSubsystem('render', { channels: ['render'] });
+    enableDebug({ subsystems: ['render'], level: LogLevel.Verbose, sink: createMemoryLogSink(1).sink });
+
+    disableDebug();
+    expect(getLogLevel()).toBe(LogLevel.Warn);
+    expect(getLogChannelLevel('render')).toBeNull();
+  });
+
+  it('is a no-op when debug is not enabled', () => {
+    expect(isDebugEnabled()).toBe(false);
+    expect(() => disableDebug()).not.toThrow();
+    expect(isDebugEnabled()).toBe(false);
+  });
+});
+
+describe('enableDebug', () => {
+  it('runs a selected subsystem enableGuards and raises its channel levels', () => {
+    const enableGuards = vi.fn();
+    registerDebugSubsystem('render', { channels: ['render', 'render.batch'], enableGuards });
+
+    enableDebug({ subsystems: ['render'], sink: createMemoryLogSink(1).sink });
+
+    expect(enableGuards).toHaveBeenCalledTimes(1);
+    expect(getLogChannelLevel('render')).toBe(LogLevel.Debug);
+    expect(getLogChannelLevel('render.batch')).toBe(LogLevel.Debug);
+    expect(isDebugEnabled()).toBe(true);
+  });
+
+  it('routes a log on a raised channel to the installed sink', () => {
+    const memory = createMemoryLogSink(16);
+    registerDebugSubsystem('render', { channels: ['render'] });
+    enableDebug({ subsystems: ['render'], sink: memory.sink });
+
+    log(LogLevel.Debug, { msg: 'draw' }, 'render');
+    expect(readMemory(memory)).toHaveLength(1);
+  });
+
+  it('honors an explicit level and extra channels', () => {
+    registerDebugSubsystem('render', { channels: ['render'] });
+    enableDebug({
+      subsystems: ['render'],
+      level: LogLevel.Verbose,
+      channels: ['app'],
+      sink: createMemoryLogSink(1).sink,
+    });
+
+    expect(getLogLevel()).toBe(LogLevel.Verbose);
+    expect(getLogChannelLevel('render')).toBe(LogLevel.Verbose);
+    expect(getLogChannelLevel('app')).toBe(LogLevel.Verbose);
+  });
+
+  it('enables every registered subsystem when none are named', () => {
+    const renderGuards = vi.fn();
+    const inputGuards = vi.fn();
+    registerDebugSubsystem('render', { enableGuards: renderGuards });
+    registerDebugSubsystem('input', { enableGuards: inputGuards });
+
+    enableDebug({ sink: createMemoryLogSink(1).sink });
+
+    expect(renderGuards).toHaveBeenCalledTimes(1);
+    expect(inputGuards).toHaveBeenCalledTimes(1);
+  });
+
+  it('skips an unregistered subsystem name without throwing', () => {
+    const memory = createMemoryLogSink(1);
+    expect(() => enableDebug({ subsystems: ['audio'], sink: memory.sink })).not.toThrow();
+    expect(isDebugEnabled()).toBe(true);
+  });
+
+  it('is idempotent — a second enable while active does not re-run guards or re-install', () => {
+    const enableGuards = vi.fn();
+    const memory = createMemoryLogSink(16);
+    registerDebugSubsystem('render', { channels: ['render'], enableGuards });
+
+    enableDebug({ subsystems: ['render'], sink: memory.sink });
+    enableDebug({ subsystems: ['render'], sink: memory.sink });
+
+    expect(enableGuards).toHaveBeenCalledTimes(1);
+    log(LogLevel.Debug, 'once', 'render');
+    expect(readMemory(memory)).toHaveLength(1);
+  });
+});
+
+describe('isDebugEnabled', () => {
+  it('reports the enable/disable lifecycle', () => {
+    expect(isDebugEnabled()).toBe(false);
+    enableDebug({ sink: createMemoryLogSink(1).sink });
+    expect(isDebugEnabled()).toBe(true);
+    disableDebug();
+    expect(isDebugEnabled()).toBe(false);
+  });
+});
+
+describe('registerDebugSubsystem', () => {
+  it('drives a newly registered subsystem through enableDebug', () => {
+    const enableGuards = vi.fn();
+    registerDebugSubsystem('acme.custom', { channels: ['acme.custom'], enableGuards });
+
+    enableDebug({ subsystems: ['acme.custom'], sink: createMemoryLogSink(1).sink });
+
+    expect(enableGuards).toHaveBeenCalledTimes(1);
+    expect(getLogChannelLevel('acme.custom')).toBe(LogLevel.Debug);
+  });
+
+  it('is last-write-wins for a repeated name', () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    registerDebugSubsystem('render', { enableGuards: first });
+    registerDebugSubsystem('render', { enableGuards: second });
+
+    enableDebug({ subsystems: ['render'], sink: createMemoryLogSink(1).sink });
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('unregisterDebugSubsystem', () => {
+  it('returns true and stops the subsystem from being driven', () => {
+    const enableGuards = vi.fn();
+    registerDebugSubsystem('render', { enableGuards });
+
+    expect(unregisterDebugSubsystem('render')).toBe(true);
+    enableDebug({ subsystems: ['render'], sink: createMemoryLogSink(1).sink });
+    expect(enableGuards).not.toHaveBeenCalled();
+  });
+
+  it('returns false for a name that was never registered', () => {
+    expect(unregisterDebugSubsystem('audio')).toBe(false);
+  });
+});

package/src/debugTiming.test.ts

@@ -0,0 +1,125 @@
+import {
+  addLogSink,
+  clearLogChannelLevels,
+  clearLogSinks,
+  createMemoryLogSink,
+  getMemoryLogSinkEntries,
+  setLogLevel,
+} from '@flighthq/log';
+import type { MemoryLogSink } from '@flighthq/log';
+import { LogLevel } from '@flighthq/types';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { disableDebug, enableDebug, isDebugEnabled } from './debug';
+import { beginDebugSpan, endDebugSpan, markDebugFrame, measureDebugSpan } from './debugTiming';
+
+function entryData(sink: MemoryLogSink): Readonly<Record<string, unknown>>[] {
+  return getMemoryLogSinkEntries(sink).map((entry) => (entry as { data: Record<string, unknown> }).data);
+}
+
+beforeEach(() => {
+  if (isDebugEnabled()) disableDebug();
+  clearLogSinks();
+  clearLogChannelLevels();
+  setLogLevel(LogLevel.Verbose);
+});
+
+afterEach(() => {
+  if (isDebugEnabled()) disableDebug();
+  clearLogSinks();
+  clearLogChannelLevels();
+  setLogLevel(LogLevel.Verbose);
+});
+
+describe('beginDebugSpan', () => {
+  it('returns null when debug is disabled', () => {
+    expect(beginDebugSpan('draw')).toBeNull();
+  });
+
+  it('returns a running timer when debug is enabled', () => {
+    enableDebug({ sink: createMemoryLogSink(1).sink });
+    const timer = beginDebugSpan('draw');
+    expect(timer).not.toBeNull();
+    expect(timer!.label).toBe('draw');
+  });
+});
+
+describe('endDebugSpan', () => {
+  it('is a no-op returning -1 for a null timer', () => {
+    expect(endDebugSpan(null)).toBe(-1);
+  });
+
+  it('emits an elapsed-time entry and returns the elapsed milliseconds', () => {
+    const memory = createMemoryLogSink(16);
+    enableDebug({ sink: memory.sink });
+    const elapsed = endDebugSpan(beginDebugSpan('draw'));
+    expect(elapsed).toBeGreaterThanOrEqual(0);
+    const data = entryData(memory);
+    expect(data).toHaveLength(1);
+    expect(data[0].label).toBe('draw');
+    expect(typeof data[0].elapsedMs).toBe('number');
+  });
+});
+
+describe('markDebugFrame', () => {
+  it('is a no-op when debug is disabled', () => {
+    const memory = createMemoryLogSink(4);
+    addLogSink(memory.sink);
+    markDebugFrame();
+    expect(getMemoryLogSinkEntries(memory)).toHaveLength(0);
+  });
+
+  it('emits a labeled frame marker when debug is enabled', () => {
+    const memory = createMemoryLogSink(16);
+    enableDebug({ sink: memory.sink });
+    markDebugFrame('level-load');
+    expect(entryData(memory)[0].frame).toBe('level-load');
+  });
+
+  it('tags an unlabeled marker with an ascending counter', () => {
+    const memory = createMemoryLogSink(16);
+    enableDebug({ sink: memory.sink });
+    markDebugFrame();
+    markDebugFrame();
+    const [a, b] = entryData(memory);
+    expect(typeof a.frame).toBe('number');
+    expect(b.frame as number).toBeGreaterThan(a.frame as number);
+  });
+});
+
+describe('measureDebugSpan', () => {
+  it('returns the wrapped function result', () => {
+    expect(measureDebugSpan('compute', () => 42)).toBe(42);
+  });
+
+  it('runs the function but emits nothing when debug is disabled', () => {
+    const memory = createMemoryLogSink(4);
+    addLogSink(memory.sink);
+    let ran = false;
+    measureDebugSpan('compute', () => {
+      ran = true;
+    });
+    expect(ran).toBe(true);
+    expect(getMemoryLogSinkEntries(memory)).toHaveLength(0);
+  });
+
+  it('emits one timing entry named for the span when debug is enabled', () => {
+    const memory = createMemoryLogSink(16);
+    enableDebug({ sink: memory.sink });
+    measureDebugSpan('compute', () => 1);
+    const data = entryData(memory);
+    expect(data).toHaveLength(1);
+    expect(data[0].label).toBe('compute');
+  });
+
+  it('closes the span even when the function throws', () => {
+    const memory = createMemoryLogSink(16);
+    enableDebug({ sink: memory.sink });
+    expect(() =>
+      measureDebugSpan('boom', () => {
+        throw new Error('nope');
+      }),
+    ).toThrow('nope');
+    expect(entryData(memory)).toHaveLength(1);
+  });
+});