@stacksjs/stx 0.2.152 → 0.2.153

package/dist/signals.js

@@ -1921,12 +1921,6 @@ catch (e) {
   }
 
   function processElement(el, scope = componentScope) {
-    // Debug: log every element with x-class or @click
-    if (el.nodeType === Node.ELEMENT_NODE && el.hasAttribute) {
-      if (el.hasAttribute('x-class') || el.hasAttribute('@click')) {
-        console.log('[stx] processElement:', el.tagName, 'x-class:', el.hasAttribute('x-class'), '@click:', el.hasAttribute('@click'));
-      }
-    }
     // Lazy hydration: if this element has stx-hydrate and hasn't been hydrated
     // yet, defer its subtree processing until the trigger fires.
     if (el.nodeType === Node.ELEMENT_NODE && el.hasAttribute && el.hasAttribute('stx-hydrate') && !el.__stx_hydrated) {
@@ -2137,23 +2131,36 @@ else if (part) {
         const pipeResult = parsePipeExpression(expr, activeScope);
         if (pipeResult) {
           const unwrapScope = createExpressionAutoUnwrapProxy(activeScope, expr);
-          return maybeUnwrapSignal(executePipeExpression(pipeResult.valueExpr, pipeResult.pipes, unwrapScope));
+          var piped = maybeUnwrapSignal(executePipeExpression(pipeResult.valueExpr, pipeResult.pipes, unwrapScope));
+          noteExprSuccess(expr);
+          return piped;
         }
 
         // Use auto-unwrap proxy (Feature #1)
         const unwrapScope = createExpressionAutoUnwrapProxy(activeScope, expr);
         const fn = new Function('__scope__', 'with(__scope__) { return (' + expr + ') }');
-        return maybeUnwrapSignal(fn(unwrapScope));
+        var value = maybeUnwrapSignal(fn(unwrapScope));
+        noteExprSuccess(expr);
+        return value;
       }
 catch (e) {
         // Auto-unwrap can break explicit signal calls like errorData().message
         // Retry without auto-unwrap so signal functions remain callable
         try {
           const fn = new Function('__scope__', 'with(__scope__) { return (' + expr + ') }');
-          return maybeUnwrapSignal(fn(activeScope));
+          var retried = maybeUnwrapSignal(fn(activeScope));
+          noteExprSuccess(expr);
+          return retried;
         }
 catch (e2) {
           if (!(e2 instanceof ReferenceError) && !(e2 instanceof TypeError)) console.warn('[STX] Attribute expression error:', expr, e2);
+          // ReferenceError/TypeError stay unlogged HERE on purpose: a signal
+          // may not exist yet on an effect's first pass, and warning on every
+          // one of those trains people to ignore the console. Instead the
+          // failure is recorded and cleared the moment the same expression
+          // evaluates successfully, so only expressions that are STILL broken
+          // when hydration finishes get reported \u2014 by the audit (#1773).
+          else noteExprFailure(expr, e2);
           return '';
         }
       }
@@ -2172,18 +2179,11 @@ catch (e2) {
     var KEY_MAP = {enter:'Enter', tab:'Tab', escape:'Escape', space:' ', up:'ArrowUp', down:'ArrowDown', left:'ArrowLeft', right:'ArrowRight', 'delete':'Delete', backspace:'Backspace'};
 
     // Handle attributes
-    if (el.hasAttribute && (el.hasAttribute('x-class') || el.hasAttribute('@click'))) {
-      console.log('[stx] attr loop entry:', el.tagName, 'attrs:', getElementAttributes(el).map(a => a.name).join(', '));
-    }
     getElementAttributes(el).forEach(attr => {
       const name = attr.name;
       const value = attr.value;
       if (!name) return;
 
-      if (el.hasAttribute && (el.hasAttribute('x-class') || el.hasAttribute('@click'))) {
-        console.log('[stx] attr iter:', el.tagName, 'name:', name);
-      }
-
       // Dynamic attribute binding: @bind:attr, x-bind:attr, :attr, OR x-attr
       // x-attr (e.g. x-class, x-style, x-href, x-src) is the canonical binding prefix.
       // :attr still works for backward compat but is reserved for structural directives.
@@ -2278,7 +2278,6 @@ else {
         el.removeAttribute(name);
       }
 else if (name === '@class' || name === ':class' || name === 'x-class') {
-        console.log('[stx] HIT x-class handler:', el.tagName);
         bindClass(el, value, scope);
         el.removeAttribute(name);
       }
@@ -2336,9 +2335,7 @@ else if (name === 'ref' || name === ':ref' || name === 'x-ref' || name === 'data
           ? { ...globalHelpers, ...el.__stx_parent_scope }
           : { ...globalHelpers, ...scope, ...(findElementScope(el) || {}) };
 
-        console.log('[stx] binding event:', eventName, 'on', el.tagName, 'expr:', value.substring(0, 40));
         el.addEventListener(eventName, (event) => {
-          console.log('[stx] event fired:', eventName, 'on', el.tagName);
           // Vue-style component listeners fall through to the rendered native
           // root unless the child emits the same event. Signal components use
           // a scope wrapper, so native events arrive here from a descendant.
@@ -2459,7 +2456,7 @@ catch (e) {
         // Skip script elements entirely
         if (child.tagName === 'SCRIPT') return;
         // Skip elements already processed by stx.mount() \u2014 they have their own scope and effects
-        if (child.__stx_scope) { console.log('[processElement] skip __stx_scope:', child.tagName); return; }
+        if (child.__stx_scope) return;
         // Skip data-stx-scope elements \u2014 they are managed by the reactive (x-data) runtime
         if (child.hasAttribute && child.hasAttribute('data-stx-scope')) return;
         processElement(child, scope);
@@ -4410,16 +4407,34 @@ else if (timer === null) {
     // flash the boot script exists to prevent.
     var boot = null;
     try { boot = window.__STX_COLOR_MODE__ || null; } catch (e) {}
-    var storageKey = options.storageKey || (boot && boot.storageKey) || 'stx-color-mode';
-    var initialMode = options.initialMode || (boot && boot.initialMode) || 'auto';
-    var darkClass = options.darkClass || (boot && boot.darkClass) || 'dark';
-    var attribute = options.attribute || (boot && boot.attribute) || null;
+    // Explicit-undefined checks rather than ||, so an explicit darkClass:null
+    // or attribute:null opts out instead of falling through to the default.
+    function pick(a, b, fallback) {
+      if (a !== undefined) return a;
+      if (b !== undefined && b !== null) return b;
+      return fallback;
+    }
+    var storageKey = pick(options.storageKey, boot && boot.storageKey, 'stx-color-mode');
+    var initialMode = pick(options.initialMode, boot && boot.initialMode, 'auto');
+    var darkClass = pick(options.darkClass, boot && boot.darkClass, 'dark');
+    var attribute = pick(options.attribute, boot && boot.attribute, null);
+    var autoValueOption = pick(options.autoValue, boot && boot.autoValue, undefined);
     var disableTransitions = options.disableTransitions !== false;
-    var preference = initialMode;
     var resolved = 'light';
     var listeners = [];
     var cleanups = [];
 
+    // Storage tokens meaning "follow the system". 'system' is a common spelling
+    // for the same concept; rejecting it used to send the app down a silent
+    // data-loss path \u2014 read 'system', fail to recognise it, fall back to
+    // 'auto', then OVERWRITE the stored value with 'auto' (#1788).
+    function normalizeMode(v) {
+      if (v === 'light' || v === 'dark') return v;
+      if (v === 'auto' || v === 'system') return 'auto';
+      return null;
+    }
+    var preference = normalizeMode(initialMode) || 'auto';
+
     function getSystem() {
       return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
     }
@@ -4427,27 +4442,42 @@ else if (timer === null) {
     function applyDOM(mode) {
       var el = document.documentElement;
       if (disableTransitions) el.style.setProperty('transition', 'none', 'important');
-      if (attribute) { el.setAttribute(attribute, mode); }
-      else { if (mode === 'dark') el.classList.add(darkClass); else el.classList.remove(darkClass); }
+      // Both, when both are configured. The class drives the utility
+      // framework's dark: variants, the attribute drives everything else \u2014
+      // complements, not alternatives.
+      if (attribute) el.setAttribute(attribute, mode);
+      // Explicit add/remove, not toggle(cls, force) \u2014 very-happy-dom ignores
+      // the force argument and plain-toggles, inverting every light-mode test.
+      if (darkClass) { if (mode === 'dark') el.classList.add(darkClass); else el.classList.remove(darkClass); }
       if (disableTransitions) { el.offsetHeight; el.style.removeProperty('transition'); }
     }
-    function persist(pref) { try { localStorage.setItem(storageKey, pref); }
-catch (e) {} }
-    function readPersisted() {
-      try { var v = localStorage.getItem(storageKey); if (v === 'light' || v === 'dark' || v === 'auto') return v; }
-catch (e) {}
-      return null;
+    function readRaw() {
+      try { return localStorage.getItem(storageKey); }
+catch (e) { return null; }
     }
-    function update(pref) {
-      preference = pref;
-      resolved = resolve(pref);
+    // The spelling written back for 'auto': an explicit option wins, else
+    // whatever the app already stored, so its own pre-paint script keeps
+    // reading a value it recognises.
+    var storedRaw = readRaw();
+    var autoValue = autoValueOption !== undefined
+      ? autoValueOption
+      : ((storedRaw === 'auto' || storedRaw === 'system') ? storedRaw : 'auto');
+
+    function persist(pref) {
+      try { localStorage.setItem(storageKey, pref === 'auto' ? autoValue : pref); }
+catch (e) {} }
+    // persistChoice: only an explicit user choice is written back. Persisting
+    // on init would stamp the resolved default over a stored value this
+    // composable didn't recognise, destroying it.
+    function update(pref, persistChoice) {
+      preference = normalizeMode(pref) || 'auto';
+      resolved = resolve(preference);
       applyDOM(resolved);
-      persist(pref);
+      if (persistChoice !== false) persist(preference);
       listeners.forEach(function(fn) { fn(resolved, preference); });
     }
 
-    var persisted = readPersisted();
-    update(persisted || initialMode);
+    update(normalizeMode(storedRaw) || initialMode, false);
 
     var mql = window.matchMedia('(prefers-color-scheme: dark)');
     var onSystemChange = function() {
@@ -4462,8 +4492,11 @@ catch (e) {}
 
     var onStorage = function(e) {
       if (e.key !== storageKey) return;
-      var v = e.newValue;
-      if (v === 'light' || v === 'dark' || v === 'auto') {
+      var v = normalizeMode(e.newValue);
+      if (v) {
+        // Track the other tab's spelling too, so a write from here doesn't
+        // convert the key out from under it.
+        if (v === 'auto' && (e.newValue === 'auto' || e.newValue === 'system')) autoValue = e.newValue;
         preference = v; resolved = resolve(v); applyDOM(resolved);
         listeners.forEach(function(fn) { fn(resolved, preference); });
       }
@@ -4887,9 +4920,22 @@ catch (e) {}
       if (config.bodyAttrs && config.bodyAttrs.class) {
         config.bodyAttrs.class.split(' ').forEach(function(cls) { if (cls) document.body.classList.add(cls); });
       }
-      // Html lang
-      if (config.htmlAttrs && config.htmlAttrs.lang) {
-        document.documentElement.setAttribute('lang', config.htmlAttrs.lang);
+      // Html attributes. Every key, not just lang \u2014 the module impl
+      // (head.ts updateHead) has always applied all of them, and a root-level
+      // class is the main reason to reach for htmlAttrs at all (#1798).
+      // class merges rather than replaces, matching bodyAttrs.class above:
+      // the color-mode boot script owns a class on this same element.
+      if (config.htmlAttrs) {
+        for (var hk in config.htmlAttrs) {
+          if (!config.htmlAttrs.hasOwnProperty(hk)) continue;
+          var hv = config.htmlAttrs[hk];
+          if (hv == null) continue;
+          if (hk === 'class') {
+            String(hv).split(' ').forEach(function(cls) { if (cls) document.documentElement.classList.add(cls); });
+          } else {
+            document.documentElement.setAttribute(hk, hv);
+          }
+        }
       }
     }
     // Apply immediately if DOM is ready, otherwise on mount
@@ -5895,6 +5941,12 @@ else {
   window.nextTick = nextTick;
   window.useAsync = useAsync;
   window.useLocalStorage = useLocalStorage;
+  // Paired with the line above. Both are in STX_RUNTIME_GLOBALS, so a
+  // <script client> block gets either via the setup destructure \u2014 but code
+  // that reads the bare window global directly (a plain <script>, or a
+  // bundled module that wasn't rewritten) found useLocalStorage defined and
+  // useSessionStorage undefined.
+  window.useSessionStorage = useSessionStorage;
   window.useEventListener = useEventListener;
   window.useWebSocket = useWebSocket;
   window.useColorMode = useColorMode;
@@ -6285,6 +6337,9 @@ catch (e) {
         }
       }
     });
+
+    // Everything that should have hydrated has now had its chance (#1773).
+    auditHydration(document.body, 'DOMContentLoaded');
   };
   window.__stxDomReadyHandler = stxDomReadyHandler;
   console.log('[stx] registering DOMContentLoaded handler');
@@ -6376,6 +6431,184 @@ catch (e) {
     }
   }
 
+  // ==========================================================================
+  // Post-hydration invariant sweep (stacksjs/stx#1773)
+  // ==========================================================================
+  //
+  // Preserved moustaches are the framework's de-facto error UI: ANY failure in
+  // the detect \u2192 extract \u2192 bundle \u2192 ship \u2192 rebind relay collapses into the same
+  // visible symptom, literal {{ }} on screen. Eight separate fixes each patched
+  // one site's heuristic, and no invariant anywhere asserted the actual
+  // requirement \u2014 zero unhydrated scopes after hydration. So every new upstream
+  // miss reached users silently and had to be diagnosed from a screenshot.
+  //
+  // This is that invariant. It runs at the end of both hydration entry points
+  // and turns a silent miss into one loud, self-healing event:
+  //
+  //   - an element carrying data-stx-scope whose id isn't in the registry, or
+  //     that hydration reached but never processed, is reported AND processed
+  //     with the ambient scope, which is what the walk would have done had the
+  //     script arrived. That recovers the D2/D3 shapes (a silent early return
+  //     in the walk, a stale __stx_scope guard) rather than merely naming them.
+  //   - leftover {{ }} text is reported. Diagnostic only, never auto-fixed:
+  //     without a scope there is nothing to interpolate against, and a page may
+  //     legitimately print moustaches.
+  //
+  // Deliberately quiet in the normal case: nothing is logged when the page has
+  // no signals at all, and containers that legitimately show template syntax
+  // (<pre>, <code>, <template>, <script>, <style>, <textarea>, and anything
+  // under [data-stx-ignore]) are skipped.
+
+  var AUDIT_SKIP_TAGS = { PRE: 1, CODE: 1, SCRIPT: 1, STYLE: 1, TEXTAREA: 1, TEMPLATE: 1 };
+
+  // Expressions whose evaluation threw a ReferenceError/TypeError and have not
+  // since succeeded. evalAttrExpr swallows those two on purpose \u2014 a signal may
+  // not exist yet on an effect's first pass \u2014 which is why a genuinely broken
+  // binding produces no diagnostic at all today. The classic case is
+  // :if="flag()" where flag is a signal: the auto-unwrap proxy returns the
+  // VALUE, calling it throws TypeError, the directive suppresses it, and the
+  // element silently stays hidden with no warning anywhere (see CLAUDE.md,
+  // "Signals: scripts call, templates don't").
+  //
+  // Recording rather than warning immediately is what keeps this quiet on
+  // working pages: a first-pass failure that later succeeds clears itself, so
+  // only expressions still broken when hydration finishes are reported.
+  var _exprFailures = {};
+  var _exprFailureCount = 0;
+
+  function noteExprFailure(expr, err) {
+    if (_exprFailures[expr] !== undefined) return;
+    // Bounded: one runaway loop must not grow this without limit.
+    if (_exprFailureCount >= 50) return;
+    _exprFailureCount++;
+    _exprFailures[expr] = (err && err.message) ? err.message : String(err);
+  }
+
+  function noteExprSuccess(expr) {
+    if (_exprFailures[expr] === undefined) return;
+    delete _exprFailures[expr];
+    _exprFailureCount--;
+  }
+
+  function auditSkipped(node) {
+    // Not rendered, not audited. Covers <template> content (a detached
+    // DocumentFragment \u2014 which some DOM implementations still walk into) and
+    // :if branches parked off-document, neither of which the user can see.
+    if (node.isConnected === false) return true;
+    for (var p = node.parentNode; p; p = p.parentNode) {
+      if (p.nodeType === Node.DOCUMENT_FRAGMENT_NODE) return true;
+      if (p.nodeType !== Node.ELEMENT_NODE) continue;
+      if (AUDIT_SKIP_TAGS[p.tagName]) return true;
+      if (p.hasAttribute && p.hasAttribute('data-stx-ignore')) return true;
+    }
+    return false;
+  }
+
+  function findLiteralMoustaches(root) {
+    var found = [];
+    if (!root || typeof document.createTreeWalker !== 'function') return found;
+    // Read NodeFilter off window, not the bare global: in a real browser they
+    // are the same object, but some DOM implementations used for testing expose
+    // it only on window, and a bare reference then throws inside the audit.
+    var showText = (window.NodeFilter && window.NodeFilter.SHOW_TEXT) || 4;
+    var walker = document.createTreeWalker(root, showText, null);
+    var node;
+    while ((node = walker.nextNode())) {
+      var text = node.nodeValue || '';
+      if (text.indexOf('{{') === -1 || text.indexOf('}}') === -1) continue;
+      if (auditSkipped(node)) continue;
+      found.push(text.trim().slice(0, 80));
+      if (found.length >= 5) break;
+    }
+    return found;
+  }
+
+  // A diagnostic that can break hydration is worse than no diagnostic, so the
+  // whole sweep is wrapped and every DOM capability it uses is feature-checked.
+  // Minimal document stubs (tests, non-browser embeddings) simply skip it.
+  function auditHydration(container, phase) {
+    try { auditHydrationUnsafe(container, phase); }
+    catch (e) { console.warn('[stx] hydration audit skipped:', e && e.message ? e.message : e); }
+  }
+
+  function auditHydrationUnsafe(container, phase) {
+    if (!window.stx || !window.stx._scopes) return;
+    var root = container && typeof container.querySelectorAll === 'function' ? container : document.body;
+    if (!root || typeof root.querySelectorAll !== 'function') return;
+
+    // Unregistered / unprocessed scopes \u2014 the unambiguous failure, and the one
+    // worth repairing.
+    var stranded = [];
+    root.querySelectorAll('[data-stx-scope]').forEach(function(el) {
+      if (el.__stx_audit_recovered) return;
+      // Deferred islands are unhydrated ON PURPOSE until their trigger fires.
+      if (el.hasAttribute('stx-hydrate') || el.__stx_hydration_scheduled) return;
+      var scopeId = el.getAttribute('data-stx-scope');
+      var registered = window.stx._scopes[scopeId];
+      if (registered && el.__stx_disposers) return;
+      stranded.push({ el: el, id: scopeId, registered: !!registered });
+    });
+
+    if (stranded.length) {
+      console.error(
+        '[stx] hydration invariant failed after ' + phase + ': '
+        + stranded.length + ' scope(s) left unhydrated \u2014 '
+        + stranded.map(function(s) {
+          return s.id + (s.registered ? ' (registered, never processed)' : ' (not registered)');
+        }).join(', ')
+        + '. Recovering with the ambient scope; please report with the page that produced it (stacksjs/stx#1773).',
+      );
+      stranded.forEach(function(s) {
+        // Once per element: a repair that itself fails must not loop on the
+        // next navigation.
+        s.el.__stx_audit_recovered = true;
+        try {
+          var vars = s.registered ? window.stx._scopes[s.id] : null;
+          if (vars) Object.assign(componentScope, vars);
+          s.el.__stx_disposers = trackEffects(function() { processElement(s.el, componentScope); });
+          s.el.removeAttribute('x-cloak');
+          s.el.querySelectorAll('[x-cloak]').forEach(function(c) { c.removeAttribute('x-cloak'); });
+        }
+        catch (e) {
+          console.error('[stx] hydration recovery failed for scope ' + s.id + ':', e);
+        }
+      });
+    }
+
+    var literals = findLiteralMoustaches(root);
+    if (literals.length) {
+      console.error(
+        '[stx] hydration invariant failed after ' + phase + ': literal {{ }} left in the DOM \u2014 '
+        + literals.join(' | ')
+        + '. An expression did not bind; see stacksjs/stx#1773. Wrap intentional '
+        + 'template syntax in <pre>/<code> or [data-stx-ignore] to exclude it.',
+      );
+    }
+
+    // Expressions that threw and never recovered. Reported here rather than at
+    // throw time so a first-pass miss that later resolves stays silent.
+    var brokenExprs = [];
+    for (var expr in _exprFailures) {
+      if (Object.prototype.hasOwnProperty.call(_exprFailures, expr))
+        brokenExprs.push(expr + ' \u2192 ' + _exprFailures[expr]);
+    }
+    if (brokenExprs.length) {
+      var hint = brokenExprs.some(function(m) { return m.indexOf('is not a function') !== -1; })
+        ? ' If one of these calls a signal, drop the parentheses: templates read '
+          + 'a signal by bare name (:if="flag"), scripts call it (flag()). Calling '
+          + 'the unwrapped value is a TypeError, which directives suppress \u2014 the '
+          + 'element just stays hidden.'
+        : '';
+      console.error(
+        '[stx] hydration invariant failed after ' + phase + ': '
+        + brokenExprs.length + ' expression(s) never evaluated \u2014 '
+        + brokenExprs.slice(0, 5).join(' | ') + '.' + hint,
+      );
+      _exprFailures = {};
+      _exprFailureCount = 0;
+    }
+  }
+
   // ==========================================================================
   // Container Cleanup (for SPA navigation)
   // ==========================================================================
@@ -6617,6 +6850,9 @@ catch (e) { console.warn('[stx] destroy callback error:', e); }
 catch (e) { console.warn('[stx] mount callback error:', e); }
     });
     mountCallbacks.length = 0;
+
+    // Everything that should have hydrated has now had its chance (#1773).
+    auditHydration(container, 'stx:load');
   }
 
   // Helper to process elements while skipping already-processed scoped containers