@ersbeth/picoflow 0.2.4 → 1.0.1

package/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,1578 @@
+# Implementation Guide - PicoFlow API v1.0.0
+
+> **Note for Library Users:** This guide is intended for library maintainers and contributors who need detailed implementation instructions. If you're a user upgrading your project from v0.x to v1.0.0, please see [UPGRADING.md](UPGRADING.md) instead.
+
+---
+
+## Vue d'ensemble
+
+Cette migration transforme l'API de PicoFlow d'un système basé sur des fonctions getter/watcher vers un système basé sur un contexte de tracking explicite (`TrackingContext`).
+
+### Philosophie de simplification
+
+La nouvelle API élimine les méthodes internes comme `_watch()`, `_watchFrom()`, et `_getFrom()` au profit d'overrides directs de méthodes publiques. Cela rend le code plus simple, plus lisible et plus maintenable.
+
+**Architecture simplifiée :**
+
+```
+Ancienne API (complexe) :
+├─ FlowSignal._watch() [interne]
+├─ FlowSignal._watchFrom() [interne]  
+├─ FlowObservable._getFrom() [interne]
+└─ Overrides de _watch() dans FlowDerivation
+
+Nouvelle API (simple) :
+├─ FlowSignal.watch(context) [publique]
+├─ FlowObservable.get(context) [publique]
+├─ FlowObservable.pick() [publique]
+└─ Override de watch(context) dans FlowDerivation
+```
+
+### Aperçu des Modifications
+
+**Fichiers à créer :** 1
+- `src/basic/trackingContext.ts`
+
+**Fichiers à modifier :** 16
+- Basic (7) : `signal.ts`, `observable.ts`, `constant.ts`, `state.ts` (aucun changement), `derivation.ts`, `effect.ts`, `index.ts`
+- Advanced (5) : `resource.ts`, `resourceAsync.ts`, `array.ts`, `stream.ts`, `streamAsync.ts`
+- Creators (1) : `creators.ts`
+- Solid (1) : `converters.ts`
+
+**Fichiers sans modification :** 3
+- `src/advanced/map.ts` (hérite via FlowState)
+- `src/solid/primitives.ts` (dépend uniquement de SolidJS)
+- `src/solid/index.ts` (fichier d'exports)
+
+**Tests à migrer :** 11 fichiers
+- Basic (5) : `state.test.ts`, `effect.test.ts`, `derivation.test.ts`, `signal.test.ts`, `constant.test.ts`
+- Advanced (6) : `array.test.ts`, `map.test.ts`, `resource.test.ts`, `resourceAsync.test.ts`, `stream.test.ts`, `streamAsync.test.ts`
+
+### Changements clés
+
+**Avant :**
+```typescript
+effect((get, watch) => {
+    const value = get($state);
+    watch($signal);
+});
+
+derivation((get, watch) => {
+    return get($stateA) + get($stateB);
+});
+```
+
+**Après :**
+```typescript
+effect((t) => {
+    const value = $state.get(t);
+    $signal.watch(t);
+});
+
+derivation((t) => {
+    return $stateA.get(t) + $stateB.get(t);
+});
+```
+
+### Bénéfices de la Nouvelle API
+
+1. **Syntaxe chaînée naturelle** : `$parent.get(t).child.get(t)` au lieu de `get(get($parent).child)`
+2. **Contrôle explicite** : `get(t)` pour tracking, `pick()` pour non-tracking
+3. **Code plus simple** : Moins de méthodes internes, architecture plus claire
+4. **API unifiée** : Toutes les classes (basic et advanced) utilisent le même pattern
+5. **Meilleure lisibilité** : L'intention (réactif ou non) est évidente à la lecture
+6. **Plus flexible** : Possibilité de lectures mixtes réactives/non-réactives dans le même scope
+
+---
+
+## Nouvelle API des Observables
+
+### `FlowObservable.get(context)`
+
+**Avant :**
+```typescript
+observable.get()  // Pas de tracking automatique
+```
+
+**Après :**
+```typescript
+observable.get(t)     // Avec tracking (dans effect/derivation)
+observable.get(null)  // Sans tracking
+observable.pick()     // Sans tracking (syntaxe alternative)
+```
+
+### `FlowObservable.pick()`
+
+**Nouvelle méthode** - équivalent à `get(null)` :
+```typescript
+const value = $state.pick();  // Lecture sans tracking
+```
+
+---
+
+## Nouvelle API des Signaux
+
+### `FlowSignal.watch(context)`
+
+**Avant :**
+```typescript
+watch($signal)  // Via la fonction watcher
+```
+
+**Après :**
+```typescript
+$signal.watch(t)  // Méthode directe, contexte obligatoire
+```
+
+⚠️ **Important** : `watch()` nécessite TOUJOURS un contexte. Pas de version sans paramètre.
+
+---
+
+## Changements dans les Fichiers Source
+
+### 1. Créer `src/basic/trackingContext.ts` (NOUVEAU FICHIER)
+
+```typescript
+import type { FlowEffect } from "./effect";
+import type { FlowDerivation } from "./derivation";
+import type { FlowSignal } from "./signal";
+
+/**
+ * Represents a tracking context used to register dependencies
+ * during reactive computations.
+ * 
+ * @public
+ */
+export class TrackingContext {
+    /*@internal*/
+    constructor(
+        private _owner: FlowEffect | FlowDerivation<unknown>
+    ) {}
+
+    /**
+     * Registers a dependency on the given signal.
+     * @internal
+     */
+    /*@internal*/ _registerDependency(signal: FlowSignal): void {
+        this._owner._registerDependency(signal);
+    }
+}
+```
+
+### 2. Modifier `src/basic/signal.ts`
+
+**Ajouts :**
+- Import `TrackingContext`
+- Méthode publique `watch(context: TrackingContext)`
+
+**Changements à apporter :**
+
+```typescript
+// AJOUTER cet import en haut du fichier
+import type { TrackingContext } from "./trackingContext";
+
+// AJOUTER cette méthode dans la classe FlowSignal (après la méthode trigger)
+/**
+ * Watches the signal, registering it as a dependency in the tracking context.
+ * @param context - The tracking context (required).
+ * @public
+ */
+public watch(context: TrackingContext): void {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    context._registerDependency(this);
+}
+```
+
+**Suppressions :**
+- SUPPRIMER le type `FlowWatcher` (ligne 5-9)
+- SUPPRIMER la méthode `_watch()` (ligne 77-80)
+- SUPPRIMER la méthode `_watchFrom()` (ligne 87-90)
+
+### 3. Modifier `src/basic/observable.ts`
+
+**Changements majeurs :**
+- Remplacer la méthode abstraite `get()` par `get(context: TrackingContext | null)`
+- Ajouter la méthode abstraite protégée `_getRaw()`
+- Ajouter la méthode publique `pick()`
+- Supprimer la méthode `_getFrom()`
+
+**Code complet de la classe :**
+
+```typescript
+import { FlowSignal } from "./signal";
+import type { TrackingContext } from "./trackingContext";
+import { FlowEffect } from "./effect";
+
+/**
+ * Represents a reactive observable that holds and tracks a value.
+ *
+ * @remarks Subclasses must implement the {@link FlowObservable._getRaw} method to return the current value.
+ * @typeParam T - The type of the value held by the observable.
+ * @public
+ */
+export abstract class FlowObservable<T> extends FlowSignal {
+    /**
+     * Gets the current value with optional dependency tracking.
+     * @param context - The tracking context for reactive tracking, or null for untracked access.
+     * @returns The current value of type T.
+     * @public
+     */
+    get(context: TrackingContext | null): T {
+        if (context) {
+            this.watch(context);
+        }
+        return this._getRaw();
+    }
+
+    /**
+     * Gets the current value without any dependency tracking.
+     * Equivalent to calling get(null).
+     * @returns The current value of type T.
+     * @public
+     */
+    pick(): T {
+        return this._getRaw();
+    }
+
+    /**
+     * Internal method to retrieve the raw value.
+     * Subclasses must override this method to provide the current value.
+     * @internal
+     */
+    protected abstract _getRaw(): T;
+
+    /* INTERNAL -------------------------------------------*/
+
+    /*@internal*/ protected _value!: T;
+
+    /**
+     * Subscribes a listener function to changes of the observable.
+     * The listener is executed immediately with the current value and on subsequent updates.
+     * @param listener - A callback function that receives the new value.
+     * @returns A disposer function to cancel the subscription.
+     */
+    subscribe(listener: (value: T) => void): () => void {
+        const effect = new FlowEffect((t) => {
+            listener(this.get(t));
+        });
+        return () => effect.dispose();
+    }
+}
+```
+
+**Suppressions :**
+- SUPPRIMER le type `FlowGetter` (ligne 5-11)
+- SUPPRIMER la méthode `abstract get(): T` (ligne 23-28)
+- SUPPRIMER la méthode `_getFrom` (ligne 34-37)
+
+### 4. Modifier `src/basic/constant.ts`
+
+**Changements :**
+- Remplacer la méthode `get()` par la méthode protégée `_getRaw()`
+
+**Avant :**
+```typescript
+get(): T {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._initLazy();
+    return this._value;
+}
+```
+
+**Après :**
+```typescript
+/**
+ * Internal method to get the raw value.
+ * @internal
+ */
+protected _getRaw(): T {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._initLazy();
+    return this._value;
+}
+```
+
+### 5. Modifier `src/basic/state.ts`
+
+**Aucun changement nécessaire** - La classe hérite automatiquement des nouvelles méthodes `get()` et `pick()` de `FlowObservable`.
+
+### 6. Modifier `src/basic/derivation.ts`
+
+**Changements majeurs :**
+- Remplacer le type du paramètre `compute` : `(get: FlowGetter, watch: FlowWatcher) => T` → `(t: TrackingContext) => T`
+- Supprimer `_trackedGet`, `_untrackedGet`, `_trackedWatch`, `_untrackedWatch`
+- Ajouter `_trackedContext: TrackingContext`
+- Remplacer `_trackedCompute` et `_untrackedCompute` par un seul `_compute`
+- Remplacer la méthode `get()` par `_getRaw()`
+- Renommer la méthode `_compute()` en `_update()`
+- Override la méthode `watch()` pour gérer le compute lazy
+
+**Code complet de la classe :**
+
+```typescript
+import { FlowObservable } from "./observable";
+import { TrackingContext } from "./trackingContext";
+
+/**
+ * Represents a reactive derivation whose value is computed based on other reactive signals.
+ * @remarks
+ * It tracks dependencies automatically and recomputes its value when any dependency changes.
+ * Use FlowDerivation to create derived values in a reactive manner. It lazily initializes the computed value,
+ * ensuring that computations only occur when necessary.
+ * @typeParam T - The type of the computed value.
+ * @public
+ */
+export class FlowDerivation<T> extends FlowObservable<T> {
+    /**
+     * Creates a new FlowDerivation.
+     * @param compute - A function that computes the derived value using a tracking context.
+     * @public
+     */
+    constructor(compute: (t: TrackingContext) => T) {
+        super();
+        this._compute = compute;
+        this._trackedContext = new TrackingContext(this);
+    }
+
+    /**
+     * Internal method to get the raw value.
+     * @internal
+     */
+    protected _getRaw(): T {
+        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+        this._initLazy();
+        this._update();
+        return this._value;
+    }
+
+    /* INTERNAL --------------------------------------------------------- */
+
+    private _initialized = false;
+    private _dirty = false;
+    private _compute: (t: TrackingContext) => T;
+    private _trackedContext: TrackingContext;
+
+    private _initLazy(): void {
+        if (!this._initialized) {
+            this._value = this._compute(this._trackedContext);
+            this._initialized = true;
+        }
+    }
+
+    /* @internal */ private _update(): void {
+        if (this._dirty) {
+            // Store current dependencies
+            const dependencies = [...this._dependencies];
+
+            // Clear current dependencies, compute and retrack dependencies
+            this._dependencies.clear();
+            this._value = this._compute(this._trackedContext);
+
+            // Unsubscribe from dependencies that are no longer needed
+            const dependenciesToRemove = dependencies.filter(
+                (dependency) => !this._dependencies.has(dependency),
+            );
+            dependenciesToRemove.forEach((dependency) =>
+                dependency._unregisterDependency(this),
+            );
+
+            this._dirty = false;
+        }
+    }
+
+    /* @internal */ override _notify(): void {
+        this._dirty = true;
+        super._notify();
+    }
+
+    /**
+     * Override watch to ensure the derivation computes its value
+     * and tracks its own dependencies when watched.
+     * @public
+     */
+    public override watch(context: TrackingContext): void {
+        super.watch(context);  // Register this derivation as a dependency
+        
+        // Ensure the derivation is initialized and up-to-date
+        // This is needed when watching a derivation without reading its value
+        this._initLazy();
+        this._update();
+    }
+}
+```
+
+**À supprimer complètement :**
+- `_trackedGet`
+- `_untrackedGet`
+- `_trackedWatch`
+- `_untrackedWatch`
+- `_initEager`
+- `_trackedCompute`
+- `_untrackedCompute`
+- `_watch()` (l'override est remplacé par l'override de `watch()`)
+
+### 7. Modifier `src/basic/effect.ts`
+
+**Changements majeurs :**
+- Remplacer le type du paramètre `apply` : `(get: FlowGetter, watch: FlowWatcher) => void` → `(t: TrackingContext) => void`
+- Supprimer `_trackedGet`, `_untrackedGet`, `_trackedWatch`, `_untrackedWatch`
+- Ajouter `_trackedContext: TrackingContext`
+- Simplifier `_trackedExec` et `_untrackedExec` en un seul `_apply`
+- Modifier la logique de `_exec()`
+
+**Code complet de la classe :**
+
+```typescript
+import type { FlowSignal } from "./signal";
+import { TrackingContext } from "./trackingContext";
+
+/**
+ * Represents a reactive effect that executes side-effect functions based
+ * on its tracked dependencies.
+ *
+ * @remarks
+ * The FlowEffect executes an apply function that performs side effects,
+ * running initially in a tracked mode to register dependencies.
+ *
+ * @public
+ */
+export class FlowEffect {
+    /**
+     * Creates a new FlowEffect.
+     *
+     * @param apply - A side-effect function that receives a tracking context to
+     * access and register dependencies on reactive observables and signals.
+     *
+     * @remarks
+     * The provided function is executed immediately with a tracking context to collect dependencies.
+     *
+     * @public
+     */
+    constructor(apply: (t: TrackingContext) => void) {
+        this._trackedContext = new TrackingContext(this);
+        this._apply = apply;
+        this._exec();
+    }
+
+    /**
+     * Disposes the effect, unregistering all its tracked dependencies.
+     *
+     * @remarks
+     * Once disposed, the effect must no longer be used. Trying to dispose an effect
+     * that is already disposed will throw an error.
+     *
+     * @public
+     */
+    public dispose(): void {
+        if (this._disposed) throw new Error("[PicoFlow] Effect is disposed");
+        Array.from(this._dependencies).forEach((dependency) => {
+            this._unregisterDependency(dependency);
+        });
+        this._disposed = true;
+    }
+
+    /**
+     * Indicates whether this effect has been disposed.
+     *
+     * @returns A boolean value that is true if the effect is disposed, false otherwise.
+     *
+     * @public
+     */
+    public get disposed(): boolean {
+        return this._disposed;
+    }
+
+    /* INTERNAL ------------------------------------------------------------ */
+
+    private _disposed = false;
+    private _dependencies = new Set<FlowSignal>();
+    private _trackedContext: TrackingContext;
+    private _apply: (t: TrackingContext) => void;
+
+    /*@internal*/ _exec(): void {
+        if (this._disposed)
+            /* v8 ignore next 1 */
+            throw new Error("[PicoFlow] Effect is disposed");
+        
+        // Always execute with tracking context
+        this._apply(this._trackedContext);
+    }
+
+    /*@internal*/ _registerDependency(dependency: FlowSignal): void {
+        this._dependencies.add(dependency);
+        dependency._registerEffect(this);
+    }
+
+    /*@internal*/ _unregisterDependency(dependency: FlowSignal): void {
+        this._dependencies.delete(dependency);
+        dependency._unregisterEffect(this);
+    }
+}
+```
+
+**À supprimer complètement :**
+- `_initialized`
+- `_trackedGet`
+- `_untrackedGet`
+- `_trackedWatch`
+- `_untrackedWatch`
+- `_trackedExec`
+- `_untrackedExec`
+
+**Changement comportemental important :**
+Dans l'ancienne API, les effects s'exécutaient en mode "tracked" la première fois, puis "untracked" les fois suivantes. Dans la nouvelle API, ils s'exécutent **toujours en mode tracked**, et c'est l'utilisateur qui décide explicitement avec `.get(t)` ou `.pick()` ce qui doit être tracké ou non.
+
+### 8. Modifier `src/basic/index.ts`
+
+**Ajouts :**
+```typescript
+export { TrackingContext } from "./trackingContext";
+```
+
+**Suppressions :**
+```typescript
+// SUPPRIMER ces exports (s'ils existent)
+export type { FlowGetter } from "./observable";
+export type { FlowWatcher } from "./signal";
+```
+
+---
+
+## Changements dans les Fichiers Advanced
+
+Les classes dans `src/advanced/` qui étendent `FlowObservable` et override la méthode `get()` doivent être modifiées. Le pattern est identique pour toutes : remplacer `public get()` par `protected _getRaw()`.
+
+**Résumé :** 5 fichiers à modifier, 1 fichier sans modification.
+
+**Pattern uniforme :**
+Toutes les classes advanced qui override `get()` suivent le même pattern de migration :
+1. Remplacer `public get()` → `protected _getRaw()`
+2. La classe hérite automatiquement de `get(context)` et `pick()`
+3. Aucun autre changement nécessaire
+
+### 9. Modifier `src/advanced/resource.ts`
+
+**Changement unique :**
+Remplacer la méthode `get()` par `_getRaw()`
+
+**Avant :**
+```typescript
+public get(): T | undefined {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+}
+```
+
+**Après :**
+```typescript
+protected _getRaw(): T | undefined {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+}
+```
+
+**Bénéfices :**
+La classe hérite automatiquement de `get(context)` et `pick()` de `FlowObservable`.
+
+### 10. Modifier `src/advanced/resourceAsync.ts`
+
+**Changement unique :**
+Remplacer la méthode `get()` par `_getRaw()`
+
+**Avant :**
+```typescript
+public get(): Promise<T> {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (!this._value) this._value = this._fetch();
+    return this._value;
+}
+```
+
+**Après :**
+```typescript
+protected _getRaw(): Promise<T> {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (!this._value) this._value = this._fetch();
+    return this._value;
+}
+```
+
+### 11. Modifier `src/advanced/array.ts`
+
+**Changement unique :**
+Remplacer la méthode `get()` par `_getRaw()`
+
+**Avant :**
+```typescript
+get(): T[] {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return [...this._value]; // Ensure nobody can modify the original array
+}
+```
+
+**Après :**
+```typescript
+protected _getRaw(): T[] {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return [...this._value]; // Ensure nobody can modify the original array
+}
+```
+
+**Note :** La propriété `length` n'est pas impactée par ce changement.
+
+### 12. Modifier `src/advanced/stream.ts`
+
+**Changement unique :**
+Remplacer la méthode `get()` par `_getRaw()`
+
+**Avant :**
+```typescript
+public get(): T | undefined {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+}
+```
+
+**Après :**
+```typescript
+protected _getRaw(): T | undefined {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+}
+```
+
+### 13. Modifier `src/advanced/streamAsync.ts`
+
+**Changement unique :**
+Remplacer la méthode `get()` par `_getRaw()`
+
+**Avant :**
+```typescript
+public get(): Promise<T> {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+}
+```
+
+**Après :**
+```typescript
+protected _getRaw(): Promise<T> {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    return this._value;
+}
+```
+
+### 14. `src/advanced/map.ts` - AUCUNE MODIFICATION
+
+**Important :** `FlowMap` étend `FlowState`, qui étend `FlowConstant`, qui implémente déjà `_getRaw()`. Aucune modification n'est nécessaire pour ce fichier.
+
+---
+
+## Changements dans le Fichier Creators
+
+### 15. Modifier `src/creators.ts`
+
+**Changements :**
+- Modifier les signatures de `derivation()` et `effect()`
+- Supprimer les imports de `FlowGetter` et `FlowWatcher`
+- Ajouter l'import de `TrackingContext`
+
+**Imports - Avant :**
+```typescript
+import type { FlowGetter, FlowWatcher } from "./basic/";
+```
+
+**Imports - Après :**
+```typescript
+import type { TrackingContext } from "./basic/";
+```
+
+**Fonction `derivation()` - Avant :**
+```typescript
+/**
+ * Creates a new reactive derivation whose value is computed based on other reactive signals.
+ * @typeParam T - The type of the derived value.
+ * @param fn - A function that computes the derived value. It receives a getter and a watcher
+ * function to access and register dependencies.
+ * @returns A new instance of {@link FlowDerivation}.
+ * @public
+ */
+export function derivation<T>(
+    fn: (get: FlowGetter, watch: FlowWatcher) => T,
+): FlowDerivation<T> {
+    return new FlowDerivation(fn);
+}
+```
+
+**Fonction `derivation()` - Après :**
+```typescript
+/**
+ * Creates a new reactive derivation whose value is computed based on other reactive signals.
+ * @typeParam T - The type of the derived value.
+ * @param fn - A function that computes the derived value using a tracking context.
+ * @returns A new instance of {@link FlowDerivation}.
+ * @public
+ */
+export function derivation<T>(
+    fn: (t: TrackingContext) => T,
+): FlowDerivation<T> {
+    return new FlowDerivation(fn);
+}
+```
+
+**Fonction `effect()` - Avant :**
+```typescript
+/**
+ * Creates a new reactive effect that executes a side-effect function based on its dependencies.
+ * @param fn - A function that performs side effects. It receives a getter and a watcher
+ * function for tracking reactive dependencies.
+ * @returns A new instance of {@link FlowEffect}.
+ * @public
+ */
+export function effect(
+    fn: (get: FlowGetter, watch: FlowWatcher) => void,
+): FlowEffect {
+    return new FlowEffect(fn);
+}
+```
+
+**Fonction `effect()` - Après :**
+```typescript
+/**
+ * Creates a new reactive effect that executes a side-effect function based on its dependencies.
+ * @param fn - A function that performs side effects using a tracking context.
+ * @returns A new instance of {@link FlowEffect}.
+ * @public
+ */
+export function effect(
+    fn: (t: TrackingContext) => void,
+): FlowEffect {
+    return new FlowEffect(fn);
+}
+```
+
+**Note :** Les autres fonctions creator (`signal`, `state`, `constant`, `resource`, etc.) ne sont pas impactées.
+
+---
+
+## Changements dans les Fichiers Solid (Intégration SolidJS)
+
+Les fichiers dans `src/solid/` sont des adaptateurs d'intégration entre PicoFlow et SolidJS. Ils convertissent les observables PicoFlow en primitives SolidJS.
+
+### 16. Modifier `src/solid/converters.ts`
+
+Ce fichier nécessite plusieurs modifications pour utiliser la nouvelle API avec `TrackingContext`.
+
+#### Imports
+
+**Avant :**
+```typescript
+import { FlowEffect, FlowObservable, type FlowGetter, FlowDerivation } from '../basic';
+```
+
+**Après :**
+```typescript
+import { FlowEffect, FlowObservable, type TrackingContext, FlowDerivation } from '../basic';
+```
+
+#### Fonction `fromSync`
+
+**Avant :**
+```typescript
+function fromSync<T>(state: FlowObservable<T>): SolidDerivation<T> {
+    const solidState = new SolidState<T>(state.get());
+
+    let fx: FlowEffect;
+
+    onMount(() => {
+        fx = new FlowEffect((get) => {
+            const value = get(state);
+            solidState.set(() => value);
+        });
+    });
+
+    onCleanup(() => fx.dispose());
+
+    return solidState
+}
+```
+
+**Après :**
+```typescript
+function fromSync<T>(state: FlowObservable<T>): SolidDerivation<T> {
+    const solidState = new SolidState<T>(state.pick());  // Lecture initiale non-réactive
+
+    let fx: FlowEffect;
+
+    onMount(() => {
+        fx = new FlowEffect((t) => {                      // t au lieu de get
+            const value = state.get(t);                    // state.get(t) au lieu de get(state)
+            solidState.set(() => value);
+        });
+    });
+
+    onCleanup(() => fx.dispose());
+
+    return solidState
+}
+```
+
+#### Fonction `fromAsync`
+
+**Avant :**
+```typescript
+function fromAsync<T>(derivation: FlowObservable<Promise<T>>): SolidResource<T> {
+    const solidResource = new SolidResource<T>(async () => {
+        const value = await derivation.get();
+        return value;
+    });
+
+    let fx: FlowEffect;
+
+    onMount(() => {
+        fx = new FlowEffect(async (get) => {
+            await get(derivation);
+            solidResource.refetch();
+        });
+    });
+
+    onCleanup(() => fx.dispose());
+
+    return solidResource;
+}
+```
+
+**Après :**
+```typescript
+function fromAsync<T>(derivation: FlowObservable<Promise<T>>): SolidResource<T> {
+    const solidResource = new SolidResource<T>(async () => {
+        const value = await derivation.pick();              // pick() au lieu de get()
+        return value;
+    });
+
+    let fx: FlowEffect;
+
+    onMount(() => {
+        fx = new FlowEffect(async (t) => {                  // t au lieu de get
+            await derivation.get(t);                         // derivation.get(t) au lieu de get(derivation)
+            solidResource.refetch();
+        });
+    });
+
+    onCleanup(() => fx.dispose());
+
+    return solidResource;
+}
+```
+
+#### Fonction `shallowFrom`
+
+**Changement :**
+Remplacer `flow.get()` par `flow.pick()`
+
+**Avant :**
+```typescript
+function shallowFrom<T>(flow: FlowObservable<Promise<T>> | FlowObservable<T>): SolidDerivation<T> | SolidResource<T> {
+    const initialValue = flow.get();
+    // ...
+}
+```
+
+**Après :**
+```typescript
+function shallowFrom<T>(flow: FlowObservable<Promise<T>> | FlowObservable<T>): SolidDerivation<T> | SolidResource<T> {
+    const initialValue = flow.pick();  // pick() au lieu de get()
+    // ...
+}
+```
+
+#### Fonction `deepFrom`
+
+**Changements :**
+- Signatures : `(get: FlowGetter)` → `(t: TrackingContext)`
+- Implémentation : `(get) =>` → `(t) =>`
+- Lecture : `derivation.get()` → `derivation.pick()`
+
+**Avant :**
+```typescript
+function deepFrom<T>(getter: (get: FlowGetter) => T): SolidDerivation<T>;
+function deepFrom<T>(getter: (get: FlowGetter) => Promise<T>): SolidResource<T>;
+function deepFrom<T>(getter: (get: FlowGetter) => T | Promise<T>): SolidDerivation<T> | SolidResource<T> {
+    const derivation = new FlowDerivation((get) => {
+        return getter(get);
+    });
+
+    const initialValue = derivation.get();
+    const isAsync = initialValue instanceof Promise;
+
+    if (isAsync) {
+        return fromAsync(derivation as FlowObservable<Promise<T>>);
+    }
+
+    return fromSync(derivation as FlowObservable<T>);
+}
+```
+
+**Après :**
+```typescript
+function deepFrom<T>(getter: (t: TrackingContext) => T): SolidDerivation<T>;
+function deepFrom<T>(getter: (t: TrackingContext) => Promise<T>): SolidResource<T>;
+function deepFrom<T>(getter: (t: TrackingContext) => T | Promise<T>): SolidDerivation<T> | SolidResource<T> {
+    const derivation = new FlowDerivation((t) => {
+        return getter(t);
+    });
+
+    const initialValue = derivation.pick();  // pick() au lieu de get()
+    const isAsync = initialValue instanceof Promise;
+
+    if (isAsync) {
+        return fromAsync(derivation as FlowObservable<Promise<T>>);
+    }
+
+    return fromSync(derivation as FlowObservable<T>);
+}
+```
+
+#### Fonction `from` - Signatures TypeScript
+
+Mettre à jour toutes les signatures qui utilisent `FlowGetter` :
+
+**Avant :**
+```typescript
+export function from<T>(flow: (get: FlowGetter) => NotPromise<T>): SolidDerivation<NotPromise<T>>;
+export function from<T>(flow: (get: FlowGetter) => Promise<NotPromise<T>>): SolidResource<NotPromise<T>>;
+export function from<T>(
+    flow: ((get: FlowGetter) => NotPromise<T>) | ((get: FlowGetter) => Promise<NotPromise<T>>),
+): SolidDerivation<T> | SolidResource<T>;
+```
+
+**Après :**
+```typescript
+export function from<T>(flow: (t: TrackingContext) => NotPromise<T>): SolidDerivation<NotPromise<T>>;
+export function from<T>(flow: (t: TrackingContext) => Promise<NotPromise<T>>): SolidResource<NotPromise<T>>;
+export function from<T>(
+    flow: ((t: TrackingContext) => NotPromise<T>) | ((t: TrackingContext) => Promise<NotPromise<T>>),
+): SolidDerivation<T> | SolidResource<T>;
+```
+
+#### Fonction `from` - Implémentation
+
+**Avant :**
+```typescript
+export function from<T>(
+    flow: FlowObservable<Promise<T>> | FlowObservable<T> | ((get: FlowGetter) => T) | ((get: FlowGetter) => Promise<T>),
+): SolidDerivation<T> | SolidResource<T> {
+    if (flow instanceof FlowObservable) {
+        return shallowFrom(flow as FlowObservable<T | Promise<T>>) as SolidDerivation<T> | SolidResource<T>;
+    }
+
+    return deepFrom(flow as (get: FlowGetter) => T | Promise<T>) as SolidDerivation<T> | SolidResource<T>;
+}
+```
+
+**Après :**
+```typescript
+export function from<T>(
+    flow: FlowObservable<Promise<T>> | FlowObservable<T> | ((t: TrackingContext) => T) | ((t: TrackingContext) => Promise<T>),
+): SolidDerivation<T> | SolidResource<T> {
+    if (flow instanceof FlowObservable) {
+        return shallowFrom(flow as FlowObservable<T | Promise<T>>) as SolidDerivation<T> | SolidResource<T>;
+    }
+
+    return deepFrom(flow as (t: TrackingContext) => T | Promise<T>) as SolidDerivation<T> | SolidResource<T>;
+}
+```
+
+**Résumé des changements dans converters.ts :**
+- Import : `FlowGetter` → `TrackingContext`
+- FlowEffect : `(get) =>` → `(t) =>`
+- FlowDerivation : `(get) =>` → `(t) =>`
+- Lecture réactive : `get(observable)` → `observable.get(t)`
+- Lecture initiale : `observable.get()` → `observable.pick()`
+- Toutes les signatures : `(get: FlowGetter)` → `(t: TrackingContext)`
+
+### 17. `src/solid/primitives.ts` - AUCUNE MODIFICATION
+
+Ce fichier ne dépend que de SolidJS et n'utilise pas l'API PicoFlow. Aucune modification nécessaire.
+
+### 18. `src/solid/index.ts` - AUCUNE MODIFICATION
+
+Simple fichier d'exports. Aucune modification nécessaire.
+
+---
+
+## Migration des Tests
+
+### Pattern 1 : Effect simple avec get
+
+**Avant :**
+```typescript
+effect((get) => {
+    const value = get($state);
+    effectFn(value);
+});
+```
+
+**Après :**
+```typescript
+effect((t) => {
+    const value = $state.get(t);
+    effectFn(value);
+});
+```
+
+### Pattern 2 : Effect avec watch
+
+**Avant :**
+```typescript
+effect((get, watch) => {
+    watch($signal);
+    effectFn();
+});
+```
+
+**Après :**
+```typescript
+effect((t) => {
+    $signal.watch(t);
+    effectFn();
+});
+```
+
+### Pattern 3 : Derivation
+
+**Avant :**
+```typescript
+const $derived = derivation((get) => {
+    return get($stateA) + get($stateB);
+});
+```
+
+**Après :**
+```typescript
+const $derived = derivation((t) => {
+    return $stateA.get(t) + $stateB.get(t);
+});
+```
+
+### Pattern 4 : Nested states
+
+**Avant :**
+```typescript
+effect((get) => {
+    const a = get(get($stateC).a);
+    effectFn(a);
+});
+```
+
+**Après :**
+```typescript
+effect((t) => {
+    const a = $stateC.get(t).a.get(t);
+    effectFn(a);
+});
+```
+
+### Pattern 5 : Lecture non-réactive (nouveau)
+
+**Après uniquement :**
+```typescript
+effect((t) => {
+    const tracked = $stateA.get(t);    // Réactif
+    const untracked = $stateB.pick();  // Non-réactif
+    // ou
+    const untracked2 = $stateB.get(null);  // Non-réactif
+    
+    effectFn(tracked, untracked);
+});
+```
+
+### Pattern 6 : Subscribe (modification mineure)
+
+Les `subscribe` sont impactés car ils utilisent des effects en interne.
+
+**Avant :**
+```typescript
+$state.subscribe((value) => {
+    console.log(value);
+});
+```
+
+**Après :**
+```typescript
+// Le code reste identique pour l'utilisateur
+$state.subscribe((value) => {
+    console.log(value);
+});
+
+// Mais en interne, la méthode a changé (voir src/basic/observable.ts)
+```
+
+### Pattern 7 : Utilisation des classes Advanced
+
+Les classes advanced (`FlowArray`, `FlowResource`, `FlowStream`, etc.) héritent automatiquement de la nouvelle API.
+
+**Avant :**
+```typescript
+const $items = array([1, 2, 3]);
+
+effect((get) => {
+    const items = get($items);
+    console.log(items.length);
+});
+```
+
+**Après :**
+```typescript
+const $items = array([1, 2, 3]);
+
+effect((t) => {
+    const items = $items.get(t);      // Réactif
+    // ou
+    const items2 = $items.pick();      // Non-réactif
+    console.log(items.length);
+});
+```
+
+**Nouveau : Accès mixte dans les collections**
+```typescript
+const $users = array<User>([]);
+
+effect((t) => {
+    // Réagir aux changements du tableau
+    const users = $users.get(t);
+    
+    // Mais lire les propriétés des users sans réagir à leurs changements
+    users.forEach(user => {
+        console.log(user.$name.pick());  // Non-réactif
+    });
+});
+```
+
+---
+
+## Exemples Complets de Migration
+
+### Exemple 1 : state.test.ts - Test "nested states"
+
+**Avant :**
+```typescript
+test("nested states", ()=> {
+    const $stateA = state(1);
+    const $stateB = state(2);
+    const $stateC = state({
+        a: $stateA,
+        b: $stateB,
+    });
+
+    const effectFn = vi.fn();
+    effect((get) => {
+        const a = get(get($stateC).a);
+        effectFn(a)
+    });
+
+    expect(effectFn).toHaveBeenCalledTimes(1);
+    expect(effectFn).toHaveBeenLastCalledWith(1);
+})
+```
+
+**Après :**
+```typescript
+test("nested states", ()=> {
+    const $stateA = state(1);
+    const $stateB = state(2);
+    const $stateC = state({
+        a: $stateA,
+        b: $stateB,
+    });
+
+    const effectFn = vi.fn();
+    effect((t) => {
+        const a = $stateC.get(t).a.get(t);
+        effectFn(a)
+    });
+
+    expect(effectFn).toHaveBeenCalledTimes(1);
+    expect(effectFn).toHaveBeenLastCalledWith(1);
+})
+```
+
+### Exemple 2 : Derivation complexe
+
+**Avant :**
+```typescript
+const $fullName = derivation((get) => {
+    const firstName = get($firstName);
+    const lastName = get($lastName);
+    return `${firstName} ${lastName}`;
+});
+```
+
+**Après :**
+```typescript
+const $fullName = derivation((t) => {
+    const firstName = $firstName.get(t);
+    const lastName = $lastName.get(t);
+    return `${firstName} ${lastName}`;
+});
+```
+
+### Exemple 3 : Effect avec lecture mixte
+
+**Nouveau pattern possible :**
+```typescript
+// Réagir uniquement à $trigger, mais lire $data sans créer de dépendance
+effect((t) => {
+    $trigger.watch(t);  // Crée une dépendance
+    const data = $data.pick();  // Ne crée PAS de dépendance
+    console.log("Triggered with data:", data);
+});
+```
+
+### Exemple 4 : FlowArray avec effet
+
+**Avant :**
+```typescript
+const $items = array([1, 2, 3]);
+
+effect((get) => {
+    const items = get($items);
+    console.log("Array length:", items.length);
+});
+
+$items.push(4);  // L'effect se déclenche
+```
+
+**Après :**
+```typescript
+const $items = array([1, 2, 3]);
+
+effect((t) => {
+    const items = $items.get(t);
+    console.log("Array length:", items.length);
+});
+
+$items.push(4);  // L'effect se déclenche
+```
+
+### Exemple 5 : FlowResource avec dérivation
+
+**Avant :**
+```typescript
+const $user = resource(() => fetchUser());
+
+const $userName = derivation((get) => {
+    const user = get($user);
+    return user?.name ?? "Unknown";
+});
+
+effect((get) => {
+    console.log(get($userName));
+});
+```
+
+**Après :**
+```typescript
+const $user = resource(() => fetchUser());
+
+const $userName = derivation((t) => {
+    const user = $user.get(t);
+    return user?.name ?? "Unknown";
+});
+
+effect((t) => {
+    console.log($userName.get(t));
+});
+```
+
+### Exemple 6 : FlowStream avec tracking sélectif
+
+**Nouveau pattern :**
+```typescript
+const $messages = stream<string>((set) => {
+    const ws = new WebSocket("ws://...");
+    ws.onmessage = (e) => set(e.data);
+    return () => ws.close();
+});
+
+const $config = state({ showLogs: true });
+
+effect((t) => {
+    const message = $messages.get(t);     // Réactif aux messages
+    const config = $config.pick();         // Non-réactif au config
+    
+    if (config.showLogs) {
+        console.log(message);
+    }
+});
+```
+
+### Exemple 7 : Intégration SolidJS avec from()
+
+**Avant :**
+```typescript
+import { from } from 'picoflow/solid';
+
+const $picoState = state(42);
+
+// Convertir en SolidJS
+const solidSignal = from($picoState);
+
+// Ou avec une fonction getter
+const solidDerived = from((get) => {
+    return get($stateA) + get($stateB);
+});
+```
+
+**Après :**
+```typescript
+import { from } from 'picoflow/solid';
+
+const $picoState = state(42);
+
+// Convertir en SolidJS
+const solidSignal = from($picoState);
+
+// Ou avec une fonction getter utilisant TrackingContext
+const solidDerived = from((t) => {
+    return $stateA.get(t) + $stateB.get(t);
+});
+```
+
+---
+
+## Checklist de Migration
+
+### Fichiers source - Basic
+
+- [ ] Créer `src/basic/trackingContext.ts`
+- [ ] Modifier `src/basic/signal.ts`
+  - [ ] Ajouter import `TrackingContext`
+  - [ ] Ajouter méthode `watch(context: TrackingContext)`
+  - [ ] Supprimer type `FlowWatcher`
+  - [ ] Supprimer méthode `_watch()`
+  - [ ] Supprimer méthode `_watchFrom()`
+- [ ] Modifier `src/basic/observable.ts`
+  - [ ] Ajouter import `TrackingContext`
+  - [ ] Remplacer `abstract get()` par `get(context: TrackingContext | null)`
+  - [ ] Ajouter méthode `pick()`
+  - [ ] Ajouter `abstract _getRaw()`
+  - [ ] Supprimer type `FlowGetter`
+  - [ ] Supprimer méthode `_getFrom`
+  - [ ] Mettre à jour `subscribe` pour utiliser `(t) =>` au lieu de `(get) =>`
+- [ ] Modifier `src/basic/constant.ts`
+  - [ ] Remplacer `get()` par `protected _getRaw()`
+- [ ] Modifier `src/basic/derivation.ts`
+  - [ ] Ajouter import `TrackingContext`
+  - [ ] Changer signature du constructeur
+  - [ ] Remplacer logique de tracking
+  - [ ] Remplacer `get()` par `_getRaw()`
+  - [ ] Override la méthode `watch(context)` pour gérer le compute lazy
+- [ ] Modifier `src/basic/effect.ts`
+  - [ ] Ajouter import `TrackingContext`
+  - [ ] Changer signature du constructeur
+  - [ ] Simplifier logique d'exécution
+  - [ ] Supprimer `_initialized`
+- [ ] Modifier `src/basic/index.ts`
+  - [ ] Ajouter export de `TrackingContext`
+  - [ ] Supprimer exports de `FlowGetter` et `FlowWatcher`
+
+### Fichiers source - Advanced
+
+- [ ] Modifier `src/advanced/resource.ts`
+  - [ ] Remplacer `public get()` par `protected _getRaw()`
+- [ ] Modifier `src/advanced/resourceAsync.ts`
+  - [ ] Remplacer `public get()` par `protected _getRaw()`
+- [ ] Modifier `src/advanced/array.ts`
+  - [ ] Remplacer `get()` par `protected _getRaw()`
+- [ ] Modifier `src/advanced/stream.ts`
+  - [ ] Remplacer `public get()` par `protected _getRaw()`
+- [ ] Modifier `src/advanced/streamAsync.ts`
+  - [ ] Remplacer `public get()` par `protected _getRaw()`
+- [ ] Vérifier `src/advanced/map.ts` (aucune modification nécessaire)
+
+### Fichiers source - Creators
+
+- [ ] Modifier `src/creators.ts`
+  - [ ] Supprimer import de `FlowGetter` et `FlowWatcher`
+  - [ ] Ajouter import de `TrackingContext`
+  - [ ] Modifier signature de `derivation()` : `(get, watch) => T` → `(t) => T`
+  - [ ] Modifier signature de `effect()` : `(get, watch) => void` → `(t) => void`
+
+### Fichiers source - Solid (Intégration SolidJS)
+
+- [ ] Modifier `src/solid/converters.ts`
+  - [ ] Modifier import : `FlowGetter` → `TrackingContext`
+  - [ ] Modifier fonction `fromSync` : `(get) =>` → `(t) =>` et `state.get()` → `state.pick()`
+  - [ ] Modifier fonction `fromAsync` : `(get) =>` → `(t) =>` et `derivation.get()` → `derivation.pick()`
+  - [ ] Modifier fonction `shallowFrom` : `flow.get()` → `flow.pick()`
+  - [ ] Modifier fonction `deepFrom` : signatures et implémentation avec `TrackingContext`
+  - [ ] Modifier fonction `from` : toutes les signatures `FlowGetter` → `TrackingContext`
+- [ ] Vérifier `src/solid/primitives.ts` (aucune modification nécessaire)
+- [ ] Vérifier `src/solid/index.ts` (aucune modification nécessaire)
+
+### Tests - Basic
+
+- [ ] Migrer tous les tests de `test/state.test.ts`
+- [ ] Migrer tous les tests de `test/effect.test.ts`
+- [ ] Migrer tous les tests de `test/derivation.test.ts`
+- [ ] Migrer tous les tests de `test/signal.test.ts`
+- [ ] Migrer tous les tests de `test/constant.test.ts`
+
+### Tests - Advanced
+
+- [ ] Migrer tous les tests de `test/array.test.ts`
+- [ ] Migrer tous les tests de `test/map.test.ts`
+- [ ] Migrer tous les tests de `test/resource.test.ts`
+- [ ] Migrer tous les tests de `test/resourceAsync.test.ts`
+- [ ] Migrer tous les tests de `test/stream.test.ts`
+- [ ] Migrer tous les tests de `test/streamAsync.test.ts`
+
+### Vérifications
+
+- [ ] Tous les tests passent
+- [ ] Aucune erreur TypeScript
+- [ ] La documentation API est à jour
+- [ ] Exécuter `npm run build` avec succès
+- [ ] Exécuter les linters sans erreurs
+
+---
+
+## Points d'Attention
+
+### 0. Architecture simplifiée - Pas de méthode interne `_watch()`
+
+**Design simplifié** : Dans cette migration, nous supprimons complètement les méthodes internes `_watch()` et `_watchFrom()` qui existaient dans le code original. À la place, nous utilisons des overrides directs de la méthode publique `watch()`.
+
+**Pourquoi FlowDerivation override-t-elle `watch()` ?**
+
+Pour gérer le cas où on track une derivation sans lire sa valeur :
+
+```typescript
+effect((t) => {
+    $myDerivation.watch(t);  // On track la derivation sans lire sa valeur
+    // La derivation DOIT quand même computer pour établir SES dépendances
+});
+```
+
+**Architecture :**
+- `FlowSignal.watch(context)` : Enregistre simplement la dépendance
+- `FlowDerivation.watch(context)` : Override qui appelle `super.watch()` + initialise et compute
+
+Cette approche est plus simple et plus directe que d'utiliser une méthode interne `_watch()` qui serait appelée par `watch()` puis overridée dans les sous-classes.
+
+### 1. Comportement des Effects
+
+**Important** : Le comportement des effects change légèrement. Avant, ils n'étaient "tracked" que lors de la première exécution. Maintenant, ils sont toujours exécutés avec un contexte de tracking, mais c'est à l'utilisateur de décider explicitement quoi tracker avec `.get(t)` vs `.pick()`.
+
+### 2. Lecture non-réactive
+
+La nouvelle API permet explicitement des lectures non-réactives dans les contexts réactifs :
+```typescript
+effect((t) => {
+    const reactive = $state.get(t);     // Crée une dépendance
+    const snapshot = $other.pick();      // Ne crée PAS de dépendance
+});
+```
+
+### 3. Chaînage
+
+Le chaînage devient plus fluide :
+```typescript
+// Avant
+const nested = get(get($parent).child);
+
+// Après
+const nested = $parent.get(t).child.get(t);
+```
+
+### 4. Types TypeScript
+
+Les types `FlowGetter` et `FlowWatcher` sont supprimés. Si du code utilisateur les référence, il faudra les remplacer par `TrackingContext`.
+
+### 5. Classes Advanced
+
+Toutes les classes advanced bénéficient automatiquement de la nouvelle API :
+- `FlowResource`, `FlowResourceAsync` → supportent `get(t)` et `pick()`
+- `FlowArray` → supporte `get(t)` et `pick()` pour l'accès au tableau
+- `FlowStream`, `FlowStreamAsync` → supportent `get(t)` et `pick()`
+- `FlowMap` → pas de changement nécessaire (hérite via FlowState)
+
+Cela offre un contrôle granulaire sur la réactivité dans les structures de données complexes.
+
+### 6. Ordre de Migration
+
+**Ordre recommandé :**
+1. Fichiers `basic/` (fondation)
+2. Fichiers `advanced/` (extensions des basic)
+3. Fichier `creators.ts` (factory functions)
+4. Fichiers `solid/` (intégration SolidJS, dépend de basic)
+5. Tests
+
+Cette séquence assure que chaque couche est migrée avant celle qui en dépend. Les fichiers `solid/` peuvent être migrés en parallèle avec `creators.ts` car ils dépendent tous deux des fichiers `basic/` mais pas l'un de l'autre.
+
+### 7. Intégration SolidJS
+
+Les fichiers `src/solid/` fournissent une intégration avec SolidJS via la fonction `from()`. Cette fonction accepte soit :
+- Un `FlowObservable` directement → converti en SolidDerivation ou SolidResource
+- Une fonction getter avec `TrackingContext` → crée une dérivation PicoFlow puis la convertit
+
+**Important** : Les lectures initiales (pour déterminer sync vs async) utilisent `pick()` car elles ne doivent pas être réactives. Les lectures réactives dans les effects utilisent `get(t)`.
+
+### 8. Compatibilité
+
+Cette migration casse **complètement** l'API publique. C'est un changement majeur de version (v2.0.0).
+
+---
+
+## Commandes de Vérification
+
+Après migration, exécuter ces commandes :
+
+```bash
+# Vérifier les types TypeScript
+npx tsc --noEmit
+
+# Exécuter les tests
+npm test
+
+# Build
+npm run build
+
+# Linter
+npm run lint
+```
+
+---
+
+## Support
+
+Si vous rencontrez des patterns non couverts par ce guide, référez-vous aux principes de base :
+- `get(t)` = lecture réactive
+- `pick()` ou `get(null)` = lecture non-réactive  
+- `watch(t)` = enregistrement de dépendance réactive (signaux uniquement)
+
+**Ces principes s'appliquent à TOUTES les classes** :
+- Classes basic : `FlowSignal`, `FlowConstant`, `FlowState`, `FlowDerivation`
+- Classes advanced : `FlowArray`, `FlowMap`, `FlowResource`, `FlowResourceAsync`, `FlowStream`, `FlowStreamAsync`
+- Effects et derivations : utilisent `TrackingContext` au lieu de `get`/`watch`
+- Intégration Solid : `converters.ts` utilise `TrackingContext` dans `from()` et ses helpers
+
+## Résumé de la Migration
+
+Ce guide couvre la migration complète de PicoFlow vers une API basée sur le contexte de tracking :
+
+✅ **17 fichiers source** modifiés ou créés (1 créé + 16 modifiés)
+✅ **11 fichiers de tests** à migrer  
+✅ **Architecture simplifiée** avec moins de méthodes internes
+✅ **API unifiée** pour toutes les classes (basic, advanced, solid)
+✅ **Contrôle granulaire** de la réactivité avec `get(t)` vs `pick()`
+✅ **Intégration SolidJS** mise à jour pour utiliser TrackingContext
+
+**Détails des fichiers :**
+- 1 nouveau : `trackingContext.ts`
+- 16 modifiés : 7 basic + 5 advanced + 1 creators + 1 solid + 2 index
+- 3 sans modification : `map.ts`, `solid/primitives.ts`, `solid/index.ts`
+
+**Temps estimé :** 2-4 heures pour une migration complète avec tests.
+