npm package: @sdux-vault/devtools
Description: > Observability, debugging, and runtime inspection for the SDuX platform.
Latest version: 0.0.7

# @sdux-vault/devtools

> Observability, debugging, and runtime inspection for the SDuX platform.

`@sdux-vault/devtools-tooling` provides the developer-facing tooling layer for SDuX.  
It enables deep insight into pipeline execution, controller decisions, and state transitions in real time.

---

## TL;DR

For full documentation, guides, and API references:  
https://www.sdux-vault.com

---

## Overview

SDuX is built as a layered system:

```plaintext
shared → engine → core → core-extensions → apps
           └─────────---------───────────→ devtools
```

- **apps** → end-user applications
- **core** → behavior runtime + execution layer
- **core-extensions** → framework integrations
- **devtools** → debugging and inspection (this package)
- **engine** → runtime engine and orchestration
- **shared** → contracts, types, utilities

---

## What This Package Provides

- Runtime instrumentation layer
- Pipeline inspection tools
- Controller decision tracing
- State transition visualization hooks
- DevTools integration bridge
- Debug-safe monitoring utilities

---

## Key Characteristics

- ✅ Non-invasive instrumentation
- ✅ Dev-only execution (no production overhead)
- ✅ Framework-agnostic
- ✅ Real-time pipeline visibility
- ✅ Deterministic and traceable execution insights

---

## Installation

```bash
npm install @sdux-vault/devtools-tooling
```

---

## Usage

### Basic Import

```ts
import '@sdux-vault/devtools-tooling';
```

This enables:

- runtime instrumentation
- DevTools communication
- feature cell registration tracking

---

## Example: Dev Mode Integration

```ts
import { DevMode } from '@sdux-vault/shared';

if (DevMode.active) {
  // DevTools will automatically attach
}
```

---

## How It Works

This package integrates with the SDuX runtime through:

- VaultMonitor hooks
- DecisionEngine events
- Behavior + controller lifecycle signals

It observes:

- pipeline execution
- controller outcomes
- state mutations
- error propagation

All without mutating runtime behavior.

---

## Instrumentation Model

### Passive Observation

Devtools tooling:

- does not alter execution
- does not mutate state
- does not introduce side effects in production

---

## Event Sources

Instrumentation is driven by:

- FeatureCell lifecycle events
- Behavior execution stages
- Controller decision flow
- Orchestrator pipeline phases

---

## Traceability

Each pipeline run is tracked via:

```ts
traceId: string;
```

This enables:

- deterministic debugging
- replayable execution flows
- cross-layer correlation

---

## DevTools Integration

This package acts as the bridge between runtime and DevTools UI.

It enables:

- feature cell inspection
- timeline visualization
- state diffing
- controller decision tracing

---

## Environment Behavior

Instrumentation is:

- ✅ Enabled in DevMode
- 🚫 No-op in production
- ✅ Safe for SSR and browser environments

---

## Side Effects

This package performs controlled, dev-only side effects:

```ts
import '@sdux-vault/devtools-tooling';
```

Triggers:

- DevTools registration
- runtime instrumentation wiring

Behavior:

- no-op in production
- idempotent
- safe across all runtimes

---

## Development

### Build

```bash
npm run build:devtools-tooling
```

Output:

```
dist/devtools/tooling
```

---

## Test

```bash
npm run test:devtools-tooling
```

---

## Verify

```bash
npm run verify
```

Includes:

- linting
- formatting
- type checking
- tests

---

## Publishing

See `RELEASE.md` for full publishing instructions.

---

## Ecosystem

- `@sdux-vault/addons` — optional, composable extensions for runtime behavior ([README](../addons/README.md))
- `@sdux-vault/core` — execution engine for pipelines and state orchestration ([README](../core/README.md))
- `@sdux-vault/core-extensions/angular` — Angular integration layer (signals, DI, reactive bindings) ([README](../core-extensions/angular/README.md))
- `@sdux-vault/engine` — orchestration, conductor, decision engine
- `@sdux-vault/shared` — contracts, types, utilities([README](../shared/README.md))

---

## Tree Shaking & Side Effects

This package includes intentional side effects for:

- runtime instrumentation
- DevTools registration

These are required for debugging capabilities.

As a result, the bundle is marked as side-effectful.

---

## License

For full licensing details:  
https://www.sdux-vault.com/docs/welcome/license#license-texts

MIT © SDuX Vault