update deepsignals readme

sdk/js/alien-deepsignals/README.md

@@ -13,7 +13,8 @@ Core idea: wrap a data tree in a `Proxy` that lazily creates per-property signal
 - Patch stream: microtask‑batched granular mutations (paths + op) for syncing external stores / framework adapters.
 - Getter => computed: property getters become derived (readonly) signals automatically.
 - `$` accessors: TypeScript exposes `$prop` for each non‑function key plus `$` / `$length` for arrays.
-- Sets: structural `add/delete/clear` emit patches; object entries get synthetic stable ids (prefers `id` / `@id` fields or auto‑generated blank IDs).
+- Sets: structural `add/delete/clear` emit patches; object entries get synthetic stable ids via `@id` property.
+- `@id` property system: configurable automatic ID assignment to objects with custom generators.
 - Shallow escape hatch: wrap sub-objects with `shallow(obj)` to track only reference replacement.
 
 ## Install
@@ -46,6 +47,68 @@ state.$count!.set(5); // update via signal
 console.log(state.$count!()); // read via signal function
 ```
 
+## Configuration options
+
+`deepSignal(obj, options?)` accepts an optional configuration object:
+
+```ts
+type DeepSignalOptions = {
+    idGenerator?: () => string | number; // Custom ID generator function
+    addIdToObjects?: boolean; // Automatically add @id to plain objects
+};
+```
+
+### Custom ID generation
+
+Provide a custom function to generate synthetic IDs instead of auto-generated blank node IDs:
+
+```ts
+let counter = 0;
+const state = deepSignal(
+    { items: new Set() },
+    { 
+        idGenerator: () => `urn:item:${++counter}`,
+        addIdToObjects: true 
+    }
+);
+
+state.items.add({ name: "Item 1" }); // Gets @id: "urn:item:1"
+state.items.add({ name: "Item 2" }); // Gets @id: "urn:item:2"
+```
+
+### The `@id` property
+
+When `addIdToObjects: true`, plain objects automatically receive a readonly, enumerable `@id` property:
+
+```ts
+const state = deepSignal(
+    { data: {} },
+    { 
+        idGenerator: () => `urn:uuid:${crypto.randomUUID()}`,
+        addIdToObjects: true 
+    }
+);
+
+state.data.user = { name: "Ada" };
+console.log(state.data.user["@id"]); // e.g., "urn:uuid:550e8400-e29b-41d4-a716-446655440000"
+
+// @id is readonly
+state.data.user["@id"] = "new-id"; // TypeError in strict mode
+
+// @id assignment emits a patch
+watch(state, ({ patches }) => {
+    // patches includes: { op: "add", path: ["data", "user", "@id"], value: "..." }
+});
+```
+
+**Key behaviors:**
+
+- `@id` is assigned **before** the object is proxied, ensuring it's available immediately
+- `@id` properties are **readonly** and **enumerable**
+- Assigning `@id` emits a patch just like any other property
+- Objects with existing `@id` properties keep their values (not overwritten)
+- Options propagate to nested objects created after initialization
+
 ## Watching patches
 
 `watch(root, cb, options?)` observes a deepSignal root and invokes your callback with microtask‑batched mutation patches plus snapshots.
@@ -113,23 +176,103 @@ Notes:
 
 ## Sets & synthetic ids
 
-Object entries inside Sets need a stable key. Priority:
+Object entries inside Sets need a stable key for patch paths. The synthetic ID resolution follows this priority:
 
-1. `entry.id`
+1. Explicit custom ID via `setSetEntrySyntheticId(entry, 'myId')` (before `add`)
-2. `entry['@id']`
+2. Existing `entry['@id']` property
-3. Custom via `setSetEntrySyntheticId(entry, 'myId')` before `add`
+3. Auto-generated blank node ID (`_bN` format)
-4. Auto `_bN` blank id
 
-Helpers:
+### Working with Sets
 
 ```ts
-import { addWithId, setSetEntrySyntheticId } from "alien-deepsignals";
+import { addWithId, setSetEntrySyntheticId } from "@ng-org/alien-deepsignals";
+
+// Option 1: Use @id from configuration
+const state = deepSignal(
+    { items: new Set() },
+    { 
+        idGenerator: () => `urn:uuid:${crypto.randomUUID()}`,
+        addIdToObjects: true 
+    }
+);
+const item = { name: "Item 1" };
+state.items.add(item); // Automatically gets @id before being added
+console.log(item["@id"]); // e.g., "urn:uuid:550e8400-..."
+
+// Option 2: Manually set synthetic ID
+const obj = { value: 42 };
+setSetEntrySyntheticId(obj, "urn:custom:my-id");
+state.items.add(obj);
+
+// Option 3: Use convenience helper
+addWithId(state.items as any, { value: 99 }, "urn:item:special");
+
+// Option 4: Pre-assign @id property
+const preTagged = { "@id": "urn:explicit:123", data: "..." };
+state.items.add(preTagged); // Uses "urn:explicit:123" as synthetic ID
+```
+
+### Set entry patches and paths
+
+When objects are added to Sets, their **synthetic ID becomes part of the patch path**. This allows patches to uniquely identify which Set entry is being mutated.
+
+```ts
+const state = deepSignal(
+    { s: new Set() }, 
+    { 
+        idGenerator: () => "urn:entry:set-entry-1",
+        addIdToObjects: true 
+    }
+);
+
+watch(state, ({ patches }) => {
+    console.log(JSON.stringify(patches));
+    // [
+    //   {"path":["s","urn:entry:set-entry-1"],"op":"add","type":"object"},
+    //   {"path":["s","urn:entry:set-entry-1","@id"],"op":"add","value":"urn:entry:set-entry-1"},
+    //   {"path":["s","urn:entry:set-entry-1","data"],"op":"add","value":"test"}
+    // ]
+});
 
-setSetEntrySyntheticId(obj, "custom");
+state.s.add({ data: "test" });
-state.settings.add(obj);
-addWithId(state.settings as any, { x: 1 }, "x1");
 ```
 
+**Path structure explained:**
+
+- `["s", "urn:entry:set-entry-1"]` - The structural Set patch; the IRI identifies the entry
+- `["s", "urn:entry:set-entry-1", "@id"]` - Patch for the @id property assignment
+- `["s", "urn:entry:set-entry-1", "data"]` - Nested property patch; the IRI identifies which Set entry
+- The synthetic ID (the IRI) is stable across mutations, allowing tracking of the same object
+
+**Mutating nested properties:**
+
+```ts
+const state = deepSignal(
+    { users: new Set() }, 
+    { 
+        idGenerator: () => `urn:user:${crypto.randomUUID()}`,
+        addIdToObjects: true 
+    }
+);
+const user = { name: "Ada", age: 30 };
+state.users.add(user); // Gets @id, e.g., "urn:user:550e8400-..."
+
+watch(state, ({ patches }) => {
+    console.log(JSON.stringify(patches));
+    // [{"path":["users","urn:user:550e8400-...","age"],"op":"add","value":31}]
+});
+
+// Later mutation: synthetic ID identifies which Set entry changed
+user.age = 31;
+```
+
+The path `["users", "urn:user:550e8400-...", "age"]` shows:
+1. `users` - the Set container
+2. `urn:user:550e8400-...` - the IRI identifying which object in the Set
+3. `age` - the property being mutated
+
+This structure enables precise tracking of nested changes within Set entries, critical for syncing state changes or implementing undo/redo.
+
 ## Shallow
 
 Skip deep proxying of a subtree (only reference replacement tracked):
@@ -152,18 +295,18 @@ const n: number = state.$count!(); // typed number
 
 ## API surface
 
-| Function                           | Description                             |
+| Function                           | Description                                       |
-| ---------------------------------- | --------------------------------------- |
+| ---------------------------------- | ------------------------------------------------- |
-| `deepSignal(obj)`                  | Create (or reuse) reactive deep proxy.  |
+| `deepSignal(obj, options?)`        | Create (or reuse) reactive deep proxy with optional configuration. |
-| `watch(root, cb, opts?)`           | Observe batched deep mutations.         |
+| `watch(root, cb, opts?)`           | Observe batched deep mutations.                   |
-| `observe(root, cb, opts?)`         | Alias of `watch`.                       |
+| `observe(root, cb, opts?)`         | Alias of `watch`.                                 |
-| `peek(obj,key)`                    | Untracked property read.                |
+| `peek(obj,key)`                    | Untracked property read.                          |
-| `shallow(obj)`                     | Mark object to skip deep proxying.      |
+| `shallow(obj)`                     | Mark object to skip deep proxying.                |
-| `isDeepSignal(val)`                | Runtime predicate.                      |
+| `isDeepSignal(val)`                | Runtime predicate.                                |
-| `isShallow(val)`                   | Was value marked shallow.               |
+| `isShallow(val)`                   | Was value marked shallow.                         |
-| `setSetEntrySyntheticId(obj,id)`   | Assign custom Set entry id.             |
+| `setSetEntrySyntheticId(obj,id)`   | Assign custom Set entry id (highest priority).    |
-| `addWithId(set, entry, id)`        | Insert with desired synthetic id.       |
+| `addWithId(set, entry, id)`        | Insert with desired synthetic id (convenience).   |
-| `subscribeDeepMutations(root, cb)` | Low-level patch stream (used by watch). |
+| `subscribeDeepMutations(root, cb)` | Low-level patch stream (used by watch).           |
 
 ## Credits
 

sdk/js/alien-deepsignals/src/deepSignal.ts

@@ -56,6 +56,14 @@ export interface DeepLiteralAddPatch {
 /** Callback signature for subscribeDeepMutations. */
 export type DeepPatchSubscriber = (patches: DeepPatch[]) => void;
 
+/** Options for configuring deepSignal behavior. */
+export interface DeepSignalOptions {
+    /** Custom function to generate synthetic IDs for objects without @id. */
+    idGenerator?: () => string | number;
+    /** If true, add @id property to all objects in the tree. */
+    addIdToObjects?: boolean;
+}
+
 /** Minimal per-proxy metadata for path reconstruction. */
 interface ProxyMeta {
     /** Parent proxy in the object graph (undefined for root). */
@@ -64,10 +72,14 @@ interface ProxyMeta {
     key?: string | number;
     /** Stable root id symbol shared by the entire deepSignal tree. */
     root: symbol;
+    /** Options inherited from root. */
+    options?: DeepSignalOptions;
 }
 
 // Proxy -> metadata
 const proxyMeta = new WeakMap<object, ProxyMeta>();
+// Root symbol -> options
+const rootOptions = new Map<symbol, DeepSignalOptions>();
 // Root symbol -> subscribers
 const mutationSubscribers = new Map<symbol, Set<DeepPatchSubscriber>>();
 // Pending patches grouped per root (flushed once per microtask)
@@ -122,7 +134,8 @@ function queuePatch(patch: DeepPatch) {
 function queueDeepPatches(
     val: any,
     rootId: symbol,
-    basePath: (string | number)[]
+    basePath: (string | number)[],
+    options?: DeepSignalOptions
 ) {
     if (!val || typeof val !== "object") {
         // Emit patch for primitive leaf
@@ -135,6 +148,28 @@ function queueDeepPatches(
         return;
     }
 
+    // Add @id to object if options specify it
+    if (
+        options?.addIdToObjects &&
+        val.constructor === Object &&
+        !("@id" in val)
+    ) {
+        let syntheticId: string | number;
+        if (options.idGenerator) {
+            syntheticId = options.idGenerator();
+        } else {
+            syntheticId = assignBlankNodeId(val);
+        }
+
+        // Define @id on the raw object before proxying
+        Object.defineProperty(val, "@id", {
+            value: syntheticId,
+            writable: false,
+            enumerable: true,
+            configurable: false,
+        });
+    }
+
     // Emit patch for the object/array/Set itself
     queuePatch({
         root: rootId,
@@ -143,20 +178,33 @@ function queueDeepPatches(
         type: "object",
     });
 
+    // Emit patch for @id if it exists
+    if ("@id" in val) {
+        queuePatch({
+            root: rootId,
+            path: [...basePath, "@id"],
+            op: "add",
+            value: (val as any)["@id"],
+        });
+    }
+
     // Recursively process nested properties
     if (Array.isArray(val)) {
         for (let i = 0; i < val.length; i++) {
-            queueDeepPatches(val[i], rootId, [...basePath, i]);
+            queueDeepPatches(val[i], rootId, [...basePath, i], options);
         }
     } else if (val instanceof Set) {
         for (const entry of val) {
             const key = getSetEntryKey(entry);
-            queueDeepPatches(entry, rootId, [...basePath, key]);
+            queueDeepPatches(entry, rootId, [...basePath, key], options);
         }
     } else if (val.constructor === Object) {
         for (const key in val) {
-            if (Object.prototype.hasOwnProperty.call(val, key)) {
+            if (
-                queueDeepPatches(val[key], rootId, [...basePath, key]);
+                Object.prototype.hasOwnProperty.call(val, key) &&
+                key !== "@id"
+            ) {
+                queueDeepPatches(val[key], rootId, [...basePath, key], options);
             }
         }
     }
@@ -319,17 +367,21 @@ export function setSetEntrySyntheticId(obj: object, id: string | number) {
 }
 const getSetEntryKey = (val: any): string | number => {
     if (val && typeof val === "object") {
+        // First check for explicitly assigned synthetic ID
         if (setObjectIds.has(val)) return setObjectIds.get(val)!;
-        if (
+        // Then check for @id property (primary identifier)
-            typeof (val as any).id === "string" ||
-            typeof (val as any).id === "number"
-        )
-            return (val as any).id;
         if (
             typeof (val as any)["@id"] === "string" ||
             typeof (val as any)["@id"] === "number"
         )
             return (val as any)["@id"];
+        // Then check for id property (backward compatibility)
+        if (
+            typeof (val as any).id === "string" ||
+            typeof (val as any).id === "number"
+        )
+            return (val as any).id;
+        // Fall back to generating a blank node ID
         return assignBlankNodeId(val);
     }
     return val as any;
@@ -360,16 +412,28 @@ export const isShallow = (source: any) => {
 };
 
 /** Create (or reuse) a deep reactive proxy for an object / array / Set. */
-export const deepSignal = <T extends object>(obj: T): DeepSignal<T> => {
+export const deepSignal = <T extends object>(
+    obj: T,
+    options?: DeepSignalOptions
+): DeepSignal<T> => {
     if (!shouldProxy(obj)) throw new Error("This object can't be observed.");
     if (!objToProxy.has(obj)) {
         // Create a unique root id symbol to identify this deep signal tree in patches.
         const rootId = Symbol("deepSignalRoot");
-        const proxy = createProxy(obj, objectHandlers, rootId) as DeepSignal<T>;
+        if (options) {
+            rootOptions.set(rootId, options);
+        }
+        const proxy = createProxy(
+            obj,
+            objectHandlers,
+            rootId,
+            options
+        ) as DeepSignal<T>;
         const meta = proxyMeta.get(proxy)!;
         meta.parent = undefined; // root has no parent
         meta.key = undefined; // root not addressed by a key
         meta.root = rootId; // ensure root id stored (explicit)
+        meta.options = options; // store options in metadata
         // Pre-register an empty signals map so isDeepSignal() is true before any property access.
         if (!proxyToSignals.has(proxy)) proxyToSignals.set(proxy, new Map());
         objToProxy.set(obj, proxy);
@@ -403,7 +467,8 @@ export function shallow<T extends object>(obj: T): Shallow<T> {
 const createProxy = (
     target: object,
     handlers: ProxyHandler<object>,
-    rootId?: symbol
+    rootId?: symbol,
+    options?: DeepSignalOptions
 ) => {
     const proxy = new Proxy(target, handlers);
     ignore.add(proxy);
@@ -411,8 +476,10 @@ const createProxy = (
     if (!proxyMeta.has(proxy)) {
         proxyMeta.set(proxy, {
             root: rootId || Symbol("deepSignalDetachedRoot"),
+            options: options || rootOptions.get(rootId!),
         });
     }
+
     return proxy;
 };
 
@@ -432,7 +499,12 @@ function getFromSet(
             !objToProxy.has(entry)
         ) {
             const synthetic = getSetEntryKey(entry);
-            const childProxy = createProxy(entry, objectHandlers, meta!.root);
+            const childProxy = createProxy(
+                entry,
+                objectHandlers,
+                meta!.root,
+                meta!.options
+            );
             const childMeta = proxyMeta.get(childProxy)!;
             childMeta.parent = receiver;
             childMeta.key = synthetic;
@@ -462,6 +534,30 @@ function getFromSet(
                     );
                     if (key === "add") {
                         const entry = args[0];
+
+                        // Add @id to object entries if options specify it
+                        if (
+                            entry &&
+                            typeof entry === "object" &&
+                            metaNow.options?.addIdToObjects &&
+                            entry.constructor === Object &&
+                            !("@id" in entry)
+                        ) {
+                            let syntheticId: string | number;
+                            if (metaNow.options.idGenerator) {
+                                syntheticId = metaNow.options.idGenerator();
+                            } else {
+                                syntheticId = assignBlankNodeId(entry);
+                            }
+
+                            Object.defineProperty(entry, "@id", {
+                                value: syntheticId,
+                                writable: false,
+                                enumerable: true,
+                                configurable: false,
+                            });
+                        }
+
                         let synthetic = getSetEntryKey(entry);
                         if (entry && typeof entry === "object") {
                             for (const existing of raw.values()) {
@@ -482,7 +578,8 @@ function getFromSet(
                             const childProxy = createProxy(
                                 entryVal,
                                 objectHandlers,
-                                metaNow.root
+                                metaNow.root,
+                                metaNow.options
                             );
                             const childMeta = proxyMeta.get(childProxy)!;
                             childMeta.parent = receiver;
@@ -490,30 +587,46 @@ function getFromSet(
                             objToProxy.set(entryVal, childProxy);
                             entryVal = childProxy;
                         }
-                        // Set entry add: emit object vs literal variant.
+                        // Set entry add: emit object vs primitive variant.
                         if (entryVal && typeof entryVal === "object") {
-                            queuePatch({
+                            // Object entry: path includes synthetic id, and emit deep patches for nested properties
-                                root: metaNow.root,
+                            queueDeepPatches(
-                                path: [...containerPath, synthetic],
+                                entry,
-                                op: "add",
+                                metaNow.root,
-                                type: "object",
+                                [...containerPath, synthetic],
-                            });
+                                metaNow.options
+                            );
                         } else {
+                            // Primitive entry: path is just the Set, value contains the primitive
                             queuePatch({
                                 root: metaNow.root,
-                                path: [...containerPath, synthetic],
+                                path: containerPath,
                                 op: "add",
-                                value: entryVal,
+                                type: "set",
+                                value: [entryVal],
                             });
                         }
                     } else if (key === "delete") {
                         const entry = args[0];
                         const synthetic = getSetEntryKey(entry);
-                        queuePatch({
+                        // Check if entry is primitive or object
-                            root: metaNow.root,
+                        if (entry && typeof entry === "object") {
-                            path: [...containerPath, synthetic],
+                            // Object entry: path includes synthetic id
-                            op: "remove",
+                            queuePatch({
-                        });
+                                root: metaNow.root,
+                                path: [...containerPath, synthetic],
+                                op: "remove",
+                            });
+                        } else {
+                            // Primitive entry: path is just the Set, value contains the primitive
+                            queuePatch({
+                                root: metaNow.root,
+                                path: containerPath,
+                                op: "remove",
+                                type: "set",
+                                value: entry,
+                            });
+                        }
                     } else if (key === "clear") {
                         // Structural clear: remove prior entry-level patches for this Set this tick.
                         if (pendingPatches) {
@@ -629,7 +742,12 @@ function ensureChildProxy(value: any, parent: object, key: string | number) {
     if (!shouldProxy(value)) return value;
     if (!objToProxy.has(value)) {
         const parentMeta = proxyMeta.get(parent)!;
-        const childProxy = createProxy(value, objectHandlers, parentMeta.root);
+        const childProxy = createProxy(
+            value,
+            objectHandlers,
+            parentMeta.root,
+            parentMeta.options
+        );
         const childMeta = proxyMeta.get(childProxy)!;
         childMeta.parent = parent;
         childMeta.key = key as string;
@@ -650,12 +768,14 @@ function normalizeKey(
         if (fullKey === "$") {
             // Provide $ meta proxy for array index signals
             if (!arrayToArrayOfSignals.has(target)) {
+                const receiverMeta = proxyMeta.get(receiver);
                 arrayToArrayOfSignals.set(
                     target,
                     createProxy(
                         target,
                         arrayHandlers,
-                        proxyMeta.get(receiver)?.root
+                        receiverMeta?.root,
+                        receiverMeta?.options
                     )
                 );
             }
@@ -716,6 +836,10 @@ const get =
 const objectHandlers = {
     get: get(false),
     set(target: object, fullKey: string, val: any, receiver: object): boolean {
+        // Prevent modification of @id property
+        if (fullKey === "@id") {
+            throw new Error("Cannot modify readonly property '@id'");
+        }
         // Respect original getter/setter semantics
         if (typeof descriptor(target, fullKey)?.set === "function")
             return Reflect.set(target, fullKey, val, receiver);
@@ -747,7 +871,8 @@ const objectHandlers = {
                     const childProxy = createProxy(
                         val,
                         objectHandlers,
-                        parentMeta!.root
+                        parentMeta!.root,
+                        parentMeta!.options
                     );
                     const childMeta = proxyMeta.get(childProxy)!;
                     childMeta.parent = receiver;
@@ -774,7 +899,12 @@ const objectHandlers = {
             const meta = proxyMeta.get(receiver);
             if (meta) {
                 // Recursively emit patches for all nested properties of newly attached objects
-                queueDeepPatches(val, meta.root, buildPath(receiver, fullKey));
+                queueDeepPatches(
+                    val,
+                    meta.root,
+                    buildPath(receiver, fullKey),
+                    meta.options
+                );
             }
             return result;
         }

sdk/js/alien-deepsignals/src/test/deepSignalOptions.test.ts

@@ -0,0 +1,340 @@
+import { describe, it, expect } from "vitest";
+import { deepSignal, DeepPatch, DeepSignalOptions } from "../deepSignal";
+import { watch } from "../watch";
+
+describe("deepSignal options", () => {
+    describe("custom ID generator", () => {
+        it("uses custom ID generator for objects without @id", async () => {
+            let counter = 1000;
+            const options: DeepSignalOptions = {
+                idGenerator: () => `custom-${counter++}`,
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ data: {} as any }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.data.user = { name: "Alice" };
+            await Promise.resolve();
+
+            // Check that @id was assigned
+            expect((state.data.user as any)["@id"]).toBe("custom-1000");
+
+            // Check that patch was emitted for @id
+            const flat = patches.flat().map((p) => p.path.join("."));
+            expect(flat).toContain("data.user.@id");
+
+            stop();
+        });
+
+        it("respects existing @id on objects", async () => {
+            const options: DeepSignalOptions = {
+                idGenerator: () => "should-not-be-used",
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ items: [] as any[] }, options);
+
+            state.items.push({ "@id": "existing-123", value: 42 });
+
+            // Should use the existing @id
+            expect((state.items[0] as any)["@id"]).toBe("existing-123");
+        });
+
+        it("uses @id property from objects added to Sets", async () => {
+            const options: DeepSignalOptions = {
+                idGenerator: () => "fallback-id",
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ s: new Set<any>() }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            const obj = { "@id": "set-entry-1", data: "test" };
+            state.s.add(obj);
+
+            await Promise.resolve();
+
+            const flat = patches.flat().map((p) => p.path.join("."));
+            // Path should use the @id as synthetic key
+            expect(flat.some((p) => p.startsWith("s.set-entry-1"))).toBe(true);
+
+            stop();
+        });
+    });
+
+    describe("addIdToObjects option", () => {
+        it("adds @id to all nested objects when enabled", async () => {
+            const options: DeepSignalOptions = {
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ root: {} as any }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.root.level1 = {
+                level2: {
+                    level3: { value: "deep" },
+                },
+            };
+
+            await Promise.resolve();
+
+            // Check all levels have @id
+            expect((state.root.level1 as any)["@id"]).toBeDefined();
+            expect((state.root.level1.level2 as any)["@id"]).toBeDefined();
+            expect(
+                (state.root.level1.level2.level3 as any)["@id"]
+            ).toBeDefined();
+
+            // Check patches were emitted for all @id fields
+            const flat = patches.flat().map((p) => p.path.join("."));
+            expect(flat).toContain("root.level1.@id");
+            expect(flat).toContain("root.level1.level2.@id");
+            expect(flat).toContain("root.level1.level2.level3.@id");
+
+            stop();
+        });
+
+        it("does not add @id when option is false", () => {
+            const state = deepSignal({ data: { nested: {} } });
+
+            // Should not have @id
+            expect("@id" in (state.data as any)).toBe(false);
+            expect("@id" in (state.data.nested as any)).toBe(false);
+        });
+
+        it("adds @id to objects in arrays", async () => {
+            const options: DeepSignalOptions = {
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ items: [] as any[] }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.items.push({ name: "Item 1" }, { name: "Item 2" });
+
+            await Promise.resolve();
+
+            // Both items should have @id
+            expect((state.items[0] as any)["@id"]).toBeDefined();
+            expect((state.items[1] as any)["@id"]).toBeDefined();
+
+            // Check patches
+            const flat = patches.flat().map((p) => p.path.join("."));
+            expect(flat).toContain("items.0.@id");
+            expect(flat).toContain("items.1.@id");
+
+            stop();
+        });
+
+        it("adds @id to objects in Sets", async () => {
+            const options: DeepSignalOptions = {
+                idGenerator: () =>
+                    `gen-${Math.random().toString(36).substr(2, 9)}`,
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ s: new Set<any>() }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            const obj1 = { value: 1 };
+            const obj2 = { value: 2 };
+            state.s.add(obj1);
+            state.s.add(obj2);
+
+            await Promise.resolve();
+
+            // Get proxied objects from Set
+            const proxiedObjs = Array.from(state.s);
+            expect((proxiedObjs[0] as any)["@id"]).toBeDefined();
+            expect((proxiedObjs[1] as any)["@id"]).toBeDefined();
+
+            // @id should be used as synthetic key in paths
+            const flat = patches.flat().map((p) => p.path.join("."));
+            const obj1Id = (proxiedObjs[0] as any)["@id"];
+            const obj2Id = (proxiedObjs[1] as any)["@id"];
+            expect(flat.some((p) => p.startsWith(`s.${obj1Id}`))).toBe(true);
+            expect(flat.some((p) => p.startsWith(`s.${obj2Id}`))).toBe(true);
+
+            stop();
+        });
+    });
+
+    describe("@id property behavior", () => {
+        it("makes @id readonly", () => {
+            const options: DeepSignalOptions = {
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ obj: {} as any }, options);
+            state.obj.data = { value: 1 };
+
+            // Attempting to modify @id should throw
+            expect(() => {
+                (state.obj.data as any)["@id"] = "new-id";
+            }).toThrow("Cannot modify readonly property '@id'");
+        });
+
+        it("makes @id enumerable", () => {
+            const options: DeepSignalOptions = {
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ obj: {} as any }, options);
+            state.obj.data = { value: 1 };
+
+            // @id should show up in Object.keys()
+            const keys = Object.keys(state.obj.data);
+            expect(keys).toContain("@id");
+        });
+
+        it("emits patches for @id even on objects with existing @id", async () => {
+            const options: DeepSignalOptions = {
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ container: {} as any }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            // Object already has @id before being added
+            const objWithId = { "@id": "pre-existing", data: "test" };
+            state.container.item = objWithId;
+
+            await Promise.resolve();
+
+            const flat = patches.flat().map((p) => p.path.join("."));
+            // Patch should still be emitted for @id
+            expect(flat).toContain("container.item.@id");
+
+            // Verify the value in the patch
+            const idPatch = patches
+                .flat()
+                .find((p) => p.path.join(".") === "container.item.@id");
+            expect((idPatch as any).value).toBe("pre-existing");
+
+            stop();
+        });
+    });
+
+    describe("options inheritance", () => {
+        it("child objects inherit options from root", async () => {
+            let idCounter = 5000;
+            const options: DeepSignalOptions = {
+                idGenerator: () => `inherited-${idCounter++}`,
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ root: {} as any }, options);
+
+            // Add nested structure
+            state.root.child = {
+                grandchild: {
+                    value: "nested",
+                },
+            };
+
+            // All should have IDs generated by the custom generator
+            expect((state.root.child as any)["@id"]).toMatch(/^inherited-/);
+            expect((state.root.child.grandchild as any)["@id"]).toMatch(
+                /^inherited-/
+            );
+        });
+
+        it("objects added to Sets inherit options", async () => {
+            let counter = 9000;
+            const options: DeepSignalOptions = {
+                idGenerator: () => `set-child-${counter++}`,
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ s: new Set<any>() }, options);
+
+            const obj = { nested: { value: 1 } };
+            state.s.add(obj);
+
+            // Iterate to get proxied object
+            const proxied = Array.from(state.s)[0];
+
+            // Object and nested object should have custom IDs
+            expect((proxied as any)["@id"]).toMatch(/^set-child-/);
+            expect((proxied.nested as any)["@id"]).toMatch(/^set-child-/);
+        });
+    });
+
+    describe("backward compatibility", () => {
+        it("still works without options", async () => {
+            const state = deepSignal({ data: { value: 1 } });
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.data.value = 2;
+            await Promise.resolve();
+
+            expect(patches.flat().length).toBeGreaterThan(0);
+            stop();
+        });
+
+        // TODO: Delete duplicate logic for `id`. Only accept @id.
+        it("objects with id property still work for Sets", async () => {
+            const state = deepSignal({ s: new Set<any>() });
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.s.add({ id: "legacy-id", value: 1 });
+            await Promise.resolve();
+
+            const flat = patches.flat().map((p) => p.path.join("."));
+            // Should use id as synthetic key
+            expect(flat.some((p) => p.startsWith("s.legacy-id"))).toBe(true);
+
+            stop();
+        });
+
+        it("@id takes precedence over id property", async () => {
+            const state = deepSignal({ s: new Set<any>() });
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.s.add({
+                id: "should-not-use",
+                "@id": "should-use",
+                value: 1,
+            });
+            await Promise.resolve();
+
+            const flat = patches.flat().map((p) => p.path.join("."));
+            // Should use @id, not id
+            expect(flat.some((p) => p.startsWith("s.should-use"))).toBe(true);
+            expect(flat.some((p) => p.startsWith("s.should-not-use"))).toBe(
+                false
+            );
+
+            stop();
+        });
+    });
+});

sdk/js/alien-deepsignals/src/test/watchPatches.test.ts

@@ -95,7 +95,16 @@ describe("watch (patch mode)", () => {
         await Promise.resolve();
         expect(batches.length >= 1).toBe(true);
         const allPaths = batches.flatMap((b) => b.map((p) => p.path.join(".")));
-        expect(allPaths.some((p) => p.startsWith("s."))).toBe(true);
+        // For primitives, the path should be just "s" (the Set itself)
+        expect(allPaths.every((p) => p === "s")).toBe(true);
+        // Check the values
+        const patches = batches.flat();
+        const addPatches = patches.filter((p) => p.op === "add");
+        const deletePatches = patches.filter((p) => p.op === "remove");
+        expect(addPatches.length).toBe(1);
+        expect(deletePatches.length).toBe(1);
+        expect((addPatches[0] as any).value[0]).toBe(3);
+        expect((deletePatches[0] as any).value).toBe(1);
         stop();
     });
 
@@ -226,6 +235,89 @@ describe("watch (patch mode)", () => {
     });
 
     describe("Set", () => {
+        it("emits patches for primitive adds", async () => {
+            const st = deepSignal({ s: new Set<any>() });
+            const batches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(st, ({ patches }) =>
+                batches.push(patches)
+            );
+            st.s.add(true);
+            st.s.add(2);
+            st.s.add("3");
+            await Promise.resolve();
+
+            expect(batches.length).toBe(1);
+            const patches = batches[0];
+            expect(patches.length).toBe(3);
+
+            // All patches should have the same path (the Set itself)
+            patches.forEach((p) => {
+                expect(p.path.join(".")).toBe("s");
+                expect(p.op).toBe("add");
+                expect((p as any).type).toBe("set");
+            });
+
+            // Check that values are in the value field, not in path
+            const values = patches.map((p: any) => p.value[0]);
+            expect(values).toContain(true);
+            expect(values).toContain(2);
+            expect(values).toContain("3");
+            stop();
+        });
+        it("emits patches for primitive deletes", async () => {
+            const st = deepSignal({ s: new Set<any>([true, 2, "3"]) });
+            const batches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(st, ({ patches }) =>
+                batches.push(patches)
+            );
+            st.s.delete(true);
+            st.s.delete(2);
+            await Promise.resolve();
+
+            expect(batches.length).toBe(1);
+            const patches = batches[0];
+            expect(patches.length).toBe(2);
+
+            // All patches should have the same path (the Set itself)
+            patches.forEach((p) => {
+                expect(p.path.join(".")).toBe("s");
+                expect(p.op).toBe("remove");
+                expect((p as any).type).toBe("set");
+            });
+
+            // Check that values are in the value field
+            const values = patches.map((p: any) => p.value);
+            expect(values).toContain(true);
+            expect(values).toContain(2);
+            stop();
+        });
+        it("does not emit patches for non-existent primitives", async () => {
+            const st = deepSignal({ s: new Set<any>([1, 2]) });
+            const batches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(st, ({ patches }) =>
+                batches.push(patches)
+            );
+            st.s.delete("nonexistent");
+            st.s.delete(999);
+            await Promise.resolve();
+
+            expect(batches.length).toBe(0);
+            stop();
+        });
+        it("does not emit patches for already added primitive", async () => {
+            const st = deepSignal({ s: new Set<any>([1, "test", true]) });
+            const batches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(st, ({ patches }) =>
+                batches.push(patches)
+            );
+            st.s.add(1);
+            st.s.add("test");
+            st.s.add(true);
+            await Promise.resolve();
+
+            expect(batches.length).toBe(0);
+            stop();
+        });
         it("emits single structural patch on Set.clear()", async () => {
             const st = deepSignal({ s: new Set<any>() });
             addWithId(st.s as any, { id: "a", x: 1 }, "a");
@@ -236,8 +328,13 @@ describe("watch (patch mode)", () => {
             );
             st.s.clear();
             await Promise.resolve();
-            const all = batches.flat().map((p) => p.path.join("."));
+            // clear() emits a single structural patch for the Set itself (op: "add", value: [])
-            expect(all).toEqual(["s"]);
+            const structuralPatches = batches
+                .flat()
+                .filter((p) => p.path.length === 1 && p.path[0] === "s");
+            expect(structuralPatches.length).toBe(1);
+            expect(structuralPatches[0].op).toBe("add");
+            expect((structuralPatches[0] as any).value).toEqual([]);
             stop();
         });
         it("emits delete patch for object entry", async () => {
@@ -288,8 +385,11 @@ describe("watch (patch mode)", () => {
             const ret = addWithId(st.s as any, 5, "ignored");
             expect(ret).toBe(5);
             await Promise.resolve();
+            // For primitives, path should be just "s" and value should be in the value field
             const paths = patches.flat().map((p) => p.path.join("."));
-            expect(paths).toContain("s.5");
+            expect(paths).toContain("s");
+            const values = patches.flat().map((p: any) => p.value?.[0]);
+            expect(values).toContain(5);
             stop();
         });
         it("setSetEntrySyntheticId applies custom id without helper", async () => {
@@ -358,10 +458,17 @@ describe("watch (patch mode)", () => {
             st.s.add(a1);
             st.s.add(a2);
             await Promise.resolve();
-            const keys = patches
+            // Filter for Set structural patches only (path length 2: ['s', syntheticId])
+            const setAddPatches = patches
                 .flat()
-                .filter((p) => p.op === "add")
+                .filter(
-                .map((p) => p.path.slice(-1)[0]);
+                    (p) =>
+                        p.op === "add" &&
+                        p.path.length === 2 &&
+                        p.path[0] === "s"
+                );
+            const keys = setAddPatches.map((p) => p.path.slice(-1)[0]);
+            // Both objects should have unique synthetic IDs despite id collision
             expect(new Set(keys).size).toBe(2);
             stop();
         });