@sdux-vault/shared 0.6.0 → 0.9.0

package/README.md

@@ -1,80 +1,61 @@
-# @sdux-vault/shared
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sdux-vault/vault/main/apps/docs-app/assets/brand/sdux/brand-landscape.svg" height="80" alt="SDuX Vault" />
+</p>
 
-> Core primitives, contracts, and utilities for the SDuX platform.
+<h3 align="center">Plain TypeScript. Zero Magic.</h3>
+<p align="center">Deterministic state management for every framework — one pipeline, zero ambiguity.</p>
 
-`@sdux-vault/shared` is the **foundation of the SDuX ecosystem**.  
-It defines the universal language used across all SDuX packages, including types, contracts, behaviors, and utilities.
+# @sdux-vault/shared
 
----
+> Core primitives, contracts, and utilities for the SDuX Vault platform.
 
-## TL;DR
+<p align="center">
+  <a href="https://www.sdux-vault.com"><strong>Docs</strong></a> ·
+  <a href="https://www.sdux-vault.com/stackblitz"><strong>Live Examples</strong></a> ·
+  <a href="https://www.sdux-vault.com/builder"><strong>Pipeline Builder</strong></a> ·
+  <a href="https://github.com/sdux-vault/vault/issues"><strong>Issues</strong></a>
+</p>
 
-For full documentation, guides, and API references:  
-https://www.sdux-vault.com
+<p align="center">
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License" />
+  <img src="https://img.shields.io/badge/TypeScript-first-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/frameworks-Angular%20·%20React%20·%20Vue%20·%20Svelte%20·%20Node-333" alt="Frameworks" />
+</p>
 
----
+## What is SDuX Vault?
 
-## Overview
+SDuX Vault is a **framework-agnostic, deterministic state management system** built around a reactive execution pipeline. It replaces the unpredictable sprawl of action/reducer architectures with a single, ordered, traceable pipeline where every transition is explicit and every output is guaranteed.
 
-SDuX is built as a layered system:
+## What is SDuX Vault Shared?
 
-```plaintext
-shared → engine → core → core-extensions → apps
-           └─────────---------───────────→ devtools
-```
+`@sdux-vault/shared` is the **foundation of the SDuX ecosystem**. It defines the universal language used across all SDuX packages — types, contracts, behaviors, and utilities. Every SDuX package depends on `shared`. It is the lowest layer in the dependency graph and has **zero external dependencies**.
 
-- **apps** → end-user applications
-- **core** → behavior runtime + execution layer
-- **core-extensions** → framework integrations (Angular, React, etc.)
-- **devtools** → end-user tooling
-- **engine** → runtime engine and orchestration
-- **shared** → contracts, types, utilities (this package)
+**Features:**
 
----
+- **Core contracts** — interfaces, shapes, and types that define the SDuX API surface
+- **Behavior and controller abstractions** — base types for pipeline stages
+- **Utility functions** — type guards, safe helpers, runtime utilities
+- **Configuration primitives** — options, settings, and feature flags
+- **Error models** — structured error types and services
+- **Runtime instrumentation hooks** — DevTools integration points
 
-## What This Package Provides
+**Key Characteristics:**
 
-- **Core contracts** — interfaces, shapes, and types
-- **Behavior + controller abstractions**
-- **Utility functions** — safe, composable, framework-agnostic
-- **Configuration primitives**
-- **Error models and services**
-- **Runtime instrumentation hooks (DevTools integration)**
+- ✅ **Framework-agnostic** — pure TypeScript, zero dependencies
+- ✅ **Tree-shakable** — domain-based exports, minimal runtime footprint
+- ✅ **SSR-safe and browser-safe** — works everywhere
+- ✅ **Stable public API** — domain-driven, designed for composition
 
----
-
-## Key Characteristics
-
-- ✅ Framework-agnostic TypeScript
-- ✅ Tree-shakable
-- ✅ SSR-safe and browser-safe
-- ✅ Designed for composition and extensibility
-- ✅ Stable, domain-driven public API
+For full documentation, guides, and API references: [sdux-vault.com](https://www.sdux-vault.com)
 
 ---
 
-## Installation
-
-```bash
-npm install @sdux-vault/shared
-```
+## Example
 
----
-
-## Usage
-
-### Basic Import
-
-```ts
+```typescript
 import { VaultError, BehaviorTypes } from '@sdux-vault/shared';
-```
-
----
-
-### Example: Utility Usage
-
-```ts
 import { isPromise } from '@sdux-vault/shared';
+import type { BehaviorType, StateSnapshotShape } from '@sdux-vault/shared';
 
 if (isPromise(value)) {
   // handle async flow
@@ -83,176 +64,39 @@ if (isPromise(value)) {
 
 ---
 
-### Example: Type Usage
-
-```ts
-import type { BehaviorType } from '@sdux-vault/shared';
-```
-
----
-
-## Public API Structure
-
-### Tree-Shakable by Default
-
-- No unnecessary side effects
-- Domain-based exports
-- Minimal runtime footprint
-
----
-
-### Framework-Agnostic Core
-
-This package:
-
-- has zero framework dependencies
-- supports multiple adapters
-- acts as the foundation for integrations like:
-
-```plaintext
-@sdux-vault/core-extensions/*
-```
-
----
-
-### Safe Runtime Instrumentation
-
-Includes dev-only instrumentation:
-
-- version registration
-- DevTools integration
-
-These are:
-
-- environment guarded
-- idempotent
-- safe in SSR and production
-
----
-
-## Environment Utilities
-
-```ts
-import { DevMode } from '@sdux-vault/shared';
-import { isTestEnv } from '@sdux-vault/shared';
-```
-
-Provides runtime awareness for:
-
-- development mode
-- test environments
-
-These are part of the **runtime platform**, not test-only helpers.
-
----
-
-## Utilities
-
-The `utils` domain includes:
-
-- type guards
-- safe helpers
-- logging utilities
-- runtime helpers
-
-All utilities are:
-
-- side-effect free (except controlled instrumentation)
-- safe for universal usage
-
----
-
 ## Side Effects
 
-This package performs **controlled, dev-only side effects**:
-
-```ts
-import '@sdux-vault/shared';
-```
-
-Triggers:
-
-- version registration for DevTools
-
-Behavior:
-
-- no-op in production
-- idempotent
-- safe across all runtimes
-
----
-
-## Development
-
-### Build
-
-```bash
-npm run build:shared
-```
+This package includes intentional side effects for:
 
-Output:
+- Global TypeScript typing augmentation
+- Runtime version registration for DevTools
 
-```plaintext
-dist/shared
-```
+These are environment-guarded, idempotent, and safe in SSR and production.
 
 ---
 
-### Test
-
-```bash
-npm run test:shared
-```
-
----
+## Installation
 
-### Verify
+This package is installed automatically as a dependency of `@sdux-vault/core`.
 
 ```bash
-npm run verify
+npm install @sdux-vault/core
 ```
 
-Includes:
-
-- linting
-- formatting
-- type checking
-- tests
-
----
-
-## Publishing
-
-See [RELEASE.md](./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/devtools` — observability and debugging layer for runtime inspection ([README](../devtools/tooling/README.md))
-- `@sdux-vault/engine` — orchestration, conductor, decision engine
-
----
-
-### Tree Shaking & Side Effects
-
-This package includes intentional side effects for:
-
-- global TypeScript typing augmentation
-- runtime version registration for devtools
-
-These are required for correct framework behavior.
-
-As a result, the bundle is marked as side-effectful.
+| Package                                                                                      | Purpose                                      |
+| -------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| [`@sdux-vault/engine`](https://www.npmjs.com/package/@sdux-vault/engine)                     | Orchestration, conductor, decision engine    |
+| [`@sdux-vault/core`](https://www.npmjs.com/package/@sdux-vault/core)                         | Behavior runtime and pipeline execution      |
+| [`@sdux-vault/addons`](https://www.npmjs.com/package/@sdux-vault/addons)                     | Optional runtime policies and controllers    |
+| [`@sdux-vault/core-extensions`](https://www.npmjs.com/package/@sdux-vault/core-extensions)   | Framework integrations (Angular, React, Vue) |
+| [`@sdux-vault/devtools-tooling`](https://www.npmjs.com/package/@sdux-vault/devtools-tooling) | Observability and debugging                  |
 
 ---
 
 ## License
 
-For full licensing details:  
-https://www.sdux-vault.com/docs/welcome/license#license-texts
-
-MIT © SDuX Vault
+[MIT (with SDuX Clarification Notice)](https://www.sdux-vault.com/docs/welcome/license#license-texts) © SDuX Vault