@stacksjs/stx 0.2.170 → 0.2.172

package/dist/reactive-tracking.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The one piece of state that decides what is reactive to what.
+ *
+ * stx shipped two independent reactive systems in the same package entry, and
+ * the only thing keeping them apart was a variable name: `signals-api.ts` had
+ * `activeEffect`, `reactivity.ts` had `currentEffect`, and each recorded its
+ * dependencies against its own. Both are the same shape — the nullary function
+ * to re-run — so which system a value belonged to was decided entirely by
+ * which module happened to declare the variable that was set when it was read.
+ *
+ * Measured before this module existed, on `import { … } from 'stx'`:
+ *
+ *     reactive() + effect()        INERT      reactive() + watchEffect()  REACTIVE
+ *     ref()      + effect()        INERT      ref()      + watchEffect()  REACTIVE
+ *     state()    + effect()        REACTIVE   state()    + watchEffect()  INERT
+ *
+ * Four of six silently dead. Not an error, not a warning — the effect ran once
+ * and never again, which reads as "the value never changed". All eight names
+ * come from the same entry point with nothing to tell an author which half of
+ * the matrix they are standing in (stacksjs/stx#1885).
+ *
+ * Owning the state here rather than in either module is what makes the two
+ * interoperate without one importing the other, which would be a cycle. It is
+ * also why this file is small and has no opinions: everything else about a
+ * signal — how it stores its value, when it considers itself changed, what it
+ * exposes — stays where it was.
+ *
+ * ## What this does NOT bridge
+ *
+ * The client runtime in `signals.ts` is generated as a template literal and
+ * owns a third copy of this state inside that string. No module can import it,
+ * so the runtime is unaffected by this file and stays a separate system. See
+ * CLAUDE.md item 40; the parity suites are what hold those two in step.
+ *
+ * @module reactive-tracking
+ */
+/**
+ * The effect currently collecting dependencies.
+ *
+ * A reactive read calls this and, when it is not null, records the result as a
+ * subscriber. That is the whole of dependency tracking.
+ */
+export declare function getActiveSubscriber(): (() => void) | null;
+/**
+ * Make `subscriber` the one collecting dependencies, and return the previous.
+ *
+ * Returning the previous value rather than requiring the caller to read it
+ * first is deliberate: the restore is the step that gets forgotten, and a
+ * forgotten restore leaks the inner effect's identity into the outer scope, so
+ * every subsequent read subscribes the wrong function. Pair with
+ * {@link restoreActiveSubscriber} in a `finally`.
+ */
+export declare function setActiveSubscriber(subscriber: () => void): (() => void) | null;
+/** Undo a {@link setActiveSubscriber}, restoring what was listening before. */
+export declare function restoreActiveSubscriber(previous: (() => void) | null): void;
+/** How deeply effects are currently nested. */
+export declare function subscriberDepth(): number;
+/** Whether updates are currently being collected rather than applied. */
+export declare function isBatching(): boolean;
+/**
+ * Defer an effect to the end of the current batch.
+ *
+ * A `Set` rather than an array, so a signal written five times in one batch
+ * still runs its subscribers once.
+ */
+export declare function enqueueEffect(effect: () => void): void;
+/**
+ * Collect updates rather than applying them, and run each affected effect once
+ * when the outermost batch ends.
+ *
+ * Nested calls do not flush early — a `batch` inside a `batch` would otherwise
+ * run the outer batch's pending effects against half-applied state.
+ */
+export declare function runBatched(fn: () => void): void;
+/**
+ * Run `fn` with dependency tracking suspended.
+ *
+ * Reads inside are not recorded against the enclosing effect, which is what
+ * `untrack`/`peek` are for in both modules.
+ */
+export declare function withoutTracking<T>(fn: () => T): T;

package/dist/reactive-tracking.js

@@ -0,0 +1,49 @@
+let activeSubscriber = null;
+const subscriberStack = [];
+let batchDepth = 0;
+const pendingEffects = new Set;
+export function getActiveSubscriber() {
+  return activeSubscriber;
+}
+export function setActiveSubscriber(subscriber) {
+  const previous = activeSubscriber;
+  subscriberStack.push(subscriber);
+  activeSubscriber = subscriber;
+  return previous;
+}
+export function restoreActiveSubscriber(previous) {
+  subscriberStack.pop();
+  activeSubscriber = previous;
+}
+export function subscriberDepth() {
+  return subscriberStack.length;
+}
+export function isBatching() {
+  return batchDepth > 0;
+}
+export function enqueueEffect(effect) {
+  pendingEffects.add(effect);
+}
+export function runBatched(fn) {
+  batchDepth++;
+  try {
+    fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) {
+      const queued = [...pendingEffects];
+      pendingEffects.clear();
+      for (const effect of queued)
+        effect();
+    }
+  }
+}
+export function withoutTracking(fn) {
+  const previous = activeSubscriber;
+  activeSubscriber = null;
+  try {
+    return fn();
+  } finally {
+    activeSubscriber = previous;
+  }
+}

package/dist/reactivity.js

@@ -1,4 +1,5 @@
-let currentInstance = null, currentEffect = null;
+import { enqueueEffect, getActiveSubscriber, isBatching, restoreActiveSubscriber, setActiveSubscriber } from "./reactive-tracking.js";
+let currentInstance = null;
 function structuralEqual(a, b, seen = new WeakSet) {
   if (Object.is(a, b))
     return !0;
@@ -86,8 +87,9 @@ export function ref(initialValue) {
   let value = initialValue;
   const id = Symbol("ref"), refObj = {
     get value() {
-      if (currentEffect)
-        effectSubscribers.add(currentEffect);
+      const subscriber = getActiveSubscriber();
+      if (subscriber)
+        effectSubscribers.add(subscriber);
       return value;
     },
     set value(newValue) {
@@ -97,7 +99,10 @@ export function ref(initialValue) {
         for (const callback of subscribers)
           callback(newValue, oldValue);
         for (const effect of effectSubscribers)
-          effect();
+          if (isBatching())
+            enqueueEffect(effect);
+          else
+            effect();
       }
     },
     subscribe(callback) {
@@ -118,8 +123,12 @@ export function reactive(target) {
     return existing;
   const subscribers = new Map, notify = (key) => {
     const subs = subscribers.get(key);
-    if (subs)
-      for (const callback of [...subs])
+    if (!subs)
+      return;
+    for (const callback of [...subs])
+      if (isBatching())
+        enqueueEffect(callback);
+      else
         callback();
   }, subscribe = (key, callback) => {
     if (!subscribers.has(key))
@@ -130,9 +139,9 @@ export function reactive(target) {
     };
   }, proxy = new Proxy(target, {
     get(obj, prop, receiver) {
-      const value = Reflect.get(obj, prop, receiver);
-      if (currentEffect)
-        subscribe(prop, currentEffect);
+      const value = Reflect.get(obj, prop, receiver), subscriber = getActiveSubscriber();
+      if (subscriber)
+        subscribe(prop, subscriber);
       if (value !== null && typeof value === "object" && !Array.isArray(value)) {
         const proto = Object.getPrototypeOf(value);
         if (proto === Object.prototype || proto === null)
@@ -162,10 +171,9 @@ export function computed(getter) {
     update();
   }, update = () => {
     if (dirty) {
-      const oldValue = cachedValue, prevEffect = currentEffect;
-      currentEffect = markDirty;
+      const oldValue = cachedValue, prevEffect = setActiveSubscriber(markDirty);
       cachedValue = getter();
-      currentEffect = prevEffect;
+      restoreActiveSubscriber(prevEffect);
       dirty = !1;
       if (!Object.is(cachedValue, oldValue)) {
         for (const callback of subscribers)
@@ -174,15 +182,15 @@ export function computed(getter) {
           effect();
       }
     }
-  }, prevEffect = currentEffect;
-  currentEffect = markDirty;
+  }, prevEffect = setActiveSubscriber(markDirty);
   cachedValue = getter();
   dirty = !1;
-  currentEffect = prevEffect;
+  restoreActiveSubscriber(prevEffect);
   return {
     get value() {
-      if (currentEffect)
-        effectSubscribers.add(currentEffect);
+      const subscriber = getActiveSubscriber();
+      if (subscriber)
+        effectSubscribers.add(subscriber);
       update();
       return cachedValue;
     },
@@ -243,12 +251,11 @@ export function watch(source, callback, options = {}) {
     });
   }, getValueTracking = () => {
     if (typeof source === "function") {
-      const prevEffect = currentEffect;
-      currentEffect = onChange;
+      const prevEffect = setActiveSubscriber(onChange);
       try {
         return source();
       } finally {
-        currentEffect = prevEffect;
+        restoreActiveSubscriber(prevEffect);
       }
     }
     return source.value;
@@ -299,10 +306,9 @@ export function watchEffect(effect) {
       return;
     if (cleanup)
       cleanup();
-    const prevEffect = currentEffect;
-    currentEffect = run;
+    const prevEffect = setActiveSubscriber(run);
     cleanup = effect();
-    currentEffect = prevEffect;
+    restoreActiveSubscriber(prevEffect);
   };
   run();
   if (currentInstance)

package/dist/render.js

@@ -27,24 +27,11 @@ function parseTemplate(content) {
     let sMatch;
     const removeRanges = [];
     while ((sMatch = serverScriptOpenRe.exec(templateContent)) !== null) {
-      const tagEnd = sMatch.index + sMatch[0].length;
-      let sDepth = 1, sPos = tagEnd;
-      while (sPos < templateContent.length && sDepth > 0) {
-        const nextOpen = templateContent.indexOf("<script", sPos), nextClose = templateContent.indexOf("</script>", sPos);
-        if (nextClose === -1)
-          break;
-        if (nextOpen !== -1 && nextOpen < nextClose) {
-          sDepth++;
-          sPos = nextOpen + 7;
-        } else {
-          sDepth--;
-          if (sDepth === 0) {
-            removeRanges.push({ start: sMatch.index, end: nextClose + 9 });
-            break;
-          }
-          sPos = nextClose + 9;
-        }
-      }
+      const tagEnd = sMatch.index + sMatch[0].length, closeAt = templateContent.indexOf("</script>", tagEnd);
+      if (closeAt === -1)
+        continue;
+      removeRanges.push({ start: sMatch.index, end: closeAt + 9 });
+      serverScriptOpenRe.lastIndex = closeAt + 9;
     }
     for (let ri = removeRanges.length - 1;ri >= 0; ri--)
       templateContent = templateContent.substring(0, removeRanges[ri].start) + templateContent.substring(removeRanges[ri].end);

package/dist/runtime-injection.js

@@ -76,51 +76,37 @@ export function outputNeedsSignalsRuntime(html) {
   }
   return !1;
 }
-export async function injectSignalsRuntime(template, options) {
-  if (template.includes("data-stx-runtime") || template.includes("window.stx.state") || template.includes("STX Signals Runtime"))
-    return template;
-  if (options.buildMode === "serve") {
-    const runtimeScript = '<script data-stx-runtime src="/_stx/runtime.js"></script>', firstScriptInDoc = template.indexOf("<script");
-    if (firstScriptInDoc !== -1)
-      return template.slice(0, firstScriptInDoc) + runtimeScript + `
-` + template.slice(firstScriptInDoc);
-    if (template.includes("</head>")) {
-      const idx = template.indexOf("</head>");
-      return template.slice(0, idx) + runtimeScript + `
-` + template.slice(idx);
-    }
-    return runtimeScript + `
-` + template;
-  }
-  if (options.buildMode === "compile") {
-    const runtimeScript = '<script data-stx-runtime src="/__stx/runtime.__STX_HASH__.js"></script>', firstScriptInDoc = template.indexOf("<script");
-    if (firstScriptInDoc !== -1)
-      return template.slice(0, firstScriptInDoc) + runtimeScript + `
-` + template.slice(firstScriptInDoc);
-    if (template.includes("</head>")) {
-      const idx = template.indexOf("</head>");
-      return template.slice(0, idx) + runtimeScript + `
-` + template.slice(idx);
-    }
-    return runtimeScript + `
-` + template;
+function placeRuntimeTag(template, runtimeScript) {
+  const firstScript = template.indexOf("<script"), doctype = template.search(/<!doctype\b/i);
+  if (firstScript !== -1 && (doctype === -1 || firstScript > doctype))
+    return template.slice(0, firstScript) + runtimeScript + `
+` + template.slice(firstScript);
+  const headOpen = /<head\b[^>]*>/i.exec(template);
+  if (headOpen) {
+    const at = headOpen.index + headOpen[0].length;
+    return `${template.slice(0, at)}
+${runtimeScript}${template.slice(at)}`;
   }
-  const { getCachedSignalsRuntime } = await import("./caching.js"), runtimeScript = `<script data-stx-scoped data-stx-runtime>${await getCachedSignalsRuntime(options.debug)}</script>`, firstScriptInDoc = template.indexOf("<script");
-  if (firstScriptInDoc !== -1)
-    return template.slice(0, firstScriptInDoc) + runtimeScript + `
-` + template.slice(firstScriptInDoc);
   if (template.includes("</head>")) {
     const idx = template.indexOf("</head>");
     return template.slice(0, idx) + runtimeScript + `
 ` + template.slice(idx);
   }
-  if (template.includes("<body")) {
-    const idx = template.indexOf("<body"), closeIdx = template.indexOf(">", idx);
-    return template.slice(0, closeIdx + 1) + `
-` + runtimeScript + template.slice(closeIdx + 1);
-  }
-  return runtimeScript + `
-` + template;
+  if (findBodyOpenTag(template))
+    return replaceBodyOpenTag(template, (tag) => `${tag}
+${runtimeScript}`);
+  return `${runtimeScript}
+${template}`;
+}
+export async function injectSignalsRuntime(template, options) {
+  if (template.includes("data-stx-runtime") || template.includes("window.stx.state") || template.includes("STX Signals Runtime"))
+    return template;
+  if (options.buildMode === "serve")
+    return placeRuntimeTag(template, '<script data-stx-runtime src="/_stx/runtime.js"></script>');
+  if (options.buildMode === "compile")
+    return placeRuntimeTag(template, '<script data-stx-runtime src="/__stx/runtime.__STX_HASH__.js"></script>');
+  const { getCachedSignalsRuntime } = await import("./caching.js"), runtime = await getCachedSignalsRuntime(options.debug);
+  return placeRuntimeTag(template, `<script data-stx-scoped data-stx-runtime>${runtime}</script>`);
 }
 export async function injectRouterScript(template, options) {
   if (!template.includes("</body>"))

package/dist/script-validation.d.ts

@@ -1,10 +1,3 @@
-/**
- * Script validation module for STX templates.
- *
- * Validates client-side script content against prohibited DOM API patterns,
- * enforcing the use of STX composables and Vue-style alternatives instead
- * of raw browser APIs.
- */
 import type { StrictModeConfig } from './types';
 /**
  * Prohibited DOM API patterns in client scripts.

package/dist/script-validation.js

@@ -1,3 +1,4 @@
+import { stripCommentsAndLiterals } from "./strip-literals.js";
 export const PROHIBITED_DOM_PATTERNS = [
   {
     pattern: /document\.getElementById\s*\(/g,
@@ -126,21 +127,22 @@ export const PROHIBITED_DOM_PATTERNS = [
   }
 ];
 export function validateClientScript(content, filePath, strict, originFilePath) {
-  const strictConfig = typeof strict === "boolean" ? { enabled: strict, failOnViolation: strict } : strict ?? { enabled: !1 }, allowPatterns = strictConfig.allowPatterns ?? [], errors = [];
+  const strictConfig = typeof strict === "boolean" ? { enabled: strict, failOnViolation: strict } : strict ?? { enabled: !1 }, allowPatterns = strictConfig.allowPatterns ?? [], errors = [], scannable = stripCommentsAndLiterals(content.replace(/\{\{--[\s\S]*?--\}\}/g, (match) => match.replace(/[^\n]/g, " ")));
   for (const { pattern, message, suggestion } of PROHIBITED_DOM_PATTERNS) {
     if (allowPatterns.some((allowed) => /\w/.test(allowed) && message.includes(allowed)))
       continue;
     pattern.lastIndex = 0;
-    const matches = content.match(pattern);
+    const matches = scannable.match(pattern);
     if (matches && matches.length > 0) {
-      const lines = content.split(`
+      const lines = scannable.split(`
+`), sourceLines = content.split(`
 `), lineNumbers = [];
       lines.forEach((line, index) => {
         pattern.lastIndex = 0;
         if (pattern.test(line))
           lineNumbers.push(index + 1);
       });
-      const locationInfo = lineNumbers.length > 0 ? ` (script line${lineNumbers.length > 1 ? "s" : ""} ${lineNumbers.join(", ")})` : "", quoted = lineNumbers.slice(0, 3).map((n) => `        ${n} | ${(lines[n - 1] ?? "").trim().slice(0, 100)}`).join(`
+      const locationInfo = lineNumbers.length > 0 ? ` (script line${lineNumbers.length > 1 ? "s" : ""} ${lineNumbers.join(", ")})` : "", quoted = lineNumbers.slice(0, 3).map((n) => `        ${n} | ${(sourceLines[n - 1] ?? "").trim().slice(0, 100)}`).join(`
 `), snippet = quoted ? `
 ${quoted}` : "";
       errors.push(`  \u2717 ${message}${locationInfo}

package/dist/signals-api.d.ts

@@ -43,6 +43,24 @@
  *
  * @module signals-api
  */
+/**
+ * ## The canonical set (stacksjs/stx#1885 asks 3 and 4)
+ *
+ * `state` / `derived` / `effect`, exported here, are the primitives to reach
+ * for. They are what the client runtime puts on `window.stx`, what a
+ * `<script client>` block sees as bare identifiers, and what stx's own
+ * composables and stores are written against — the only set that reads the
+ * same in a module, in a component, and in a template.
+ *
+ * `reactivity.ts` exports a Vue-shaped family beside them — `ref`, `reactive`,
+ * `computed`, `watch`, `watchEffect` — from the same package entry. Both are
+ * backed by one dependency tracker now (`reactive-tracking.ts`), so mixing
+ * them works; four of the six pairings used to be silently inert. They are
+ * kept for code ported from Vue, not recommended for new code.
+ *
+ * Note `ref()` returns a `.value` object while `state()` returns a callable
+ * signal, so the two are not interchangeable at the call site.
+ */
 /**
  * A reactive state signal.
  *

package/dist/signals-api.js

@@ -1,12 +1,19 @@
-let activeEffect = null;
-const effectStack = [];
-let isBatching = !1;
-const pendingEffects = new Set, mountCallbacks = [], destroyCallbacks = [];
+import {
+  enqueueEffect,
+  getActiveSubscriber,
+  isBatching,
+  restoreActiveSubscriber,
+  runBatched,
+  setActiveSubscriber,
+  withoutTracking
+} from "./reactive-tracking.js";
+const mountCallbacks = [], destroyCallbacks = [];
 export function state(initialValue) {
   let value = initialValue;
   const subscribers = new Set, effects = new Set, signal = () => {
-    if (activeEffect)
-      effects.add(activeEffect);
+    const subscriber = getActiveSubscriber();
+    if (subscriber)
+      effects.add(subscriber);
     return value;
   };
   signal.set = (newValue) => {
@@ -14,8 +21,8 @@ export function state(initialValue) {
       const prev = value;
       value = newValue;
       subscribers.forEach((cb) => cb(value, prev));
-      if (isBatching)
-        effects.forEach((effect) => pendingEffects.add(effect));
+      if (isBatching())
+        effects.forEach((effect) => enqueueEffect(effect));
       else
         effects.forEach((effect) => effect());
     }
@@ -40,23 +47,21 @@ export function derived(compute) {
   const effects = new Set, markDirty = () => {
     if (!isDirty) {
       isDirty = !0;
-      if (isBatching)
-        effects.forEach((effect) => pendingEffects.add(effect));
+      if (isBatching())
+        effects.forEach((effect) => enqueueEffect(effect));
       else
         effects.forEach((effect) => effect());
     }
   }, signal = () => {
-    if (activeEffect)
-      effects.add(activeEffect);
+    const subscriber = getActiveSubscriber();
+    if (subscriber)
+      effects.add(subscriber);
     if (isDirty) {
-      const prevEffect = activeEffect;
-      activeEffect = markDirty;
-      effectStack.push(markDirty);
+      const prevEffect = setActiveSubscriber(markDirty);
       try {
         cachedValue = compute();
       } finally {
-        effectStack.pop();
-        activeEffect = prevEffect;
+        restoreActiveSubscriber(prevEffect);
       }
       isDirty = !1;
     }
@@ -78,15 +83,12 @@ export function effect(fn, options = {}) {
       cleanup();
       cleanup = void 0;
     }
-    const prevEffect = activeEffect;
-    activeEffect = runEffect;
-    effectStack.push(runEffect);
+    const prevEffect = setActiveSubscriber(runEffect);
     try {
       const result = fn();
       cleanup = typeof result === "function" ? result : void 0;
     } finally {
-      effectStack.pop();
-      activeEffect = prevEffect;
+      restoreActiveSubscriber(prevEffect);
     }
   };
   if (options.immediate !== !1)
@@ -98,18 +100,7 @@ export function effect(fn, options = {}) {
   };
 }
 export function batch(fn) {
-  if (isBatching) {
-    fn();
-    return;
-  }
-  isBatching = !0;
-  try {
-    fn();
-  } finally {
-    isBatching = !1;
-    pendingEffects.forEach((effect) => effect());
-    pendingEffects.clear();
-  }
+  runBatched(fn);
 }
 export function onMount(callback) {
   mountCallbacks.push(callback);
@@ -149,13 +140,7 @@ export function untrack(value) {
   return value;
 }
 export function peek(fn) {
-  const prevEffect = activeEffect;
-  activeEffect = null;
-  try {
-    return fn();
-  } finally {
-    activeEffect = prevEffect;
-  }
+  return withoutTracking(fn);
 }
 export function useOptimistic(base, reducer) {
   const readBase = typeof base === "function" ? base : () => base, pending = state([]), optimistic = derived(() => pending().reduce((acc, entry) => reducer(acc, entry.action), readBase()));