@stacksjs/stx 0.2.152 → 0.2.154

package/dist/signals.js

@@ -1,4 +1,5 @@
 import { state, derived, effect, batch, onMount, onDestroy, isSignal, isDerived, untrack, peek } from "./signals-api.js";
+import { runtimeHandledXAttrsLiteral } from "./runtime-globals.js";
 
 export * from "./signals-api.js";
 export function generateSignalsRuntime() {
@@ -689,6 +690,12 @@ catch (e) { console.warn('[stx] dispose error:', e); } });
     return typeof v === 'function' && v._isSignal === true;
   }
 
+  // The derived brand is set at creation; this predicate was declared and
+  // auto-imported for years without ever existing here (#1804).
+  function isDerived(v) {
+    return typeof v === 'function' && v._isDerived === true;
+  }
+
   function untrack(v) {
     return isSignal(v) || (typeof v === 'function' && v._isDerived) ? v() : v;
   }
@@ -873,7 +880,13 @@ finally {
 
   function useFetch(urlOrFn, options = {}) {
     const data = state(options.initialData ?? null);
-    const loading = state(true);
+    // Starts false when nothing will be requested. It used to start true
+    // unconditionally while the only thing clearing it was the fetch that
+    // immediate:false suppresses \u2014 so the documented way to declare a deferred
+    // request produced a composable stuck loading forever, which is exactly the
+    // case where a template is most likely driving a spinner off it (#1818).
+    const immediate = options.immediate !== false;
+    const loading = state(immediate);
     const error = state(null);
     if (options.suspense) registerSuspense(loading, error);
 
@@ -927,20 +940,27 @@ finally {
       }
     };
 
-    // Auto-fetch on mount unless disabled
-    if (options.immediate !== false) {
-      onMount(fetchData);
-    }
-
-    // If urlOrFn is a function, watch for changes and refetch
+    // A reactive URL drives its own fetching: effect() runs eagerly on creation,
+    // so the first run IS the mount fetch. Registering onMount as well issued
+    // two requests for every function URL (#1818).
     if (typeof urlOrFn === 'function') {
+      var firstUrlRun = true;
       effect(() => {
         const url = urlOrFn();
-        if (url && options.immediate !== false) {
-          fetchData();
+        if (!url) return;
+        // Honour immediate:false for the FIRST evaluation only. A later change
+        // to the URL is a new request the caller asked for by changing it, not
+        // the initial one they deferred.
+        if (firstUrlRun) {
+          firstUrlRun = false;
+          if (!immediate) return;
         }
+        fetchData();
       });
     }
+else if (immediate) {
+      onMount(fetchData);
+    }
 
     return {
       data,
@@ -973,17 +993,26 @@ finally {
   // Navigation API
   // ==========================================================================
 
-  function navigate(url, forceReload) {
-    if (forceReload) {
-      window.location.href = url;
+  // Second argument is an options object: { replace, reload }.
+  //
+  // It used to be a bare forceReload boolean while the shipped declaration
+  // promised { replace?: boolean } \u2014 so the one call the type system invited,
+  // navigate(url, { replace: true }), took the truthy branch and did a full
+  // document load that PUSHED a history entry: the opposite of replace, at the
+  // cost of the SPA router, with no error (#1807).
+  //
+  // A bare boolean is still accepted and still means "full reload", because
+  // that was the real shipped behaviour and docs and examples contain it.
+  function navigate(url, options) {
+    var opts = (options && typeof options === 'object') ? options : { reload: !!options };
+    var replace = !!opts.replace;
+    var reload = !!(opts.reload || opts.forceReload);
+    if (!reload && window.stxRouter && typeof window.stxRouter.navigate === 'function') {
+      window.stxRouter.navigate(url, { replace: replace });
       return;
     }
-    if (window.stxRouter && typeof window.stxRouter.navigate === 'function') {
-      window.stxRouter.navigate(url);
-    }
-else {
-      window.location.href = url;
-    }
+    if (replace) window.location.replace(url);
+    else window.location.href = url;
   }
 
   function goBack() { window.history.back(); }
@@ -1038,20 +1067,66 @@ else {
     };
     window.addEventListener('popstate', syncFromUrl);
     window.addEventListener('stx:navigate', syncFromUrl);
+    // Own-property reads only. The backing object comes from Object.fromEntries,
+    // so it inherits Object.prototype \u2014 an unguarded params()[key] returned a
+    // FUNCTION for 'toString', 'constructor', 'valueOf' and friends, which is
+    // neither a string nor undefined and matches no declared return type.
+    var own = function(key) {
+      var current = params();
+      return Object.prototype.hasOwnProperty.call(current, key);
+    };
+    // pushState by default; replaceState when the caller asks for it (#1825).
+    //
+    // The canonical reason to delete a param is to CONSUME a one-shot value \u2014
+    // an OAuth callback result, ?checkout=success, a flash token \u2014 and the
+    // point of consuming it is that it must not survive a Back press. Under
+    // pushState the pre-delete URL, the one still carrying the param, becomes
+    // the previous entry, so Back replays the callback and whatever consuming
+    // it triggered runs again.
+    //
+    // Default stays pushState so nothing that works today changes, and the
+    // option is spelled { replace } to match navigate(), which already takes it.
+    var commit = function(url, options) {
+      // A plain truthy read of the replace property looks equivalent and is
+      // not: it asks whether the value HAS a replace property, and every string
+      // has String.prototype.replace \u2014 so delete(key, 'push') would have
+      // replaced, the exact opposite of what it reads as. Requiring an object
+      // also keeps this identical to the module implementation in
+      // composables/use-router.ts; with optional chaining alone the two
+      // disagreed on the empty string, which short-circuits in one and hits
+      // String.prototype.replace in the other.
+      //
+      // NB: no backticks anywhere in this block. This runtime is assembled as a
+      // template literal, so a backtick in a COMMENT ends the string and the
+      // rest of the runtime is parsed as code.
+      var replace = !!(options && typeof options === 'object' && options.replace);
+      if (replace)
+        window.history.replaceState({}, '', url);
+      else
+        window.history.pushState({}, '', url);
+      syncFromUrl();
+    };
     return {
       data: params,
-      get: function(key) { return params()[key]; },
-      set: function(key, value) {
+      get: function(key) { return own(key) ? params()[key] : undefined; },
+      has: own,
+      set: function(key, value, options) {
         var url = new URL(window.location.href);
         url.searchParams.set(key, value);
-        window.history.pushState({}, '', url);
-        syncFromUrl();
+        commit(url, options);
+      },
+      // delete and has were DECLARED but absent, so the compiler endorsed calls
+      // that threw in the browser; setAll and data were present but undeclared
+      // (#1806). Deleting writes history the same way set does, for consistency.
+      'delete': function(key, options) {
+        var url = new URL(window.location.href);
+        url.searchParams['delete'](key);
+        commit(url, options);
       },
-      setAll: function(obj) {
+      setAll: function(obj, options) {
         var url = new URL(window.location.href);
         Object.keys(obj).forEach(function(k) { url.searchParams.set(k, obj[k]); });
-        window.history.pushState({}, '', url);
-        syncFromUrl();
+        commit(url, options);
       }
     };
   }
@@ -1139,11 +1214,16 @@ finally {
       onMount(fetchData);
     }
 
-    // refetchOnFocus
+    // refetchOnFocus \u2014 removed on destroy, like refetchInterval right below.
+    // It used to add a listener and never remove it, so every instance leaked
+    // one for the life of the page and each SPA navigation added more; every
+    // stale listener still fired, refetching for components long gone (#1818).
     if (options.refetchOnFocus) {
-      document.addEventListener('visibilitychange', function() {
+      var onVisibility = function() {
         if (!document.hidden) fetchData();
-      });
+      };
+      document.addEventListener('visibilitychange', onVisibility);
+      onDestroy(function() { document.removeEventListener('visibilitychange', onVisibility); });
     }
 
     // refetchInterval
@@ -1921,12 +2001,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 +2211,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,24 +2259,17 @@ 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.
       // x-text, x-html, x-model, x-show, x-if, x-for, x-cloak, x-ref, x-data are
       // handled by their own code paths below \u2014 exclude them here.
-      var X_HANDLED = {'x-text':1,'x-html':1,'x-model':1,'x-show':1,'x-if':1,'x-for':1,'x-cloak':1,'x-ref':1,'x-data':1,'x-bind':1,'x-class':1,'x-style':1,'x-tooltip':1,'x-tooltip-position':1};
+      var X_HANDLED = ${runtimeHandledXAttrsLiteral()};
       if (name.startsWith('@bind:') || name.startsWith('x-bind:')
           || (name.startsWith(':') && !name.startsWith('::') && !DIRECTIVE_NAMES[name.slice(1).split('.')[0]] && !EVENT_RE.test(name.slice(1)))
           || (name.startsWith('x-') && !X_HANDLED[name.split('.')[0]] && !X_HANDLED[name])) {
@@ -2278,7 +2358,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 +2415,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 +2536,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);
@@ -2660,7 +2737,11 @@ catch (e) {
       });
     }
     else if (tag === 'select') {
-      var syncSelect = () => { el.value = getValue() ?? ''; };
+      // Same equality guard as the text branch. Harmless here \u2014 a select has
+      // no caret \u2014 but an unconditional write is still a needless DOM mutation
+      // on every signal change, and the inconsistency invites the text-branch
+      // bug being reintroduced by copying this one (#1799).
+      var syncSelect = () => { var next = getValue() ?? ''; if (el.value !== next) el.value = next; };
       el.__stx_model_sync = syncSelect;
       effect(syncSelect);
       if (!el.__stx_model_observer && typeof window.MutationObserver !== 'undefined') {
@@ -2680,7 +2761,41 @@ catch (e) {
       el.addEventListener('change', () => setValue(coerceValue(el.value)));
     }
 else {
-      effect(() => { el.value = getValue() ?? ''; });
+      // Writing el.value moves the text cursor to the END of the control, and
+      // typing forms a loop: input -> setValue -> the signal changes -> this
+      // effect re-runs -> the write. So every keystroke reset the caret
+      // (stacksjs/stx#1799).
+      //
+      // Invisible while appending at the end of a field, which is why a login
+      // form with x-model felt fine and a textarea people actually edit did
+      // not. Worse inside :for, where key-based reuse updates the item signal
+      // on reuse (#1669) and re-evaluates the reused row's bindings on every
+      // character.
+      //
+      // The equality guard alone fixes typing, because the value this effect
+      // computes IS the value just typed. The offset is preserved as well for
+      // the case the guard cannot cover: a value that legitimately changed
+      // from elsewhere while the field is focused \u2014 a formatter rewriting
+      // input, a remote sync.
+      effect(() => {
+        var next = getValue() ?? '';
+        if (el.value === next) return;
+        var active = typeof document !== 'undefined' && document.activeElement === el;
+        var start = null;
+        var end = null;
+        if (active) {
+          // selectionStart throws on input types that do not support
+          // selection (number, email, date), so it cannot be assumed present.
+          try { start = el.selectionStart; end = el.selectionEnd; }
+          catch (e) { start = null; end = null; }
+        }
+        el.value = next;
+        if (active && start !== null && typeof el.setSelectionRange === 'function') {
+          // Clamp: the incoming value may be shorter than the old offset.
+          try { el.setSelectionRange(Math.min(start, next.length), Math.min(end == null ? start : end, next.length)); }
+          catch (e) { /* type does not support selection */ }
+        }
+      });
       el.addEventListener(modifiers.includes('lazy') ? 'change' : 'input', () => setValue(coerceValue(el.value)));
     }
 
@@ -3947,9 +4062,6 @@ catch (e2) {
     const fullScope = { ...globalHelpers, ...capturedComponentScope, ...(capturedElementScope || {}) };
     const directSignal = fullScope[expr];
 
-    if (directSignal) {
-      console.log('[stx] bindIf direct signal for :if=' + expr, 'signal identity:', directSignal === componentScope[expr] ? 'SAME' : 'DIFFERENT', 'signal():', directSignal());
-    }
     effect(() => {
       var value;
       if (directSignal && (directSignal._isSignal || directSignal._isDerived)) {
@@ -4029,6 +4141,11 @@ else if (!value && isInserted) {
         // if) fire too. The if attribute was already removed, so no recursion.
         if (value && isInserted && !childrenProcessed) {
           childrenProcessed = true;
+          // Until this deferred pass runs, the shown subtree still holds literal
+          // {{ }}. Flag it so the hydration audit doesn't report those as a
+          // binding miss in the gap before the setTimeout fires \u2014 a :for nested
+          // in a :if binds a macrotask after the synchronous stx:load audit (#1773).
+          el.__stx_if_pending = true;
           setTimeout(function() {
             var childScope = { ...globalHelpers, ...capturedComponentScope, ...(capturedElementScope || {}) };
             // A false single-element conditional is detached before the
@@ -4046,6 +4163,8 @@ else if (!value && isInserted) {
             // :if children still have x-cloak and stay hidden.
             el.removeAttribute('x-cloak');
             el.querySelectorAll('[x-cloak]').forEach(function(c) { c.removeAttribute('x-cloak'); });
+            // Deferred bind complete \u2014 the audit may inspect this subtree now.
+            el.__stx_if_pending = false;
           }, 0);
         }
       }
@@ -4081,10 +4200,25 @@ else if (!value && isInserted) {
 
   // provide() \u2014 share values across components (like Vue's provide/inject)
   // Usage: provide('Modal', Modal) \u2014 makes Modal accessible in all components
+  //
+  // inject() was auto-imported but implemented nowhere, so half of the pair
+  // worked: provide() succeeded and the failure surfaced only in the consumer
+  // (#1804). Values are recorded in a private registry as well as on window,
+  // because the global write collides with native properties \u2014 provide('name',
+  // x) lands on window.name, which the browser coerces to a string.
+  var __stxProvided = Object.create(null);
+
   function provide(name, value) {
+    __stxProvided[name] = value;
     window[name] = value;
   }
 
+  function inject(name, defaultValue) {
+    if (name in __stxProvided) return __stxProvided[name];
+    if (name in window) return window[name];
+    return defaultValue;
+  }
+
   // ==========================================================================
   // Timer & Utility Composables
   // ==========================================================================
@@ -4366,6 +4500,33 @@ else if (timer === null) {
     });
   }
 
+  // Watch several sources at once, calling back with (newValues, oldValues).
+  // Declared and auto-imported but never implemented here (#1804). NOT an alias
+  // of $watch, which spreads the values and passes no oldValues \u2014 callers
+  // written against the declared contract would silently receive the wrong
+  // arguments. Sources may be signals, Vue-style refs, or plain values.
+  function watchMultiple(sources, callback, options) {
+    options = options || {};
+    var read = function() {
+      return sources.map(function(s) {
+        if (typeof s === 'function') return s();
+        if (s && typeof s === 'object' && 'value' in s) return s.value;
+        return s;
+      });
+    };
+    var oldValues = read();
+    var first = true;
+    return effect(function() {
+      var newValues = read();
+      if (first) {
+        first = false;
+        if (!options.immediate) return;
+      }
+      callback(newValues, oldValues);
+      oldValues = newValues;
+    });
+  }
+
   function useAsync(fn, options) {
     options = options || {};
     var asyncState = 'idle';
@@ -4410,16 +4571,49 @@ 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.
+    // An explicit null means "do not manage this", from the call site OR from
+    // app.colorMode. The boot payload is generated by stx and always carries
+    // every key, so absent and explicitly-null ARE distinguishable there, and
+    // rejecting null made the boot global the one path that could not say it
+    // (#1813). The asymmetry hid because it only bites where the fallback is
+    // non-null: attribute:null looked fine, darkClass:null silently became
+    // 'dark' \u2014 so opting out of the class required repeating the option at
+    // every call site, defeating the single-source arrangement the global
+    // exists for.
+    function pick(a, b, fallback) {
+      if (a !== undefined) return a;
+      if (b !== undefined) return b;
+      return fallback;
+    }
+    // Read through a helper rather than a short-circuit on boot itself: that
+    // expression yields undefined for an undefined boot but NULL for a null
+    // one, which pick would now honour as an explicit opt-out.
+    function fromBoot(key) {
+      return (boot && typeof boot === 'object') ? boot[key] : undefined;
+    }
+    var storageKey = pick(options.storageKey, fromBoot('storageKey'), 'stx-color-mode');
+    var initialMode = pick(options.initialMode, fromBoot('initialMode'), 'auto');
+    var darkClass = pick(options.darkClass, fromBoot('darkClass'), 'dark');
+    var attribute = pick(options.attribute, fromBoot('attribute'), null);
+    var autoValueOption = pick(options.autoValue, fromBoot('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 +4621,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 +4671,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 +5099,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
@@ -5320,16 +5545,25 @@ catch (e) {}
   // Component mount system
   var mountQueue = [];
 
-  window.stx = {
+  // MERGE, never replace (#1804). Three client bundles assign window.stx and
+  // the last one used to erase the others. Object.assign also preserves the
+  // object IDENTITY, which matters because the generated store runtime captures
+  // window.stx in a closure variable \u2014 replacing the object leaves that closure
+  // calling a detached one.
+  window.stx = Object.assign(window.stx || {}, {
     hydrate: hydrateSubtree,
     state,
     derived,
     effect,
     batch,
     isSignal,
+    isDerived,
     untrack,
     peek,
+    inject,
+    watchMultiple,
     onMount,
+    onBeforeMount: onMount,
     onDestroy,
     onMounted: onMount,
     onBeforeUnmount: onDestroy,
@@ -5446,6 +5680,11 @@ catch (e) {}
     defineSlots: function() {
       return window.__STX_CURRENT_SLOTS__ || {};
     },
+    // Vue spells the same lookup useSlots(); it was auto-imported with no
+    // implementation behind it (#1804).
+    useSlots: function() {
+      return window.__STX_CURRENT_SLOTS__ || {};
+    },
 
     _mountCallbacks: mountCallbacks,
     _destroyCallbacks: destroyCallbacks,
@@ -5862,7 +6101,7 @@ else {
         doMount();
       }
     }
-  };
+  });
 
   // Also expose globally for convenience
   window.state = state;
@@ -5895,6 +6134,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;
@@ -6095,10 +6340,20 @@ else {
       const setupName = el.getAttribute('data-stx');
       console.log('[DOMContentLoaded] data-stx:', setupName, 'el:', el.tagName, 'fn exists:', !!(setupName && window[setupName]));
       if (setupName && window[setupName]) {
-        const result = window[setupName]();
-        console.log('[DOMContentLoaded] setup returned:', result ? Object.keys(result).slice(0, 10) : 'null');
-        if (typeof result === 'object') {
-          Object.assign(componentScope, result);
+        // Contained, like the two sibling setup call sites. An uncaught throw
+        // here aborted the whole forEach and everything after it in this
+        // handler, so ONE bad name in ONE page's setup left every root on the
+        // page unhydrated \u2014 the user sees raw {{ }}, and the console names the
+        // identifier without saying it cost them the document (#1805).
+        try {
+          const result = window[setupName]();
+          console.log('[DOMContentLoaded] setup returned:', result ? Object.keys(result).slice(0, 10) : 'null');
+          if (typeof result === 'object' && result !== null) {
+            Object.assign(componentScope, result);
+          }
+        }
+        catch (e) {
+          console.error('[stx] page setup "' + setupName + '" threw; this root will not hydrate:', e);
         }
       }
     });
@@ -6190,7 +6445,7 @@ else {
         componentScope = { ...componentScope, ...scopeVars };
       }
 
-      console.log('[stx] calling processElement on scope:', scopeId, 'componentScope total keys:', Object.keys(componentScope).length, 'has openEventModal:', 'openEventModal' in componentScope, 'scopeVars keys:', Object.keys(scopeVars).length);
+      console.log('[stx] calling processElement on scope:', scopeId, 'componentScope keys:', Object.keys(componentScope).length, 'scopeVars keys:', Object.keys(scopeVars).length);
       var disposeEffects = trackEffects(function() { processElement(el); });
       el.__stx_disposers = disposeEffects;
       console.log('[stx] scope processed OK:', scopeId);
@@ -6285,6 +6540,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 +6634,192 @@ 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;
+      // A :if whose deferred child-binding pass hasn't run yet legitimately holds
+      // literal {{ }} that binds a macrotask later \u2014 not a hydration miss (#1773).
+      if (p.__stx_if_pending) return true;
+      // A deferred island (client=visible|idle|\u2026) is unhydrated ON PURPOSE until
+      // its trigger fires, so its {{ }} legitimately stay literal in the meantime
+      // \u2014 not a miss (#1746). The stranded-scope pass already skips stx-hydrate;
+      // the literal sweep must too.
+      if (p.hasAttribute && p.hasAttribute('stx-hydrate') && !p.__stx_hydrated) 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 +7061,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