sync work in progress

src/app/layout.tsx

@@ -46,27 +46,46 @@ function dsslInlineStyles(): { name: string; src: string }[] {
 
 // Dev-only interop shim: the engine styles the SSR DOM BEFORE React hydrates
 // (that is the whole point — no FOUC). React 19 then logs one console.error
-// about extra style attributes and, helpfully, does not patch them. On our own
-// site that reads as "1 Issue" in the dev overlay. This shim filters ONLY the
-// hydration notices whose diff references DSSL's var(--dssl-*) attributes and
-// re-tells them as an explained info line; any genuine mismatch still shows.
+// about extra style attributes and, helpfully, does not patch them. Next's
+// dev overlay ALSO patches console.error (one layer around everything) and
+// counts every error it sees into the "Issues" badge — so a plain filter
+// installed here would sit INSIDE Next's collector and the badge would still
+// show "1". This shim instead installs an assignment trap: the moment Next
+// assigns its own wrapper, we capture it and re-publish OUR filter as the
+// outermost layer. DSSL's own hydration diff is swallowed + explained; every
+// other console.error still reaches Next's collector untouched.
 const hydrationShim = `
 (function () {
-  var HYD = 'A tree hydrated but some attributes of the server rendered HTML';
-  var orig = console.error;
-  console.error = function () {
+  var HYD = 'A tree hydrated but some attributes';
+  var MARK = '--dssl';
+  var inner = console.error;   // native, until Next assigns its wrapper
+  var trapped = false;
+  function outer() {
     var s = '';
     for (var i = 0; i < arguments.length; i++) {
       var a = arguments[i];
-      s += (typeof a === 'string' ? a : ' ');
+      s += (i ? ' ' : '') + (typeof a === 'string' ? a : (a && a.message ? a.message : ''));
     }
-    if (s.indexOf(HYD) === 0 && s.indexOf('--dssl') !== -1) {
+    if (s.indexOf(HYD) !== -1 && s.indexOf(MARK) !== -1) {
       console.info('%cDSSL%c styled this page before React hydrated. The "hydrated but some attributes didn\\u2019t match" notice is expected interop: the engine owns those style attributes, and React explicitly leaves them alone.',
         'background:#b3372e;color:#fff;padding:1px 6px;border-radius:3px;font-weight:700', '');
       return;
     }
-    return orig.apply(console, arguments);
-  };
+    return inner.apply(console, arguments);
+  }
+  try {
+    var desc = Object.getOwnPropertyDescriptor(console, 'error');
+    if (!desc || !desc.configurable) throw new Error('not configurable');
+    Object.defineProperty(console, 'error', {
+      configurable: true,
+      get: function () { return trapped ? outer : inner; },
+      set: function (fn) { inner = fn; trapped = true; }
+    });
+  } catch (e) {
+    // fallback: plain filter — console noise is still explained away,
+    // though the dev-overlay badge may still count the notice.
+    console.error = outer;
+  }
 })();
 `;
 

src/components/dssl/views/DocsView.tsx

@@ -17,6 +17,7 @@ const SIDE = [
   { head: null, id: "motion", label: "Motion" },
   { head: null, id: "errors", label: "Errors" },
   { head: null, id: "api", label: "JS API" },
+  { head: null, id: "interop", label: "Interop (React & co.)" },
 ];
 
 export default function DocsView() {
@@ -443,6 +444,63 @@ button { use focus-ring }
               <code>&lt;html data-dssl-reset&gt;</code> enables the small built-in reset.
             </p>
           </section>
+
+          <section className="doc-block" id="interop">
+            <h2 className="section-title">Interop — React, hydration &amp; friends</h2>
+            <p className="doc-lead">
+              DSSL is deliberately framework-agnostic: it styles whatever DOM exists,
+              so it works under React, Vue, Svelte or plain HTML. But if you render
+              with React there is <b>one known, harmless notice</b> you should
+              understand — and this very site is the living example.
+            </p>
+            <div className="note">
+              <b>Why the notice happens.</b> The engine applies styles to the SSR DOM
+              <i> before</i> React hydrates — that is the whole anti-flash design. React
+              then compares the DOM against its virtual render, finds extra
+              <code> style="--dssl-*…"</code> attributes it did not put there, and logs
+              one hydration diff to the console. React explicitly <b>does not patch
+              them away</b> — it leaves the engine&apos;s styles alone. Nothing is wrong:
+              the styles are working exactly as intended.
+            </div>
+            <p className="doc-lead">
+              In dev builds that single notice can surface as a "1 Issue" overlay badge,
+              because Next&apos;s dev tools wrap <code>console.error</code> and count
+              everything they see. This site installs an <i>assignment trap</i>: the moment
+              Next assigns its own collector, the shim captures it and re-publishes the
+              filter as the <b>outermost</b> layer — so DSSL&apos;s own diff is swallowed
+              and re-logged as an explained info line <b>before</b> Next can count it.
+              Any genuine hydration mismatch still flows through to the collector at full
+              volume. In production React does not diff attributes at all, so the notice
+              disappears entirely; the shim is dev-only.
+            </p>
+            <CodeBlock file="dev-only console shim (this site's layout.tsx)" code={`// assignment trap: become the OUTERMOST console.error
+// the moment Next assigns its own collector
+let inner = console.error, trapped = false;
+Object.defineProperty(console, 'error', {
+  configurable: true,
+  get: () => (trapped ? outer : inner),
+  set: (fn) => { inner = fn; trapped = true; }
+});
+function outer(...args) {
+  const s = args.map(String).join(' ');
+  // swallow ONLY the DSSL-attribute hydration diff
+  if (s.includes('A tree hydrated but some attributes')
+      && s.includes('--dssl')) {
+    console.info('DSSL styled this page before React hydrated. Expected interop.');
+    return;
+  }
+  return inner.apply(console, args);  // genuine issues flow through
+}`} />
+            <p className="doc-lead">
+              Two more interop notes worth knowing. First, if a framework re-renders a
+              subtree and <i>removes</i> elements the engine had styled, the touched
+              registry notices the removal via MutationObserver and cleans up — no
+              leaked inline styles. Second, if your framework toggles attributes the
+              engine matches on (like <code>data-dssl-*</code> signal mirrors), change
+              them through <code>DSSL.signal()</code> rather than DOM writes, so rules
+              re-evaluate on the same tick instead of waiting for the observer.
+            </p>
+          </section>
         </div>
       </div>
     </div>