@supersoniks/concorde 5.1.3-immutable.1 → 5.1.3-immutable.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersoniks/concorde",
-  "version": "5.1.3-immutable.1",
+  "version": "5.1.3-immutable.2",
   "license": "MIT",
   "type": "module",
   "main": "",

package/src/core/components/functional/sdui/component-catalog.gaps.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-10-29T21:35:24.462Z",
+  "generatedAt": "2026-11-02T09:56:04.637Z",
   "count": 66,
   "items": [
     {

package/src/core/components/functional/sdui/component-catalog.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-10-29T21:35:24.462Z",
+  "generatedAt": "2026-11-02T09:56:04.637Z",
   "componentCount": 67,
   "components": [
     {

package/src/core/utils/PublisherProxy.ts

@@ -481,16 +481,16 @@ export class PublisherProxy<T = any> {
     const currentAtKey = (parentRaw as any)[this._parentKey_];
     if (currentAtKey === valueTosetInParent) return;
 
-    const nextParent = setAtKey(
+    // Silent rebuild (like the pre-immutable `parent._value_[key] = v`): ancestors get
+    // onInternalMutation via bubbling, never onAssign — else root onAssign listeners that
+    // write a child loop forever (seatmap Haxe `publisher.onAssign` → `mainState = …`).
+    this.parent._value_ = setAtKey(
       parentRaw as object,
       this._parentKey_,
       valueTosetInParent,
-    );
-    this.parent.set(
-      nextParent as any,
-      lockInternalMutationsTransmission,
-      true,
-    );
+    ) as any;
+    this.parent._cachedGet_ = undefined;
+    this.parent._syncOwnedValueIntoParent_(lockInternalMutationsTransmission);
   }
   /**
    * Extraire la valeur actuelle du proxy

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

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 import {
   deepFreeze,
   deleteAtKey,
@@ -41,14 +41,18 @@ describe("immutableValue helpers", () => {
     expect(next.a).toBe(1);
   });
 
-  it("unclonable values warn and pass through", () => {
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  it("unclonable leaves: plain containers copied + frozen, leaves kept by reference", () => {
     const fn = () => 1;
-    const obj = { fn };
-    // functions inside plain objects: structuredClone throws in many engines
+    const event = new Event("x");
+    const obj = { fn, nested: { event, list: [1] } };
+    // functions / Event: structuredClone throws
     const owned = takeOwnership(obj);
-    expect(owned).toBe(obj);
-    expect(warn).toHaveBeenCalled();
-    warn.mockRestore();
+    expect(owned).not.toBe(obj);
+    expect(Object.isFrozen(obj)).toBe(false);
+    expect(Object.isFrozen(obj.nested)).toBe(false);
+    expect(Object.isFrozen(owned.nested.list)).toBe(true);
+    expect(owned.fn).toBe(fn);
+    expect(owned.nested.event).toBe(event);
+    expect(Object.isFrozen(event)).toBe(false);
   });
 });

package/src/core/utils/immutableValue.ts

@@ -3,15 +3,24 @@
  * External values are cloned then deep-frozen; internal updates rebuild via spread.
  */
 
-const warnedUnclonable = new WeakSet<object>();
-
 export function isFrozenValue(value: unknown): boolean {
   return value != null && typeof value === "object" && Object.isFrozen(value);
 }
 
-/** Deep freeze (in place). Safe to call on already-frozen graphs. */
+/** Plain object / array — the only shapes the store clones and freezes. */
+function isPlainData(value: unknown): value is object {
+  if (value == null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Deep freeze plain objects / arrays (in place). Safe on already-frozen graphs.
+ * Non-plain values (Response, Event, DOM, class instances) are left untouched.
+ */
 export function deepFreeze<T>(value: T): T {
-  if (value == null || typeof value !== "object" || Object.isFrozen(value)) {
+  if (!isPlainData(value) || Object.isFrozen(value)) {
     return value;
   }
   Object.freeze(value);
@@ -27,7 +36,8 @@ export function deepFreeze<T>(value: T): T {
 
 /**
  * Clone so the publisher owns the data, then freeze.
- * Non-cloneable values (EventSource, etc.): kept as-is, not frozen (warned once).
+ * Graph with non-cloneable leaves (functions, Response, Event…): plain containers are
+ * copied + frozen, those leaves kept by reference — the caller's objects are never frozen.
  */
 export function takeOwnership<T>(value: T): T {
   if (value == null || typeof value !== "object") return value;
@@ -35,16 +45,20 @@ export function takeOwnership<T>(value: T): T {
   try {
     return deepFreeze(structuredClone(value));
   } catch {
-    if (!warnedUnclonable.has(value as object)) {
-      warnedUnclonable.add(value as object);
-      console.warn(
-        "[Concorde] takeOwnership: value is not structuredClone-able; stored without freeze.",
-      );
-    }
-    return value;
+    return ownPlainData(value);
   }
 }
 
+function ownPlainData<T>(value: T): T {
+  if (!isPlainData(value) || Object.isFrozen(value)) return value;
+  const copy = Array.isArray(value)
+    ? value.map(ownPlainData)
+    : Object.fromEntries(
+        Object.entries(value).map(([key, v]) => [key, ownPlainData(v)]),
+      );
+  return Object.freeze(copy) as T;
+}
+
 /** Drop `undefined` own keys on plain objects (before freeze). Arrays unchanged. */
 export function stripUndefinedKeys<T>(value: T): T {
   if (value == null || typeof value !== "object" || Array.isArray(value)) {

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

@@ -55,6 +55,57 @@ describe("immutable DataProvider store (79567)", () => {
     expect(get(cartKey)).toBe(snap);
   });
 
+  it("non-cloneable leaf: store owns plain data, caller objects stay unfrozen", () => {
+    const key = "publisherImmutableUnclonable";
+    class HttpLike {
+      ok = true;
+    }
+    const http = new HttpLike();
+    const processed = { messages: [{ type: "error" }] };
+    const onProcessed = vi.fn();
+    dp(key).processed.onAssign(onProcessed, false);
+
+    dp(key).set({ http, processed, onDone: () => 1 });
+
+    expect(Object.isFrozen(processed)).toBe(false);
+    expect(Object.isFrozen(processed.messages)).toBe(false);
+    expect(Object.isFrozen(http)).toBe(false);
+    const stored = dp(key).get() as any;
+    expect(stored.http).toBe(http);
+    expect(stored.processed).toEqual(processed);
+    expect(Object.isFrozen(stored.processed.messages)).toBe(true);
+    expect(onProcessed).toHaveBeenCalledWith(stored.processed);
+    PublisherManager.getInstance().delete(key);
+  });
+
+  it("nested set notifies parent internal mutation, not parent onAssign", () => {
+    set(cartKey, { items: [{ id: 1 }], total: 0 });
+    const parentAssign = vi.fn();
+    const parentMutation = vi.fn();
+    dp(cartKey).onAssign(parentAssign, false);
+    dp(cartKey).onInternalMutation(parentMutation);
+    parentAssign.mockClear();
+    parentMutation.mockClear();
+
+    dp(cartKey.total).set(10);
+
+    expect(parentAssign).not.toHaveBeenCalled();
+    expect(parentMutation).toHaveBeenCalled();
+    expect(get(cartKey).total).toBe(10);
+    expect(Object.isFrozen(get(cartKey))).toBe(true);
+  });
+
+  it("root onAssign writing a child does not loop", () => {
+    set(cartKey, { items: [], total: 0 });
+    let calls = 0;
+    dp(cartKey).onAssign(() => {
+      calls++;
+      dp(cartKey.total).set(calls);
+    }, false);
+    set(cartKey, { items: [{ id: 1 }], total: 0 });
+    expect(calls).toBe(1);
+  });
+
   it("re-assigning the same nested value does not re-publish the parent", () => {
     const listKey = new DataProviderKey<Row[]>("publisherImmutableListLoop");
     set(listKey, [{ id: 1 }]);

package/src/docs/getting-started/ai-agents.md

@@ -12,6 +12,16 @@ On a [starter](/docs/getting-started/installation) project, run `yarn ai:sync` a
 | Any consumer app (after `yarn add @supersoniks/concorde`) | `node node_modules/@supersoniks/concorde/scripts/ai-init.mjs` |
 | Concorde repo (contributors) | `yarn ai-init` |
 
+<sonic-code language="shell">
+  <template>
+# Starter (from project root)
+yarn ai:sync
+
+# Existing project
+node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
+  </template>
+</sonic-code>
+
 Re-run the same command after each Concorde upgrade to refresh the skill.
 
 ## The skill
@@ -28,6 +38,20 @@ Re-run the same command after each Concorde upgrade to refresh the skill.
 | `rules/composition.md` | Parts of compound components, built-in states |
 | `rules/troubleshooting.md` | Symptom → cause → fix: values not updating, requests not sent, empty lists |
 
+### Sources of truth
+
+The skill tells the agent to check, in this order:
+
+1. **The project** — the installed Concorde version (`npm ls @supersoniks/concorde`) and its existing `DataProviderKey`s, `Endpoint`s and components.
+2. **These docs** — index at [llms.txt](https://concorde.supersoniks.org/llms.txt); every page is served as Markdown when `.md` is appended to its URL. Offline: `node_modules/@supersoniks/concorde/src/**/*.md`.
+3. **The element API** — attributes, properties, events and slots in `node_modules/@supersoniks/concorde/custom-elements.json`. The file is large, so the agent queries one element:
+
+<sonic-code language="shell">
+  <template>
+node -e 'const t=process.argv[1];for(const m of require("@supersoniks/concorde/custom-elements.json").modules)for(const d of m.declarations)if(d.tagName===t)console.log(JSON.stringify({attributes:d.attributes?.map(a=>[a.name,a.type?.text,a.default]),properties:d.members?.filter(p=>p.kind==="field"&&!p.attribute).map(p=>p.name),events:d.events?.map(e=>e.name),slots:d.slots?.map(s=>s.name)},null,1))' sonic-select
+  </template>
+</sonic-code>
+
 ## What gets installed
 
 | Path | Role |
@@ -36,7 +60,7 @@ Re-run the same command after each Concorde upgrade to refresh the skill.
 | `.claude/skills/concorde` | Symlink for Claude Code |
 | `.junie/skills/concorde` | Symlink for JetBrains Junie |
 
-Where symlinks are not allowed (some Windows setups), the skill is copied instead. Your own skills in these folders are never touched. Commit `.agents/` and the links if your team shares agent settings.
+Where symlinks are not allowed (some Windows setups), the skill is copied instead. Only Concorde's own skill is replaced on each run: a project skill with another name is left alone, and one with the same name in `.claude/skills` or `.junie/skills` is never overwritten. If `.claude/skills` already points to `.agents/skills`, no per-skill link is created. Commit `.agents/` and the links if your team shares agent settings.
 
 **`AGENTS.md` stays yours:** `ai-init` never reads or writes it.
 
@@ -46,5 +70,7 @@ Where symlinks are not allowed (some Windows setups), the skill is copied instea
 |------|--------|
 | `--no-links` | Install `.agents/skills` only, without the `.claude` / `.junie` links |
 | `--overlay <dir>` | Also install the skills found in `<dir>/skills/` (project kit) |
+| `--project-root <dir>` | Project to install into (default: current directory) |
+| `--concorde-ai <dir>` | Concorde `ai/` folder to install from (default: the package's own) |
 
 Source files in the npm package: `node_modules/@supersoniks/concorde/ai/skills/concorde/`.