Log warning in console if duplicate ids are detected

CHANGELOG.md

@@ -6,6 +6,9 @@
   * Remove AMD publish target since its EOL: https://github.com/requirejs/requirejs/issues/1816#issuecomment-707503323
   * Remove CommonJS publish target. `require("idiomorph")` no longer resolves; use `import "idiomorph"` instead. (@botandrose) #122
 
+* Added:
+  * Warn in the console when duplicate ids are detected during a morph, since they can cause subtle state loss (@botandrose) #142
+
 ## [0.7.4] - 2025-09-29
 
 * Fixed:

src/idiomorph.js

@@ -1189,6 +1189,12 @@ var Idiomorph = (function () {
       for (const id of duplicateIds) {
         persistentIds.delete(id);
       }
+      if (duplicateIds.size) {
+        console.warn(
+          "[Warning] duplicate ids found during morph, state loss within these elements is possible:",
+          Array.from(duplicateIds),
+        );
+      }
       return persistentIds;
     }
 

test/core.js

@@ -606,4 +606,50 @@ describe("Core morphing tests", function () {
     // included in the persistent ID set or it will pantry the id'ed node in error
     initial.outerHTML.should.equal("<span>Bar</span>");
   });
+
+  describe("duplicate id warnings", function () {
+    let warn;
+
+    beforeEach(function () {
+      warn = sinon.stub(console, "warn");
+    });
+
+    afterEach(function () {
+      warn.restore();
+    });
+
+    it("warns when the old content has duplicate ids", function () {
+      let initial = make("<div><p id='a'>Foo</p><p id='a'>Bar</p></div>");
+      Idiomorph.morph(initial, "<div><p id='a'>Baz</p></div>");
+      warn.calledOnce.should.equal(true);
+      warn.firstCall.args[1].should.eql(["a"]);
+    });
+
+    it("warns when the new content has duplicate ids", function () {
+      let initial = make("<div><p id='a'>Foo</p></div>");
+      Idiomorph.morph(initial, "<div><p id='a'>Bar</p><p id='a'>Baz</p></div>");
+      warn.calledOnce.should.equal(true);
+      warn.firstCall.args[1].should.eql(["a"]);
+    });
+
+    it("reports every duplicated id", function () {
+      let initial = make(
+        "<div><p id='a'>Foo</p><p id='a'>Bar</p><p id='b'>Baz</p><p id='b'>Qux</p></div>",
+      );
+      Idiomorph.morph(initial, "<div><p id='a'>Foo</p><p id='b'>Baz</p></div>");
+      warn.firstCall.args[1].should.eql(["a", "b"]);
+    });
+
+    it("does not warn when all ids are unique", function () {
+      let initial = make("<div><p id='a'>Foo</p><p id='b'>Bar</p></div>");
+      Idiomorph.morph(initial, "<div><p id='a'>Baz</p><p id='b'>Qux</p></div>");
+      warn.called.should.equal(false);
+    });
+
+    it("does not warn when the content has no ids at all", function () {
+      let initial = make("<div><p>Foo</p><p>Bar</p></div>");
+      Idiomorph.morph(initial, "<div><p>Baz</p><p>Qux</p></div>");
+      warn.called.should.equal(false);
+    });
+  });
 });