@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/src/core/utils/LocationHandler.ts

@@ -115,15 +115,11 @@ export default class LocationHandler {
       return;
     }
     const url = new URL(to, document.location.href);
-    const split = url.pathname.split("/");
-    const newPathName = [];
-    let prevSp = "";
-    for (const sp of split) {
-      if (sp != prevSp) newPathName.push(sp);
-      prevSp = sp;
-    }
-
-    to = "/" + newPathName.join("/") + url.search + (url.hash ? url.hash : "");
+    // Drop empty segments from pathname.split ("/a//b" → /a/b) so we never
+    // emit a protocol-relative `//path`. Public docs URLs are already pretty
+    // (no …/router/router); equal siblings are left untouched if present.
+    const parts = url.pathname.split("/").filter(Boolean);
+    to = `/${parts.join("/")}${url.search}${url.hash || ""}`;
     if (component.hasAttribute("pushState")) {
       history.pushState(null, "", to);
     } else if (component.hasAttribute("replaceState")) {

package/src/core/utils/PublisherProxy.ts

@@ -11,10 +11,39 @@ import type {
 } from "../_types/types";
 import type { DataProviderKey } from "./dataProviderKey";
 import { resolveStaticPublisherPath } from "./dataProviderKey";
+import type { Frozen } from "./deepReadonly";
 import HTML from "./HTML";
+import {
+  deepFreeze,
+  deleteAtKey,
+  setAtKey,
+  stripUndefinedKeys,
+  takeOwnership,
+} from "./immutableValue";
 import Objects from "./Objects";
+import {
+  getStrictGetMode,
+  setStrictGetMode,
+  wrapStrictGet,
+  type StrictGetMode,
+} from "./strictGet";
 import { sonicClassPrefix } from "./Utils";
 
+export type {
+  DeepReadonly,
+  Frozen,
+  FrozenArray,
+  FrozenObject,
+} from "./deepReadonly";
+/** @deprecated Prefer {@link Frozen}. */
+export type ReadonlyDeep<T> = Frozen<T>;
+export type { StrictGetMode } from "./strictGet";
+export {
+  clearStrictGetWarnings,
+  getStrictGetMode,
+  setStrictGetMode,
+} from "./strictGet";
+
 export type Observable = string;
 
 type DynamicFillingListener = any;
@@ -85,7 +114,7 @@ export class PublisherProxy<T = any> {
   _invalidate_on_page_show_ = false;
   _invalidateListeners_ = new Set<VoidFunction>();
   _formInvalidateListeners_ = new Set<VoidFunction>();
-  _assignListeners_ = new Set<(value: T) => void>();
+  _assignListeners_ = new Set<(value: Frozen<T>) => void>();
   _mutationListeners_ = new Set<VoidFunction>();
   _fillListeners_ = new Set<Record<string, CoreJSType>>();
   _templateFillListeners_ = new Set<TemplateFillingListener>();
@@ -100,7 +129,8 @@ export class PublisherProxy<T = any> {
     parentProxPub: PublisherProxy | null,
     parentKey?: string,
   ) {
-    this._value_ = target;
+    // Child publishers often receive an already-owned (frozen) subtree from the parent.
+    this._value_ = takeOwnership(target) as T;
     this.parent = parentProxPub || null;
     this._parentKey_ = parentKey;
     this.root = this;
@@ -165,7 +195,7 @@ export class PublisherProxy<T = any> {
     if (currentId !== this._assignmentId_) return;
     const newValue = this.get();
 
-    this._assignListeners_.forEach((handler: (value: T) => void) => {
+    this._assignListeners_.forEach((handler) => {
       handler(newValue);
     });
     this._publishInternalMutation_(lockInternalMutationsTransmission);
@@ -206,7 +236,10 @@ export class PublisherProxy<T = any> {
    * Appel la fonction "handler" (passée en paramettre) lorsque la valeur gérée par le proxy change par assignation
    * hanlder reçois alors la nouvelle valeur interne du proxy en paramètre
    */
-  onAssign(handler: (value: T) => void, directHandlerCall = true) {
+  onAssign(
+    handler: (value: Frozen<T>) => void,
+    directHandlerCall = true,
+  ) {
     if (typeof handler != "function") return;
     if (this._assignListeners_.has(handler)) return;
     this._assignListeners_.add(handler);
@@ -215,7 +248,7 @@ export class PublisherProxy<T = any> {
   /**
    * Stop les appels de la fonction "handler" (passée en paramettre) lorsque la valeur gérée par le proxy change par assignation
    */
-  offAssign(handler: (value: T) => void) {
+  offAssign(handler: (value: Frozen<T>) => void) {
     this._assignListeners_.delete(handler);
   }
 
@@ -320,84 +353,54 @@ export class PublisherProxy<T = any> {
     this._fillListeners_.delete(handler);
   }
   /**
-   * Assigne une nouvelle valeur au proxy ce qui déclenche la transmission de la donnée en fonction des "écouteurs" associés
+   * Assigne une nouvelle valeur : ownership (clone) + freeze, puis publication.
+   * @param alreadyOwned si true, `newValue` est déjà une valeur du store (frozen) — pas de re-clone.
    */
+  set(
+    newValue: T | Frozen<T>,
+    lockInternalMutationsTransmission = false,
+    alreadyOwned = false,
+  ) {
+    const normalized = (
+      isComplex(newValue) ? newValue : { __value: newValue }
+    ) as T;
+    const prepared = stripUndefinedKeys(normalized);
+    // alreadyOwned: freeze without re-clone (subtree from parent or fresh __value wrapper).
+    const owned = (
+      alreadyOwned ? deepFreeze(prepared) : takeOwnership(prepared)
+    ) as T;
 
-  set(newValue: T, lockInternalMutationsTransmission = false) {
-    /**
-     * On retounre tout de suite si la valeur n'a pas changé
-     */
-
-    if (this._value_ === newValue) return true;
+    if (this._value_ === owned) return true;
 
-    /**
-     * On retounre tout de suite si la valeur n'a pas changé
-     * et qu'elle est primitive
-     */
     if (
       (isComplex(this._value_) &&
-        isComplex(newValue) &&
-        newValue &&
+        isComplex(owned) &&
+        owned &&
         isLeaf(this._value_) &&
-        isLeaf(newValue) &&
-        (this._value_ as any).__value === (newValue as any).__value) ||
+        isLeaf(owned) &&
+        (this._value_ as any).__value === (owned as any).__value) ||
       (!isComplex(newValue) && newValue === (this._value_ as any).__value)
     ) {
       return true;
     }
 
-    /**
-     * On assigne la nouvelle valeur
-     */
-
-    /** Si la valeur est complexe on assigne newValue directe sinon on le met dans une sous valeur __value */
-    this._value_ = isComplex(newValue)
-      ? newValue
-      : ({ __value: newValue } as any);
+    this._value_ = owned;
     this._cachedGet_ = undefined;
 
-    /**
-     * Si il s'agit d'une valeur primitive (un entier, une chaine ) la valeure en renseignée par un objet contenant la vaeur {__value}
-     * On publie juste et on sen va.
-     */
     const isLeafNewValue = isLeaf(this._value_);
 
-    if (this._parentKey_ && this.parent) {
-      //si le parent n'a pas de valeur, on la crée en renseignant this.value et on retourne.
-      const valueTosetInParent = isLeaf(this._value_)
-        ? (this._value_ as any).__value
-        : this._value_;
-      if (this.parent?.get() == null && this.parent?.get() == undefined) {
-        //if _parentKey_ is a number, we assume it's an array
-        if (!isNaN(Number(this._parentKey_))) {
-          const parent = [];
-          parent[Number(this._parentKey_)] = valueTosetInParent;
-          this.parent.set(parent);
-        } else {
-          this.parent.set({ [this._parentKey_]: valueTosetInParent });
-        }
-        // return;
-      } else {
-        //on mets à jour la valeur de la clef dans l'objet parnet pour refléter le changement au ca sou elle n'existait pas
-        this.parent._value_[this._parentKey_] = valueTosetInParent;
-      }
+    if (this._parentKey_ && this.parent && !lockInternalMutationsTransmission) {
+      this._syncOwnedValueIntoParent_(lockInternalMutationsTransmission);
     }
 
     if (isLeafNewValue) {
-      // Si la valeur précédente était composite, on reset tous les sous-éléments à null
       this._proxies_.forEach((_subProxy, key) => {
-        /**
-         *
-         * On reùmplace les undefined par des nuls pour eviter la suppression des clefs sauf pour les clef  tableaux
-         **/
-
         if (key != "_parent_") {
-          _subProxy.set(null);
+          _subProxy.set(null, true, true);
           this._publishDynamicFilling_(key, null);
         }
       });
 
-      //await  //await here gives better performance but can cause issues with some listeners
       this._publishAssignement_(lockInternalMutationsTransmission);
       if (this.parent && this._parentKey_) {
         this.parent._publishDynamicFilling_(
@@ -408,23 +411,8 @@ export class PublisherProxy<T = any> {
 
       return true;
     }
-    /**
-     * On fait la diff sur l'existant.
-     * On maintient les proxys à supprimer et ceux à ajouter.
-     * On met à jour leur valeur interne
-     * On publie les maj au fur et a mesure de modifications
-     */
-
-    for (const key in this._value_) {
-      const currentValue = this._value_[key] as any;
-      if (currentValue === undefined) delete this._value_[key];
-    }
 
     this._proxies_.forEach((_subProxy, key) => {
-      /**
-       *
-       * On reùmplace les undefined par des nuls pour eviter la suppression des clefs sauf pour les clef  tableaux
-       **/
       const currentValue: any = (this._value_ as any)[key];
 
       if (key != "_parent_") {
@@ -433,63 +421,99 @@ export class PublisherProxy<T = any> {
           currentValue !== null &&
           isNaN(Number(key))
         ) {
-          _subProxy.set(null);
+          _subProxy.set(null, true, true);
           this._publishDynamicFilling_(key, null);
         }
       }
     });
 
-    /**
-     * On prévient les écouteurs que la valeur a changé
-     */
-    //await  //await here gives better performance but can cause issues with some listeners
-    this._publishAssignement_();
+    this._publishAssignement_(lockInternalMutationsTransmission);
     if (this.parent && this._parentKey_)
       this.parent._publishDynamicFilling_(
         this._parentKey_,
         this._value_ as any,
       );
-    /**
-     * Si la donnée est complexe (objet, tableau)
-     * on crée les proxys pour les sous-éléments qui n'en on pas
-     * On renseigne les nouvelles valeurs internes des proxies
-     */
 
     if (isComplex(this._value_)) {
       for (const key in this._value_) {
-        const v = newValue[key] as any;
+        const v = (this._value_ as any)[key];
         const isVComplex = isComplex(v);
         const valueV = isVComplex ? v : { __value: v };
         if (!this._proxies_.has(key)) {
-          // A surveiller ancienne version
-          // const newPublisher = new DataProvider({}, this);
-          // this._proxies_.set(key, newPublisher);
-          // newPublisher._proxies_.set("_parent_", this);
-
           this._publishDynamicFilling_(key, v);
           continue;
         }
-        //await //await here gives better performance but can cause issues with some listeners
-        this._proxies_.get(key)?.set(valueV, true);
+        // Child already holds an owned subtree — do not sync back to parent.
+        this._proxies_.get(key)?.set(valueV as any, true, true);
         this._publishDynamicFilling_(key, v);
       }
     }
     return true;
   }
+
+  /** Rebuild parent immutably so this node's owned value is reflected at `_parentKey_`. */
+  _syncOwnedValueIntoParent_(lockInternalMutationsTransmission = false) {
+    if (!this.parent || this._parentKey_ == null) return;
+    const valueTosetInParent = isLeaf(this._value_)
+      ? (this._value_ as any).__value
+      : this._value_;
+    const parentRaw = this.parent._value_;
+    const parentEmpty =
+      parentRaw == null ||
+      parentRaw === undefined ||
+      (isLeaf(parentRaw) && (parentRaw as any).__value == null);
+
+    if (parentEmpty) {
+      if (!isNaN(Number(this._parentKey_))) {
+        const parent: any[] = [];
+        parent[Number(this._parentKey_)] = valueTosetInParent;
+        this.parent.set(parent as any, lockInternalMutationsTransmission);
+      } else {
+        this.parent.set(
+          { [this._parentKey_]: valueTosetInParent } as any,
+          lockInternalMutationsTransmission,
+        );
+      }
+      return;
+    }
+
+    // Already reflected on parent (same ref) — skip rebuild/publish (avoids list render loops).
+    const currentAtKey = (parentRaw as any)[this._parentKey_];
+    if (currentAtKey === valueTosetInParent) return;
+
+    const nextParent = setAtKey(
+      parentRaw as object,
+      this._parentKey_,
+      valueTosetInParent,
+    );
+    this.parent.set(
+      nextParent as any,
+      lockInternalMutationsTransmission,
+      true,
+    );
+  }
   /**
    * Extraire la valeur actuelle du proxy
    */
   _cachedGet_?: T;
-  get(): T {
+  /**
+   * Lecture typée {@link Frozen}. Runtime = valeur **owned / frozen** du store
+   * (même ref entre deux `set`). `strictGet` reste un radar optionnel sur le wrap.
+   */
+  get(): Frozen<T> {
     trackModifiedPublisher(this);
-    if (this._cachedGet_ !== undefined) return this._cachedGet_;
-    if (Object.prototype.hasOwnProperty.call(this._value_, "__value")) {
+    let raw: T;
+    if (this._cachedGet_ !== undefined) {
+      raw = this._cachedGet_;
+    } else if (Object.prototype.hasOwnProperty.call(this._value_, "__value")) {
       const v = (this._value_ as any).__value;
-      return (this._cachedGet_ = (v != undefined ? v : null) as T);
+      raw = this._cachedGet_ = (v != undefined ? v : null) as T;
+    } else {
+      raw = this._cachedGet_ = (
+        this._value_ != undefined ? this._value_ : null
+      ) as T;
     }
-    return (this._cachedGet_ = (
-      this._value_ != undefined ? this._value_ : null
-    ) as T);
+    return wrapStrictGet(raw) as Frozen<T>;
   }
   /**
    * retourner le webcomponent auquel le proxy est associé
@@ -539,6 +563,17 @@ export class PublisherManager {
   static saveId = 0;
   static instance: PublisherManager | null = null;
   static instances: Map<string, PublisherManager> = new Map();
+  /**
+   * Runtime guard on `get()` results: `off` | `warn` | `throw`.
+   * Default `off`. Enable in local/CI to detect in-place mutations after get().
+   * @see wrapStrictGet
+   */
+  static get strictGet(): StrictGetMode {
+    return getStrictGetMode();
+  }
+  static set strictGet(mode: StrictGetMode) {
+    setStrictGetMode(mode);
+  }
   enabledLocaStorageProxies: string[] = [];
   publishers = new Map<string, PublisherInterface>();
   localStorageData: Record<
@@ -825,6 +860,7 @@ const internalProps: Set<string> = new Set([
   "_publishFormInvalidation_",
   "_publishTemplateFilling_",
   "_publishAssignement_",
+  "_syncOwnedValueIntoParent_",
   "_proxies_",
   "parent",
   "_parentKey_",
@@ -943,19 +979,17 @@ function createPublisherHandler<T = any>(
         newPublisher._proxies_.set("_parent_", getProxy());
         publisherInstance._proxies_.set(sKey, newPublisher);
       }
-      //mis à jour et publication de la donnée si elle a changé
 
-      const prevValue = (publisherInstance._value_ as any)[sKey];
+      const prevValue = (publisherInstance._value_ as any)?.[sKey];
 
       if (prevValue !== vValue) {
-        (publisherInstance._value_ as any)[sKey] = vValue;
-        publisherInstance._publishDynamicFilling_(sKey, vValue);
-        publisherInstance._proxies_
-          .get(sKey)
-          ?.set(isComplex(vValue) ? vValue : { __value: vValue });
+        const childStorage = isComplex(vValue)
+          ? vValue
+          : ({ __value: vValue } as any);
+        // Child commits owned value and syncs parent immutably (no in-place _value_ patch).
+        publisherInstance._proxies_.get(sKey)?.set(childStorage as any);
+        publisherInstance._publishDynamicFilling_(sKey, vValue as any);
       }
-      //on retourne  le proxy pour pouvoir chainer les assignements
-      // return publisherInstance._proxies_.get(sKey);
       return true;
     },
     /**
@@ -963,12 +997,17 @@ function createPublisherHandler<T = any>(
      */
     deleteProperty: function (_publisherInstance, sKey: string) {
       publisherInstance._publishDynamicFilling_(sKey, null);
-      // if (!publisherInstance._proxies_.get(sKey)?.hasListener()) {
-      //   publisherInstance._proxies_.delete(sKey);
-      // } else {
-      publisherInstance._proxies_.get(sKey)?.set(null);
-      // }
-      return delete (publisherInstance._value_ as any)[sKey];
+      // Clear child without syncing; parent rebuild drops the key immutably.
+      publisherInstance._proxies_.get(sKey)?.set(null, true, true);
+      if (
+        publisherInstance._value_ != null &&
+        typeof publisherInstance._value_ === "object" &&
+        !isLeaf(publisherInstance._value_)
+      ) {
+        const next = deleteAtKey(publisherInstance._value_ as object, sKey);
+        publisherInstance.set(next as any, false, true);
+      }
+      return true;
     },
     // enumerate: function (publisherInstance, sKey): CoreJSType {
     //   return publisherInstance._value_.keys();
@@ -981,10 +1020,9 @@ function createPublisherHandler<T = any>(
     },
     defineProperty: function (_publisherInstance, sKey, oDesc) {
       if (oDesc && "value" in oDesc) {
-        (publisherInstance._value_ as any)[sKey] = oDesc.value;
+        (getProxy() as any)[sKey] = oDesc.value;
       }
       return true;
-      // return publisherInstance._value_;
     },
     getOwnPropertyDescriptor: function (_publisherInstance, sKey) {
       sKey;
@@ -1076,12 +1114,12 @@ export const getObservables = <T = any>(
   return new Set<DataProvider<T>>([observable as DataProvider<T>]);
 };
 
-// get value (snapshot at call time)
-export function get<T>(id: DataProviderKey<T>): T;
-export function get<T = any>(id: string): T;
-export function get<T>(id: string | DataProviderKey<T>): T {
+// get value (typed Frozen — owned frozen store ref; see get() JSDoc)
+export function get<T>(id: DataProviderKey<T>): Frozen<T>;
+export function get<T = any>(id: string): Frozen<T>;
+export function get<T>(id: string | DataProviderKey<T>): Frozen<T> {
   const path = resolveStaticPublisherPath(id);
-  return getObservables<T>(path).values().next().value?.get() as T;
+  return getObservables<T>(path).values().next().value?.get() as Frozen<T>;
 }
 
 function deepee<T>(
@@ -1177,9 +1215,12 @@ export function mirrorDp(
   );
 }
 
-export function set<T>(id: DataProviderKey<T>, value: T): void;
-export function set<T = any>(id: string, value: T): void;
-export function set<T>(id: string | DataProviderKey<T>, value: T): void {
+export function set<T>(id: DataProviderKey<T>, value: T | Frozen<T>): void;
+export function set<T = any>(id: string, value: T | Frozen<T>): void;
+export function set<T>(
+  id: string | DataProviderKey<T>,
+  value: T | Frozen<T>,
+): void {
   const path = resolveStaticPublisherPath(id);
   getObservables(path).values().next().value?.set(value);
 }

package/src/core/utils/deepReadonly.spec.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, expectTypeOf } from "vitest";
+import { DataProviderKey } from "./dataProviderKey";
+import type { Frozen, FrozenArray } from "./deepReadonly";
+import { dp, get, set } from "./PublisherProxy";
+
+type Cart = { items: { id: number; qty: number }[]; total: number };
+type City = { nom: string; code: string };
+
+describe("Frozen get() (79567)", () => {
+  const cartKey = new DataProviderKey<Cart>("deepReadonlySpecCart");
+
+  it("runtime: get() returns the owned frozen store ref", () => {
+    const initial: Cart = { items: [{ id: 1, qty: 1 }], total: 1 };
+    set(cartKey, initial);
+    const snapshot = get(cartKey);
+    expect(snapshot).toBe(dp(cartKey).get());
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(() => {
+      (snapshot as Cart).total = 99;
+    }).toThrow();
+    expect(get(cartKey).total).toBe(1);
+  });
+
+  it("types: array is FrozenArray and index is Frozen element", () => {
+    type Arr = Frozen<City[]>;
+    expectTypeOf<Arr>().toMatchTypeOf<FrozenArray<City>>();
+    type Elem = Arr[0];
+    expectTypeOf<Elem>().toEqualTypeOf<Frozen<City>>();
+  });
+
+  it("types: get() is Frozen when the key is typed", () => {
+    set(cartKey, { items: [{ id: 1, qty: 1 }], total: 1 });
+    const cart = get(cartKey);
+    expectTypeOf(cart).toEqualTypeOf<Frozen<Cart>>();
+    expectTypeOf(cart.items).toMatchTypeOf<FrozenArray<{ id: number; qty: number }>>();
+    expect(cart.total).toBeTypeOf("number");
+  });
+
+  it("types: keyof FrozenObject keeps domain keys (IDE completions)", () => {
+    type Payload = { request: Request; response?: Response; result: City[] };
+    type Keys = keyof Frozen<Payload>;
+    expectTypeOf<Keys>().toEqualTypeOf<"request" | "response" | "result">();
+    type R = Frozen<Payload>["result"];
+    expectTypeOf<R>().toEqualTypeOf<FrozenArray<City>>();
+  });
+
+  it("types: nested mutation is rejected", () => {
+    set(cartKey, { items: [{ id: 1, qty: 1 }], total: 1 });
+    const cart = get(cartKey);
+    if (false as boolean) {
+      // @ts-expect-error Frozen blocks push on items
+      cart.items.push({ id: 2, qty: 1 });
+      // @ts-expect-error Frozen blocks property write
+      cart.total = 0;
+      // @ts-expect-error Frozen blocks nested write
+      cart.items[0].qty = 3;
+    }
+    expect(cart.items).toHaveLength(1);
+  });
+
+  it("set accepts get() snapshot without cast", () => {
+    set(cartKey, { items: [], total: 0 });
+    set(cartKey, get(cartKey));
+    expect(get(cartKey).total).toBe(0);
+  });
+});

package/src/core/utils/deepReadonly.ts

@@ -0,0 +1,71 @@
+/**
+ * Valeur du DataProvider en lecture seule (runtime = frozen).
+ *
+ * Nom public : `Frozen<T>`.
+ * - Tableaux → interface `FrozenArray<V>` (hover nommé + autocomplétion OK).
+ * - Objets → alias mappé `FrozenObject<T>` (l’interface `extends` un mapped
+ *   générique est illégale / TS2312 → props perdues, `test.` vide).
+ * - Built-ins DOM/host (`Request`, `Response`, `Date`, …) : opaque, non retraversés
+ *   (sinon language service noyé, ex. `ApiResult`).
+ */
+
+/** Types host / builtin : shallow (pas de deep Frozen). */
+type FrozenLeaf =
+  | Date
+  | RegExp
+  | Error
+  | ArrayBuffer
+  | SharedArrayBuffer
+  | DataView
+  | Promise<unknown>
+  | WeakMap<object, unknown>
+  | WeakSet<object>
+  | Request
+  | Response
+  | Headers
+  | FormData
+  | Blob
+  | File
+  | URL
+  | URLSearchParams
+  | AbortSignal
+  | AbortController
+  | ReadableStream<unknown>
+  | WritableStream<unknown>
+  | TransformStream<unknown, unknown>;
+
+/**
+ * Objet frozen — mapped alias (seul pattern compatible autocomplétion).
+ * Hover peut déplier les champs ; le paramètre `T` reste le type maître.
+ */
+export type FrozenObject<T> = {
+  readonly [K in keyof T]: Frozen<T[K]>;
+};
+
+/**
+ * Tableau frozen nommé — hover = `FrozenArray<V>` ; `arr[0]` = `Frozen<V>`.
+ */
+export interface FrozenArray<T> extends ReadonlyArray<Frozen<T>> {}
+
+export type Frozen<T> = 0 extends 1 & T
+  ? T
+  : unknown extends T
+    ? T
+    : T extends string | number | boolean | bigint | symbol | null | undefined
+      ? T
+      : T extends (...args: never[]) => unknown
+        ? T
+        : T extends FrozenLeaf
+          ? T
+          : T extends ReadonlyMap<infer K, infer V>
+            ? ReadonlyMap<Frozen<K>, Frozen<V>>
+            : T extends ReadonlySet<infer V>
+              ? ReadonlySet<Frozen<V>>
+              : T extends readonly (infer V)[]
+                ? FrozenArray<V>
+                : T extends object
+                  ? FrozenObject<T>
+                  : T;
+
+/** @deprecated Prefer {@link Frozen} — même type, nom plus long. */
+export type DeepReadonly<T> = Frozen<T>;

package/src/core/utils/immutableValue.spec.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  deepFreeze,
+  deleteAtKey,
+  setAtKey,
+  takeOwnership,
+} from "./immutableValue";
+
+describe("immutableValue helpers", () => {
+  it("takeOwnership clones so external mutation does not affect owned value", () => {
+    const external = { a: 1, nested: { b: 2 } };
+    const owned = takeOwnership(external);
+    external.a = 9;
+    external.nested.b = 9;
+    expect(owned.a).toBe(1);
+    expect(owned.nested.b).toBe(2);
+    expect(Object.isFrozen(owned)).toBe(true);
+    expect(Object.isFrozen(owned.nested)).toBe(true);
+  });
+
+  it("takeOwnership is idempotent on frozen values", () => {
+    const once = takeOwnership({ x: 1 });
+    expect(takeOwnership(once)).toBe(once);
+  });
+
+  it("deepFreeze blocks assignment", () => {
+    const v = deepFreeze({ n: 1 });
+    expect(() => {
+      (v as { n: number }).n = 2;
+    }).toThrow();
+  });
+
+  it("setAtKey / deleteAtKey rebuild without mutating root", () => {
+    const root = takeOwnership({ a: 1, b: 2 });
+    const next = setAtKey(root, "b", 3);
+    expect(root.b).toBe(2);
+    expect(next.b).toBe(3);
+    expect(Object.isFrozen(next)).toBe(true);
+    const dropped = deleteAtKey(next, "a");
+    expect("a" in dropped).toBe(false);
+    expect(next.a).toBe(1);
+  });
+
+  it("unclonable values warn and pass through", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const fn = () => 1;
+    const obj = { fn };
+    // functions inside plain objects: structuredClone throws in many engines
+    const owned = takeOwnership(obj);
+    expect(owned).toBe(obj);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});