debugModule

import { debugModule } from '@atheory-ai/kitsune-dev'

shell.modules = [...modules, debugModule()]

What it does

• Subscribes to runtime.onDiagnostic and logs every diagnostic.
• Subscribes to '*' events and logs every event.

This makes the runtime loop visible while you build. You’ll see when modules install, when events fire, when commands dispatch and handle, when handlers fail or aren’t registered.

Options

type DebugModuleOptions = {
  log?: (message: string, detail?: Record<string, unknown>) => void
}

log — replace the default console output. Useful when:

• Routing logs through a structured logger.
• Filtering noisy event types.
• Capturing logs into a buffer for later inspection.

Default is (message, detail) => console.debug(message, detail).

Sample output

After installing the module on a Quill-style app, opening a page produces:

[kit:diagnostic] command.handler_registered { commandType: 'notification.show' }
[kit:diagnostic] command.handler_registered { commandType: 'notification.dismiss' }
[kit:diagnostic] command.handler_registered { commandType: 'notification.clear' }
[kit:diagnostic] module.installed { moduleName: 'kit-notifications' }
[kit:diagnostic] command.handler_registered { commandType: 'dialog.open' }
[kit:diagnostic] command.handler_registered { commandType: 'dialog.close' }
[kit:diagnostic] module.installed { moduleName: 'kit-dialog' }
[kit:diagnostic] module.installed { moduleName: 'debug' }
[kit:diagnostic] runtime.started

Then on each click:

[kit:event] note.opened { id: '...' }
[kit:diagnostic] event.emitted { eventType: 'note.opened', event: {...} }

Production posture

Don’t install in production. Either:

• Conditionally install based on import.meta.env.DEV (Vite) or process.env.NODE_ENV.
• Tree-shake by importing the module file only inside a dev-only entry.

const modules = [
  notificationModule(),
  dialogModule(),
  ...(import.meta.env.DEV ? [debugModule()] : []),
]

A custom logger

import { debugModule } from '@atheory-ai/kitsune-dev'

const buffer: string[] = []

debugModule({
  log: (msg, detail) => {
    buffer.push(`${msg} ${JSON.stringify(detail)}`)
    if (buffer.length > 1000) buffer.shift()
  },
})

formatDiagnostic

Also exported:

import { formatDiagnostic } from '@atheory-ai/kitsune-dev'

formatDiagnostic({ type: 'event.emitted', timestamp: 0 })
// '[kit:diagnostic] event.emitted'

The default log formatter. Useful if you want the same format with a different sink.

See also

• Diagnostics catalog
• Diagnostics (concept)

In-app devtools

@atheory-ai/kitsune-dev also exports a lightweight timeline surface for local app builds:

import {
  bindKitDevtoolsElement,
  defineKitDevtoolsElement,
  devtoolsModule,
} from '@atheory-ai/kitsune-dev'

defineKitDevtoolsElement()

const runtime = shell.runtime
await runtime.install(devtoolsModule())
bindKitDevtoolsElement('kit-devtools', runtime)

<kit-devtools></kit-devtools>

The devtoolsModule() records diagnostics and runtime events into a bounded timeline, exposes DevtoolsToken, and handles:

• devtools.entries
• devtools.clear
• devtools.introspect

The element renders timeline count, module count, provider count, recent events, and recent diagnostics. It is meant for in-app development visibility before any browser-extension packaging.