@stacksjs/stx 0.2.153 → 0.2.155

package/dist/events.js

@@ -1,3 +1,4 @@
+import { templateHasReactiveContext } from "./runtime-globals.js";
 const DOM_EVENTS = new Set([
   "click",
   "dblclick",
@@ -185,8 +186,14 @@ function wrapHandler(handler, modifiers) {
     wrapped = `__stx_throttle(() => { ${wrapped} }, ${modifiers.throttle})`;
   return wrapped;
 }
+export function asInvocableStatement(handler) {
+  const name = handler.trim();
+  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name))
+    return handler;
+  return `if (typeof ${name} === 'function' && !${name}._isSignal) ${name}($event);`;
+}
 function generateEventListener(event) {
-  const { modifiers } = event, elementId = event.elementId.replace(/\\/g, "\\\\").replace(/'/g, "\\'"), checks = generateModifierChecks(event), handler = wrapHandler(event.handler, modifiers), options = [];
+  const { modifiers } = event, elementId = event.elementId.replace(/\\/g, "\\\\").replace(/'/g, "\\'"), checks = generateModifierChecks(event), handler = wrapHandler(asInvocableStatement(event.handler), modifiers), options = [];
   if (modifiers.once)
     options.push("once: true");
   if (modifiers.capture)
@@ -254,8 +261,8 @@ else {
     }${optionsStr});
   })();`;
 }
-function generateRuntimeScript(elements) {
-  if (elements.length === 0)
+export function generateRuntimeScript(events) {
+  if (events.length === 0)
     return "";
   return `
 <script data-stx-events>
@@ -284,9 +291,16 @@ function generateRuntimeScript(elements) {
     };
   }
 
-  // Non-reactive fallback runner. The handler is embedded HTML-entity-encoded so
-  // the surrounding <script> can never contain raw markup (e.g. </script>); we
-  // decode it to JS only in memory here, then run it with $event/$el in scope.
+  // Non-reactive fallback runner. The handler is embedded HTML-entity-encoded
+  // so the surrounding script element can never contain raw markup, including
+  // its own closing tag; we decode it to JS only in memory here, then run it
+  // with $event/$el in scope.
+  //
+  // This comment must not spell that closing tag out. It used to, as an
+  // example, and a browser ends the script element at the FIRST one it sees \u2014
+  // so everything below this line, __stx_runHandler included, was emitted as
+  // page text and no listener was ever bound. The comment about escaping was
+  // the thing that needed escaping.
   function __stx_runHandler(h, $event, $el) {
     var code = h
       .replace(/&lt;/g, '<')
@@ -305,7 +319,7 @@ function generateRuntimeScript(elements) {
   }
 
   // Event listeners
-  ${elements.flatMap((el) => el.events).map(generateEventListener).join(`
+  ${events.map(generateEventListener).join(`
 `)}
 })();
 </script>`;
@@ -338,7 +352,7 @@ export function extractAndProcessEvents(template) {
   return { template: output, bindings: allBindings };
 }
 export function processEventDirectives(template, context, _filePath) {
-  if (/\b(?:state|derived|effect)\s*(?:<[^<>()]*>)?\s*\(/.test(template) || /@(?:model|show|for|if)\s*=/.test(template) || /data-stx(?:-auto)?(?![-\w])/.test(template))
+  if (templateHasReactiveContext(template))
     return template;
   if (context.__stx_sfc_mode) {
     if (/x-data\s*=\s*["']/.test(template))
@@ -369,7 +383,7 @@ export function processEventDirectives(template, context, _filePath) {
     }
     output = output.slice(0, element.startIndex) + newTag + output.slice(element.endIndex);
   }
-  const script = generateRuntimeScript(elements), bodyIdx = output.lastIndexOf("</body>");
+  const script = generateRuntimeScript(elements.flatMap((el) => el.events)), bodyIdx = output.lastIndexOf("</body>");
   if (bodyIdx !== -1)
     output = output.slice(0, bodyIdx) + script + `
 ` + output.slice(bodyIdx);

package/dist/expressions.d.ts

@@ -80,7 +80,7 @@ export declare function interpolateScriptsInTemplate(template: string, context:
 /**
  * Process template expressions including variables, filters, and operations
  */
-export declare function processExpressions(template: string, context: Record<string, any>, filePath: string, options?: { forceSignals?: boolean }): string;
+export declare function processExpressions(template: string, context: Record<string, any>, filePath: string): string;
 /**
  * Apply filters to a value
  */

package/dist/expressions.js

@@ -318,7 +318,7 @@ export function interpolateScriptExpressions(scriptBody, context) {
       const value = evaluateExpression(expr, context);
       if (value === void 0)
         return match;
-      return JSON.stringify(value);
+      return JSON.stringify(value).replace(/</g, "\\u003c");
     } catch {
       return match;
     }
@@ -344,7 +344,7 @@ export function interpolateScriptsInTemplate(template, context, options = {}) {
   });
   return restoreStashedScripts(output, interpolatedScripts);
 }
-export function processExpressions(template, context, filePath, options) {
+export function processExpressions(template, context, filePath) {
   let output = template;
   const styleMatcher = (html, i) => {
     const end = matchStyleElement(html, i);
@@ -359,7 +359,7 @@ export function processExpressions(template, context, filePath, options) {
   output = maskInto(output, styleMatcher, styleBlocks, (n) => `<!--__STX_STYLE_${n}__-->`);
   const scriptBlocks = [];
   output = maskInto(output, matchScriptElement, scriptBlocks, (n) => `<!--__STX_SCRIPT_EXPR_${n}__-->`);
-  const hasSignals = options?.forceSignals === !0 || context?.__stx_force_signals === !0 || Array.isArray(context?.__stx_client_signal_names) || usesSignalsInScript(template), clientSignalNames = new Set(Array.isArray(context?.__stx_client_signal_names) ? context.__stx_client_signal_names : []), preservedClientExpressions = new Set(Array.isArray(context?.__stx_preserved_client_expressions) ? context.__stx_preserved_client_expressions : []);
+  const hasSignals = context?.__stx_signals_gate === !0 || usesSignalsInScript(template), clientSignalNames = new Set(Array.isArray(context?.__stx_client_signal_names) ? context.__stx_client_signal_names : []), preservedClientExpressions = new Set(Array.isArray(context?.__stx_preserved_client_expressions) ? context.__stx_preserved_client_expressions : []);
   output = output.replace(/\{\{\{([\s\S]*?)\}\}\}/g, (match, expr, offset) => {
     try {
       const value = evaluateExpression(expr, context);

package/dist/framework-composables.d.ts

@@ -0,0 +1,41 @@
+/** Clear the cache. Dev HMR calls this when composables change on disk. */
+export declare function clearFrameworkComposableCache(): void;
+/**
+ * Choose which files in the composables directory carry runtime code.
+ *
+ * This ran against a `*.ts` glob, which is only ever right when stx runs from
+ * `src/`. A released package runs from `dist/`, where the directory holds 37
+ * `.js` files and 37 `.d.ts` files and not one plain `.ts` — so every file the
+ * bundler opened was type-only, nothing was ever emitted, and every requested
+ * name was reported as unbundlable. The one configuration where the old glob
+ * worked is the one the repo's own tests run in, which is why it never showed
+ * up here (stacksjs/stx#1832).
+ *
+ * Two compounding details, both fixed by going through this function:
+ *
+ *  - `.d.ts` can never contribute runtime code, so it is excluded outright
+ *    rather than left to be caught downstream.
+ *  - The barrel exclusion compared `endsWith('index.ts')`, and `'index.d.ts'`
+ *    does not end with that. The one file the filter existed to skip was the
+ *    only one it let through — and being a barrel of `export … from …`, it was
+ *    also the one shape the export-stripping below cannot parse.
+ *
+ * Exported so the selection can be tested against a dist-shaped listing without
+ * a built package.
+ */
+export declare function selectComposableFiles(files: string[]): string[];
+/**
+ * Which framework composables does this source actually call?
+ *
+ * Restricted to the server-only set, so a page calling `useLocalStorage` (which
+ * the runtime provides) never drags in a module copy.
+ */
+export declare function referencedFrameworkComposables(source: string): string[];
+/**
+ * Build a script exposing `names` on `window.stx` and as bare globals.
+ *
+ * Returns null when nothing is needed.
+ */
+export declare function getFrameworkComposableScript(source: string, composablesDir?: string): Promise<string | null>;
+/** @internal test-only — declare names the runtime provides. */
+export declare function __setRuntimeOwnedForTest(names: string[]): void;

package/dist/framework-composables.js

@@ -0,0 +1,115 @@
+import path from "node:path";
+import { getPublicEnvDefine } from "./public-env.js";
+import { SERVER_ONLY_COMPOSABLES } from "./unresolved-identifiers.js";
+const _cache = new Map, RUNTIME_OWNED = new Set, SERVER_ONLY = new Set(SERVER_ONLY_COMPOSABLES);
+export function clearFrameworkComposableCache() {
+  _cache.clear();
+}
+export function selectComposableFiles(files) {
+  const byBase = new Map;
+  for (const file of files) {
+    const base = path.basename(file);
+    if (base.endsWith(".d.ts"))
+      continue;
+    const stem = base.replace(/\.[jt]s$/, "");
+    if (stem === "index")
+      continue;
+    if (stem === base)
+      continue;
+    const existing = byBase.get(stem);
+    if (existing && !existing.endsWith(".js"))
+      continue;
+    byBase.set(stem, file);
+  }
+  return [...byBase.values()].sort();
+}
+function declaresLocally(source, name) {
+  const escaped = name.replace(/[$()*+.?[\\\]^{|}-]/g, "\\$&");
+  return new RegExp(`(?:^|[^\\w$.])(?:const|let|var|function|class)\\s+${escaped}\\b`).test(source);
+}
+export function referencedFrameworkComposables(source) {
+  if (!source)
+    return [];
+  const authored = source.replace(/<script\b[^>]*\bdata-stx-runtime\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<script\b[^>]*\bdata-stx-framework-composables\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<script\b[^>]*\bdata-stx-stores\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<script\b[^>]*\bdata-stx-composables\b[^>]*>[\s\S]*?<\/script>/gi, ""), found = [];
+  for (const name of SERVER_ONLY) {
+    if (RUNTIME_OWNED.has(name))
+      continue;
+    const escaped = name.replace(/[$()*+.?[\\\]^{|}-]/g, "\\$&");
+    if (new RegExp(`(^|[^\\w$.])${escaped}\\s*\\(`).test(authored))
+      found.push(name);
+  }
+  return found.sort();
+}
+export async function getFrameworkComposableScript(source, composablesDir) {
+  const names = referencedFrameworkComposables(source);
+  if (names.length === 0)
+    return null;
+  const dir = composablesDir ?? path.join(import.meta.dir, "composables"), key = `${dir}\x00${names.join(",")}`, cached = _cache.get(key);
+  if (cached !== void 0)
+    return cached || null;
+  const transpiler = new Bun.Transpiler({ loader: "ts", target: "browser", define: getPublicEnvDefine() }), wanted = new Set(names), chunks = [], emitted = new Set;
+  let files = [];
+  try {
+    const glob = new Bun.Glob("*.{ts,js}");
+    for await (const file of glob.scan({ cwd: dir, absolute: !0 }))
+      files.push(file);
+  } catch {
+    _cache.set(key, "");
+    return null;
+  }
+  files = selectComposableFiles(files);
+  for (const file of files) {
+    let code;
+    try {
+      code = await Bun.file(file).text();
+    } catch {
+      continue;
+    }
+    let exports = [];
+    try {
+      exports = transpiler.scan(code).exports.filter((n) => n !== "default");
+    } catch {
+      continue;
+    }
+    if (!exports.some((n) => wanted.has(n)))
+      continue;
+    try {
+      code = code.replace(/^import\s+.*from\s+['"][^'"]+['"]\s*;?\s*$/gm, "");
+      code = code.replace(/^import\s+type\s+.*$/gm, "");
+      code = code.replace(/^export\s+\*\s+(?:as\s+\w+\s+)?from\s*['"][^'"]+['"]\s*;?\s*$/gm, "");
+      code = code.replace(/^export\s+(?:type\s+)?\{[\s\S]*?\}\s*(?:from\s*['"][^'"]+['"]\s*)?;?\s*$/gm, "");
+      code = code.replace(/^export\s+default\s+/gm, "");
+      code = code.replace(/^export\s+(?=(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:function|class|const|let|var|type|interface|enum)\b)/gm, "");
+      chunks.push(`// ${path.basename(file).replace(/\.[jt]s$/, "")}
+${transpiler.transformSync(code).trim()}`);
+      for (const name of exports)
+        emitted.add(name);
+    } catch (error) {
+      console.warn(`[stx] framework composable ${path.basename(file)} could not be bundled:`, error);
+    }
+  }
+  const missing = names.filter((n) => !emitted.has(n) && !declaresLocally(source, n));
+  if (missing.length > 0)
+    console.warn(`[stx] could not bundle ${missing.join(", ")} from @stacksjs/stx/composables \u2014 ` + "calls to them will throw ReferenceError in the browser. Import them explicitly so the bundler inlines them, or use a runtime equivalent from window.stx.");
+  if (chunks.length === 0) {
+    _cache.set(key, "");
+    return null;
+  }
+  const assignments = [...emitted].map((name) => `  try { if (!(${JSON.stringify(name)} in __s)) { __s[${JSON.stringify(name)}] = ${name}; if (!(${JSON.stringify(name)} in window)) window[${JSON.stringify(name)}] = ${name}; } } catch (e) {}`).join(`
+`), script = `<script data-stx-framework-composables>
+;(function(){
+  var __s = window.stx = window.stx || {};
+${chunks.join(`
+
+`)}
+${assignments}
+})();
+</script>`;
+  _cache.set(key, script);
+  return script;
+}
+export function __setRuntimeOwnedForTest(names) {
+  RUNTIME_OWNED.clear();
+  for (const n of names)
+    RUNTIME_OWNED.add(n);
+}

package/dist/hot-reload.js

@@ -198,8 +198,14 @@ catch (e) {
             console.log('[stx] Reloading...', msg.path || '');
             // Use SPA router for progressive update instead of full page reload.
             // Falls back to hard reload only when the router isn't available.
-            if (typeof window.navigate === 'function') {
-              window.navigate(window.location.pathname + window.location.search, false, true);
+            // Call the ROUTER directly, not window.navigate: the runtime helper
+            // takes (url, options) and silently dropped the third argument, so
+            // force never arrived and the same-URL early return made this a
+            // no-op on every page that had the router (#1807). pushState=false
+            // keeps the address bar untouched (this is a reload, not a
+            // navigation) and force=true bypasses the early return.
+            if (window.stxRouter && typeof window.stxRouter.navigate === 'function') {
+              window.stxRouter.navigate(window.location.pathname + window.location.search, false, true);
             } else {
               window.location.reload();
             }

package/dist/includes.js

@@ -560,6 +560,7 @@ export async function processIncludes(template, context, filePath, options, depe
       workingContent = workingContent.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "");
       workingContent = workingContent.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "");
       const includeContext = { ...context };
+      includeContext.__stx_signals_gate = usesSignalsInScript(partialContent);
       for (const [key, value] of Object.entries(localVars))
         includeContext[key] = value;
       const scriptRegex = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi, scriptMatches = [...partialContent.matchAll(scriptRegex)];
@@ -630,8 +631,7 @@ export async function processIncludes(template, context, filePath, options, depe
       const { processLoops } = await import("./loops.js");
       let processedContent = processLoops(workingContent, includeContext, includeFilePath);
       processedContent = processConditionals(processedContent, includeContext, includeFilePath);
-      const partialHasSignals = usesSignalsInScript(partialContent);
-      processedContent = processExpressions(processedContent, includeContext, includeFilePath, { forceSignals: partialHasSignals });
+      processedContent = processExpressions(processedContent, includeContext, includeFilePath);
       if (preservedStyle)
         processedContent += `
 ` + preservedStyle;

package/dist/isolated-build.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Run `build` over `entrypoints`, falling back to one-at-a-time on failure.
+ *
+ * @param entrypoints absolute paths to build
+ * @param build performs a Bun.build over the given subset; should throw or
+ * reject on failure, which is what Bun.build does by default
+ */
+export declare function buildIsolatingFailures(entrypoints: string[], build: (subset: string[]) => Promise<unknown>): Promise<IsolatedBuildResult>;
+export declare interface IsolatedBuildResult {
+  succeeded: string[]
+  failed: Array<{ entrypoint: string, error: string }>
+}

package/dist/isolated-build.js

@@ -0,0 +1,18 @@
+import { formatBuildFailure } from "./build-message.js";
+export async function buildIsolatingFailures(entrypoints, build) {
+  if (entrypoints.length === 0)
+    return { succeeded: [], failed: [] };
+  try {
+    await build(entrypoints);
+    return { succeeded: [...entrypoints], failed: [] };
+  } catch {}
+  const succeeded = [], failed = [];
+  for (const entrypoint of entrypoints)
+    try {
+      await build([entrypoint]);
+      succeeded.push(entrypoint);
+    } catch (error) {
+      failed.push({ entrypoint, error: formatBuildFailure(error, entrypoint) });
+    }
+  return { succeeded, failed };
+}

package/dist/plugin-system.d.ts

@@ -89,7 +89,7 @@ export declare interface StxPlugin {
   registerFilters?: () => Record<string, (value: unknown, ...args: unknown[]) => unknown>
   onRegister?: (options: StxOptions) => void | Promise<void>
   onUnregister?: () => void | Promise<void>
-  components?: string
+  components?: string | string[]
   functions?: string
   stores?: string
   pages?: string

package/dist/process.js

@@ -7,7 +7,7 @@ import { processTemplateBindings } from "./reactive-bindings.js";
 import { injectAnalytics } from "./analytics.js";
 import { injectHeatmap } from "./heatmap.js";
 import { processAnimationDirectives } from "./animation.js";
-import { processEventDirectives } from "./events.js";
+import { generateRuntimeScript, processEventDirectives } from "./events.js";
 import { extractBridgeData, processClientScript } from "./client-script.js";
 import { processReactiveDirectives } from "./reactive.js";
 import { processMarkdownFileDirectives } from "./assets.js";
@@ -36,9 +36,9 @@ import { processServerBindings } from "./server-bindings.js";
 import { processVueTemplate } from "./vue-template.js";
 import { processDynamicComponents } from "./dynamic-components.js";
 import { dedupeScopedStyles, processScopedStyles } from "./style-scoping.js";
-import { injectColorModeBootScript } from "./color-mode-boot.js";
+import { injectColorModeBootScript, normalizeCriticalHeadOrder } from "./color-mode-boot.js";
 import { injectBuildId } from "./build-id.js";
-import { applyHtmlAttrs, ensureDocumentShell, hasDocumentShell, injectCloakStyle, injectConfigHeadTags, mergeHtmlAttrs } from "./document-shell.js";
+import { applyHtmlAttrs, ensureDocumentShell, hasDocumentShell, injectCloakStyle, injectConfigHeadTags, mergeHtmlAttrs, startsDocument } from "./document-shell.js";
 import { hasSignalsSyntax, convertSignalDirectivesToAttributes, convertSignalLoopsToAttributes, preEvalLiteralReactiveIfs, processSignals } from "./signal-processing.js";
 import { processComponents } from "./component-renderer.js";
 import { processInlineAssets } from "./inline-assets.js";
@@ -51,6 +51,7 @@ import { deriveLayoutGroup } from "stx-router/layout-metadata";
 import { initializeComponentClientFactories, injectComponentClientFactories } from "./component-client-factories.js";
 import { importOnce } from "./lazy-module.js";
 export { injectRouterScript } from "./runtime-injection.js";
+import { injectSignalsRuntime, outputNeedsSignalsRuntime, pageShipsSignalsRuntime } from "./runtime-injection.js";
 export { processJsonDirective, processOnceDirective } from "./misc-directives.js";
 export { validateClientScript } from "./script-validation.js";
 const PARENT_PLACEHOLDER = "<!--PARENT_CONTENT_PLACEHOLDER-->";
@@ -246,6 +247,8 @@ function placeSignalsRuntimeBeforeScripts(html) {
 export async function processDirectives(template, context, filePath, options, dependencies) {
   if (options.ssr === !1 && !options.autoShell && options.buildMode === "spa")
     return template;
+  if (context.__stx_signals_gate === void 0)
+    context.__stx_signals_gate = usesSignalsInScript(template);
   const isTopLevel = !context.__stxProcessingDepth;
   if (isTopLevel)
     initializeComponentClientFactories(context);
@@ -269,7 +272,7 @@ export async function processDirectives(template, context, filePath, options, de
           pageHeadTitle = rawTitleMatch[1].trim();
           pageHeadRaw = pageHeadRaw.replace(rawTitleMatch[0], "").trim();
         }
-        const sectionTitle = context.__sections?.title, pageTitle = runtimeHead.title || pageHeadTitle || sectionTitle, headConfig = {
+        const sectionTitle = context.__sections?.title, pageTitle = runtimeHead.title || pageHeadTitle || sectionTitle, titleIsHtml = !runtimeHead.title && (!!pageHeadTitle || !!sectionTitle), headConfig = {
           ...baseHeadConfig,
           ...pageTitle && { title: pageTitle },
           meta: [...baseHeadConfig.meta || [], ...runtimeHead.meta || []],
@@ -281,6 +284,7 @@ export async function processDirectives(template, context, filePath, options, de
           ...runtimeHead.bodyAttrs && { bodyAttrs: { ...baseHeadConfig.bodyAttrs || {}, ...runtimeHead.bodyAttrs } }
         }, alreadyShelled = hasDocumentShell(result);
         result = ensureDocumentShell(result, headConfig, {
+          ...titleIsHtml && { titleIsHtml: !0 },
           ...options.app?.colorMode && { colorMode: options.app.colorMode }
         });
         if (alreadyShelled) {
@@ -290,7 +294,7 @@ export async function processDirectives(template, context, filePath, options, de
         const layoutComment = result.match(/<!-- stx-layout: ([^ ]+) -->/);
         if (layoutComment && result.includes("<head")) {
           const layoutName = layoutComment[1], layoutGroup = deriveLayoutGroup(layoutName);
-          result = result.replace("<head>", `<head>
+          result = result.replace(/<head\b[^>]*>/i, (match) => `${match}
   <meta name="stx-layout" content="${escapeHtmlAttribute(layoutName)}">
   <meta name="stx-layout-group" content="${escapeHtmlAttribute(layoutGroup)}">`);
         }
@@ -319,6 +323,16 @@ export async function processDirectives(template, context, filePath, options, de
 ` + storeTag + result.slice(runtime.end);
           }
         } catch {}
+      if (isTopLevel)
+        try {
+          const { getFrameworkComposableScript } = await importOnce("stx/framework-composables", () => import("./framework-composables.js")), frameworkScript = await getFrameworkComposableScript(result);
+          if (frameworkScript) {
+            const anchor = findScriptBlockByAttribute(result, "data-stx-stores") || findScriptBlockByAttribute(result, "data-stx-runtime");
+            if (anchor)
+              result = result.slice(0, anchor.end) + `
+` + frameworkScript + result.slice(anchor.end);
+          }
+        } catch {}
       if (isTopLevel)
         try {
           const { getComposableScript } = await importOnce("stx/composable-loader", () => import("./composable-loader.js")), resolvedComposablesDir = options.composablesDir, composableCode = await getComposableScript(resolvedComposablesDir);
@@ -329,6 +343,8 @@ export async function processDirectives(template, context, filePath, options, de
 ` + composableTag + result.slice(anchor.end);
           }
         } catch {}
+      if (isTopLevel)
+        result = normalizeCriticalHeadOrder(result);
       if (isTopLevel && context.__stx_inject_css !== !1)
         result = await injectCrosswindCSS(result, void 0, options.buildMode === "serve");
       if (isTopLevel)
@@ -384,8 +400,8 @@ async function processDirectivesInternal(template, context, filePath, options, d
     output = output.replace(/@(?:layout|extends)\(\s*['"]([^'"]+)['"]\s*\)/g, "");
   }
   if (!layoutPath && !hasNoLayout && opts.defaultLayout) {
-    const hasDoctype = /<!DOCTYPE\s/i.test(output), hasSections = /@section\s*\(/.test(output);
-    if (!hasDoctype || hasSections) {
+    const isDocument = startsDocument(output), hasSections = /@section\s*\(/.test(output);
+    if (!isDocument || hasSections) {
       let autoLayoutPath = "", searchDir = path.dirname(filePath);
       const rootDir = opts.layoutsDir ? path.dirname(opts.layoutsDir) : process.cwd();
       for (let i = 0;i < 20; i++) {
@@ -602,8 +618,8 @@ async function processOtherDirectives(template, context, filePath, options, depe
   const { processStreamDirectives } = await importOnce("stx/streaming", () => import("./streaming.js"));
   output = processStreamDirectives(output, context);
   output = processLoops(output, context, filePath, opts);
-  output = await processComponents(output, context, filePath, opts, dependencies);
   output = await processDynamicComponents(output, context, filePath, opts, dependencies);
+  output = await processComponents(output, context, filePath, opts, dependencies);
   output = processAnimationDirectives(output, context, filePath, opts);
   const { processDeferDirectives } = await importOnce("stx/defer", () => import("./defer.js"));
   output = processDeferDirectives(output, context, filePath);
@@ -739,7 +755,7 @@ ${snippet}
   }
   const hasClientScripts = /<script\b(?![^>]*\bserver\b)[^>]*>[\s\S]*?<\/script>/i.test(output), hasStxUsage = /\bSTX\.\w+/.test(output), alreadyHasRuntime = /window\.STX\s*=/.test(output);
   if (hasClientScripts && hasStxUsage && !alreadyHasRuntime) {
-    const runtimeScript = `<script data-stx-scoped>
+    const runtimeScript = `<script data-stx-scoped data-stx-run="once">
 ${generateLifecycleRuntime()}
 </script>`;
     if (output.includes("</head>")) {
@@ -789,12 +805,26 @@ ${runtimeScript}`);
   for (const { match, attrs, content } of clientScriptMatches) {
     clientScriptsTransformed = !0;
     let processedContent = content;
-    validateClientScript(content, filePath, options.strict);
+    validateClientScript(content, filePath, options.strict, context.__originalFilePath);
     const scriptResult = await processClientScript(content, { eventBindings, attrs, hasColonDirectives, templateContent: template, filePath, projectRoot: process.cwd(), production: options.buildMode === "compile", serverData });
     output = output.replace(match, () => scriptResult);
   }
   if (clientScriptsTransformed)
     context.__stx_event_bindings = [];
+  if (!clientScriptsTransformed && context.__stxProcessingDepth === 1) {
+    const orphaned = context.__stx_event_bindings || [];
+    if (orphaned.length > 0) {
+      const script = generateRuntimeScript(orphaned);
+      if (script) {
+        const bodyIdx = output.lastIndexOf("</body>");
+        output = bodyIdx === -1 ? output + script : output.slice(0, bodyIdx) + script + `
+` + output.slice(bodyIdx);
+      }
+      context.__stx_event_bindings = [];
+    }
+  }
+  if (!pageShipsSignalsRuntime(output) && outputNeedsSignalsRuntime(output))
+    output = await injectSignalsRuntime(output, opts);
   if (opts.csp?.enabled && opts.csp.useNonce && typeof context.cspNonce === "string")
     output = addNonceToInlineContent(output, context.cspNonce);
   return output;

package/dist/production-server.js

@@ -4,6 +4,7 @@ import { serve } from "bun";
 import { loadManifest } from "./manifest.js";
 import { hydrateTemplateStream, hydrateFragment } from "./template-hydrator.js";
 import { extractLayoutMetadata } from "./app-shell.js";
+import { pageShipsSignalsRuntime } from "./runtime-injection.js";
 import { patternToRegex } from "stx-router";
 const MIME_TYPES = {
   ".js": "application/javascript",
@@ -41,12 +42,13 @@ export async function startProductionServer(options = {}) {
     process.exit(1);
   }
   console.log(`[stx] Production server loading ${manifest.routes.length} routes...`);
-  const compiledTemplates = new Map, fragmentCache = new Map, layoutMetadataCache = new Map;
+  const compiledTemplates = new Map, fragmentCache = new Map, layoutMetadataCache = new Map, runtimeCache = new Map;
   for (const route of manifest.routes)
     try {
       const compiledPath = path.join(outputDir, route.compiledPath), compiled = JSON.parse(await Bun.file(compiledPath).text());
       compiledTemplates.set(route.pattern, compiled);
       layoutMetadataCache.set(route.pattern, extractLayoutMetadata(compiled.html));
+      runtimeCache.set(route.pattern, pageShipsSignalsRuntime(compiled.html));
       const fragmentPath = path.join(outputDir, route.fragmentPath);
       if (await Bun.file(fragmentPath).exists())
         fragmentCache.set(route.pattern, await Bun.file(fragmentPath).text());
@@ -129,6 +131,7 @@ export async function startProductionServer(options = {}) {
             headers: {
               "Content-Type": "text/html",
               "X-STX-Fragment": "true",
+              ...runtimeCache.has(matchedRoute.pattern) ? { "X-STX-Runtime": runtimeCache.get(matchedRoute.pattern) ? "true" : "false" } : {},
               ...layoutMetadata ? {
                 "X-STX-Layout": layoutMetadata.layout,
                 "X-STX-Layout-Group": layoutMetadata.group

package/dist/prop-sentinels.d.ts

@@ -0,0 +1,31 @@
+/** Is this value the bare-boolean-attribute marker? */
+export declare function isBooleanAttributeSentinel(value: unknown): boolean;
+/**
+ * Last-resort guard for anything about to be written into a response.
+ *
+ * Nothing should reach output carrying a NUL, but the cost of one escaping is
+ * an invalid document and a silent grep, which is far worse than the cost of
+ * this check.
+ */
+export declare function stripControlChars(value: string): string;
+/**
+ * Sentinel values used while resolving component props.
+ *
+ * A leaf module on purpose: `component-renderer.ts` imports `./builtins`, so a
+ * builtin importing the renderer back would be a cycle. Both sides import this
+ * instead.
+ *
+ * @module prop-sentinels
+ */
+/**
+ * Marks a prop that was written as a bare HTML boolean attribute — `<X open>`
+ * rather than `<X open="true">`.
+ *
+ * It carries a leading NUL precisely so it cannot collide with an author-written
+ * value, which also means it must never survive into a response: a NUL byte
+ * makes the document invalid UTF-8, and tools treat the file as binary. `grep`
+ * in particular goes SILENT on it — not zero matches, no output at all — so a
+ * verification step that greps rendered HTML returns an empty string and reads
+ * as a pass (stacksjs/stx#1816).
+ */
+export declare const BOOLEAN_ATTRIBUTE_SENTINEL: '\0stx-boolean-attribute';

package/dist/prop-sentinels.js

@@ -0,0 +1,7 @@
+export const BOOLEAN_ATTRIBUTE_SENTINEL = "\x00stx-boolean-attribute";
+export function isBooleanAttributeSentinel(value) {
+  return value === BOOLEAN_ATTRIBUTE_SENTINEL;
+}
+export function stripControlChars(value) {
+  return value.indexOf("\x00") === -1 ? value : value.replace(/\0/g, "");
+}