@stacksjs/stx 0.2.152 → 0.2.153

package/dist/dev-server/serve-app.js

@@ -11,6 +11,7 @@ import {
   stopHmrServer
 } from "../hot-reload.js";
 import { partialsCache } from "../includes.js";
+import { BUILD_ID_HEADER, getBuildId } from "../build-id.js";
 import { stateDir } from "../state-dir.js";
 import { plugin as stxPlugin } from "../plugin.js";
 import { createRouter, matchRoute, formatRoutes, findErrorPage } from "../router.js";
@@ -74,14 +75,16 @@ function serveStaticFile(filePath) {
 export async function serveApp(appDir = ".", options = {}) {
   const port = options.port || 3000, watch = options.watch !== !1, hotReload = options.hotReload !== !1 && watch;
   let hmrServer = null, actualHmrPort = options.hmrPort || port + 1;
-  const absoluteAppDir = path.resolve(appDir), { loadStxConfig } = await import("../index.js"), projectConfig = await loadStxConfig(absoluteAppDir), stxRoot = projectConfig.root && projectConfig.root !== "." ? path.join(absoluteAppDir, projectConfig.root) : absoluteAppDir, pagesDirName = projectConfig.pagesDir || "pages", pagesDir = path.join(stxRoot, pagesDirName);
+  const absoluteAppDir = path.resolve(appDir), { loadStxConfig } = await import("../index.js"), projectConfig = await loadStxConfig(absoluteAppDir), stxRoot = projectConfig.root && projectConfig.root !== "." ? path.join(absoluteAppDir, projectConfig.root) : absoluteAppDir, pagesDirName = options.pagesDir || projectConfig.pagesDir || "pages", pagesDir = path.join(stxRoot, pagesDirName);
   if (!fs.existsSync(pagesDir)) {
-    console.error(`${colors.red}Error: No '${pagesDirName}' directory found in ${colors.bright}${stxRoot}${colors.reset}`);
-    console.log(`${colors.dim}Create a ${pagesDirName}/ directory with .stx files to define your routes.${colors.reset}`);
-    console.log(`${colors.dim}Example: ${pagesDirName}/index.stx for the homepage.${colors.reset}`);
+    console.error(`${colors.red}Error: No '${pagesDirName}' directory found${colors.reset}`);
+    console.log(`${colors.dim}Looked in: ${colors.bright}${pagesDir}${colors.reset}`);
+    console.log(`${colors.dim}Run stx dev from the app directory, pass it as an argument (stx dev <dir>),${colors.reset}`);
+    console.log(`${colors.dim}point at another directory with --pages <dir>, or set pagesDir in stx.config.ts.${colors.reset}`);
+    console.log(`${colors.dim}Starting fresh? Create ${pagesDirName}/index.stx for the homepage.${colors.reset}`);
     return !1;
   }
-  const routes = createRouter(stxRoot);
+  const routes = createRouter(stxRoot, { pagesDir: pagesDirName });
   if (routes.length === 0) {
     console.error(`${colors.red}Error: No page files found in ${colors.bright}${pagesDir}${colors.reset}`);
     return !1;
@@ -447,6 +450,7 @@ export async function serveApp(appDir = ".", options = {}) {
                 "X-STX-Layout": layoutMetadata.layout,
                 "X-STX-Layout-Group": layoutMetadata.group,
                 ...pageTitle && { "X-STX-Title": encodeURIComponent(pageTitle) },
+                [BUILD_ID_HEADER]: getBuildId(),
                 "Cache-Control": "no-store, no-cache, must-revalidate"
               }
             });

package/dist/dev-server/types.d.ts

@@ -37,8 +37,14 @@ export declare const MIME_TYPES: {
 };
 /**
  * Default dev server options
+ *
+ * `pagesDir` is excluded rather than defaulted: it has no static default. Its
+ * absence is meaningful — it's what lets `stx.config.ts` `pagesDir` apply.
+ * Baking `'pages'` in here would override a configured `views/` for anyone who
+ * spread these defaults (#1781). serveApp resolves it as
+ * option → config → `'pages'`.
  */
-export declare const DEFAULT_DEV_OPTIONS: Required<Omit<DevServerOptions, 'stxOptions' | 'markdown'>>;
+export declare const DEFAULT_DEV_OPTIONS: Required<Omit<DevServerOptions, 'stxOptions' | 'markdown' | 'pagesDir'>>;
 /**
  * Markdown rendering options
  */
@@ -59,6 +65,7 @@ export declare interface DevServerOptions {
   watch?: boolean
   native?: boolean
   titlebarHidden?: boolean
+  pagesDir?: string
   stxOptions?: StxOptions
   markdown?: MarkdownOptions
   cache?: boolean

package/dist/document-shell.d.ts

@@ -1,5 +1,42 @@
 import type { AppHeadConfig } from './types/config-types';
 import type { ColorModeBootConfig } from './color-mode-boot';
+/**
+ * Build the attribute string for the shell's `<html>` open tag.
+ *
+ * `htmlAttrs.lang` wins over the `lang` option so `useHead({ htmlAttrs: { lang } })`
+ * is not emitted twice (two `lang=` attributes on one element is a parse error
+ * that browsers resolve by keeping the first — i.e. silently ignoring the
+ * more specific one).
+ *
+ * @param htmlAttrs - Attributes from config `app.head.htmlAttrs` / `useHead()`
+ * @param lang - The `lang` option, used unless `htmlAttrs.lang` overrides it
+ * @returns Leading-space-prefixed attribute string, e.g. ` lang="en" class="marketing"`
+ */
+export declare function buildHtmlAttrs(htmlAttrs?: Record<string, string>, lang?: string): string;
+/**
+ * Merge a page's `htmlAttrs` over the config's.
+ *
+ * Per-key override, except `class`, which unions: a global
+ * `app.head.htmlAttrs.class` (`h-full`, a font class, …) shouldn't silently
+ * vanish the moment one page adds a class of its own. Same rule as
+ * `applyHtmlAttrs`, so "class unions, everything else overrides" holds at every
+ * point htmlAttrs are combined.
+ */
+export declare function mergeHtmlAttrs(base?: Record<string, string>, override?: Record<string, string>): Record<string, string>;
+/**
+ * Merge `htmlAttrs` into a document that rendered its OWN `<html>` tag.
+ *
+ * `generateDocumentShell` only runs for pages without a shell, so a page or
+ * layout that writes `<html>` itself — the common case, and what SSG emits —
+ * would otherwise drop `useHead({ htmlAttrs })` entirely. Whether the attribute
+ * lands should not depend on who wrote the document element.
+ *
+ * `class` unions with what the template already put there (the template's own
+ * classes are never dropped); every other attribute is overwritten. Only the
+ * classes stx contributed are recorded in the marker, so an SPA navigation
+ * removes those and leaves the hand-written ones in place.
+ */
+export declare function applyHtmlAttrs(html: string, htmlAttrs?: Record<string, string>): string;
 /**
  * Insert the inline x-cloak <style> before </head> if a head exists and the
  * style isn't already present. Idempotent (guards on the data-stx-cloak
@@ -106,3 +143,21 @@ export declare function ensureDocumentShell(html: string, headConfig?: AppHeadCo
  * emission.
  */
 export declare const CLOAK_STYLE: '<style data-stx-cloak>[x-cloak]{display:none !important}</style>';
+/**
+ * Markers recording which `<html>` attributes stx itself wrote from `htmlAttrs`
+ * (stacksjs/stx#1798).
+ *
+ * The router needs them to reconcile the root element across an SPA layout
+ * change. It cannot just diff `<html>` against the incoming document: by then
+ * the color-mode boot script has added its own `dark` class / `data-theme`, and
+ * `animation.ts` has added `data-reduced-motion`, none of which exist in the
+ * server response — a blind diff would strip them on every navigation and
+ * flash the wrong theme. These say exactly what stx put there, so the router
+ * can remove precisely that much and leave runtime state alone.
+ *
+ * `class` is tracked separately because it is the one attribute that gets
+ * *merged* into at runtime, so it has to be reconciled token-by-token rather
+ * than replaced wholesale.
+ */
+export declare const HTML_ATTRS_MARKER: 'data-stx-html-attrs';
+export declare const HTML_CLASS_MARKER: 'data-stx-html-class';

package/dist/document-shell.js

@@ -1,5 +1,104 @@
 import { generateColorModeBootScript } from "./color-mode-boot.js";
-export const CLOAK_STYLE = "<style data-stx-cloak>[x-cloak]{display:none !important}</style>";
+export const CLOAK_STYLE = "<style data-stx-cloak>[x-cloak]{display:none !important}</style>", HTML_ATTRS_MARKER = "data-stx-html-attrs", HTML_CLASS_MARKER = "data-stx-html-class";
+const SAFE_ATTR_NAME = /^[A-Za-z_:][\w:.-]*$/;
+function escapeAttr(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export function buildHtmlAttrs(htmlAttrs = {}, lang = "en") {
+  const rest = [], managed = [];
+  let className = "", resolvedLang = lang;
+  for (const [rawName, value] of Object.entries(htmlAttrs || {})) {
+    if (value == null)
+      continue;
+    const name = rawName.trim();
+    if (!SAFE_ATTR_NAME.test(name))
+      continue;
+    const lower = name.toLowerCase();
+    if (lower === "lang") {
+      resolvedLang = String(value);
+      continue;
+    }
+    if (lower === "class") {
+      className = String(value).trim();
+      continue;
+    }
+    rest.push(` ${name}="${escapeAttr(String(value))}"`);
+    managed.push(name);
+  }
+  let out = ` lang="${escapeAttr(resolvedLang)}"`;
+  if (className)
+    out += ` class="${escapeAttr(className)}"`;
+  out += rest.join("");
+  if (className)
+    out += ` ${HTML_CLASS_MARKER}="${escapeAttr(className)}"`;
+  if (managed.length)
+    out += ` ${HTML_ATTRS_MARKER}="${escapeAttr(managed.join(" "))}"`;
+  return out;
+}
+export function mergeHtmlAttrs(base = {}, override = {}) {
+  const merged = { ...base, ...override };
+  if (base.class && override.class) {
+    const tokens = base.class.split(/\s+/).filter(Boolean);
+    for (const token of override.class.split(/\s+/).filter(Boolean))
+      if (!tokens.includes(token))
+        tokens.push(token);
+    merged.class = tokens.join(" ");
+  }
+  return merged;
+}
+export function applyHtmlAttrs(html, htmlAttrs = {}) {
+  if (!htmlAttrs || Object.keys(htmlAttrs).length === 0)
+    return html;
+  const openTag = html.match(/<html\b([^>]*)>/i);
+  if (!openTag)
+    return html;
+  const existing = {}, order = [], attrRe = /([A-Za-z_:][\w:.-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+  let m;
+  while ((m = attrRe.exec(openTag[1])) !== null) {
+    const name = m[1];
+    if (!(name in existing))
+      order.push(name);
+    existing[name] = m[2] ?? m[3] ?? m[4] ?? "";
+  }
+  const addedClasses = [], managed = [];
+  for (const [rawName, value] of Object.entries(htmlAttrs)) {
+    if (value == null)
+      continue;
+    const name = rawName.trim();
+    if (!SAFE_ATTR_NAME.test(name))
+      continue;
+    const lower = name.toLowerCase();
+    if (lower === "class") {
+      const present = (existing.class || "").split(/\s+/).filter(Boolean);
+      for (const token of String(value).split(/\s+/).filter(Boolean))
+        if (!present.includes(token)) {
+          present.push(token);
+          addedClasses.push(token);
+        }
+      if (!("class" in existing))
+        order.push("class");
+      existing.class = present.join(" ");
+      continue;
+    }
+    if (!(name in existing))
+      order.push(name);
+    existing[name] = String(value);
+    if (lower !== "lang")
+      managed.push(name);
+  }
+  if (addedClasses.length) {
+    if (!(HTML_CLASS_MARKER in existing))
+      order.push(HTML_CLASS_MARKER);
+    existing[HTML_CLASS_MARKER] = addedClasses.join(" ");
+  }
+  if (managed.length) {
+    if (!(HTML_ATTRS_MARKER in existing))
+      order.push(HTML_ATTRS_MARKER);
+    existing[HTML_ATTRS_MARKER] = managed.join(" ");
+  }
+  const rebuilt = order.map((name) => ` ${name}="${escapeAttr(existing[name])}"`).join("");
+  return html.replace(openTag[0], () => `<html${rebuilt}>`);
+}
 export function injectCloakStyle(html) {
   if (html.includes("data-stx-cloak"))
     return html;
@@ -86,6 +185,7 @@ export function generateDocumentShell(content, headConfig = {}, options = {}) {
     link = [],
     script: headScriptTags = [],
     headRaw = "",
+    htmlAttrs = {},
     bodyClass = "",
     bodyAttrs = {}
   } = headConfig, pageTitle = options.title || configTitle, metaTags = [...[
@@ -104,7 +204,7 @@ export function generateDocumentShell(content, headConfig = {}, options = {}) {
       return `  <script>${s.content}</script>`;
     return "";
   }).filter(Boolean).join(`
-`), bodyAttrStr = Object.entries(bodyAttrs).map(([k, v]) => ` ${k}="${v}"`).join(""), bodyClassStr = bodyClass ? ` class="${bodyClass}"` : "", { body: pageBody, hoisted: pageHeadTags } = hoistLeadingHeadTags(content), headParts = [
+`), htmlAttrStr = buildHtmlAttrs(htmlAttrs, lang), bodyAttrStr = Object.entries(bodyAttrs).map(([k, v]) => ` ${k}="${v}"`).join(""), bodyClassStr = bodyClass ? ` class="${bodyClass}"` : "", { body: pageBody, hoisted: pageHeadTags } = hoistLeadingHeadTags(content), headParts = [
     metaTags,
     options.colorMode ? `  ${generateColorModeBootScript(options.colorMode)}` : "",
     `  <title>${pageTitle}</title>`,
@@ -122,7 +222,7 @@ export function generateDocumentShell(content, headConfig = {}, options = {}) {
     options.bodyStack || ""
   ].filter(Boolean);
   return `<!DOCTYPE html>
-<html lang="${lang}">
+<html${htmlAttrStr}>
 <head>
 ${headParts.join(`
 `)}

package/dist/head.js

@@ -194,7 +194,11 @@ export function applyHead(config = currentHead) {
   }
   if (config.htmlAttrs)
     for (const [key, value] of Object.entries(config.htmlAttrs))
-      document.documentElement.setAttribute(key, value);
+      if (key === "class")
+        for (const cls of String(value).split(/\s+/).filter(Boolean))
+          document.documentElement.classList.add(cls);
+      else
+        document.documentElement.setAttribute(key, value);
   if (config.bodyAttrs)
     for (const [key, value] of Object.entries(config.bodyAttrs))
       document.body.setAttribute(key, value);

package/dist/includes.js

@@ -597,7 +597,7 @@ export async function processIncludes(template, context, filePath, options, depe
         if (isSignalScript && !isServerScript) {
           signalScopeId = `stx_scope_${path.basename(includeFilePath, ".stx").replace(/[^a-zA-Z0-9]/g, "_")}_${++scopeIdCounter}`;
           const resolvedContent = transformStoreImports(scriptContent), transformedScript = transformSignalScript(resolvedContent, signalScopeId);
-          preservedScript += `${vendorStyleTags}<script data-stx-scoped>${transformedScript}</script>
+          preservedScript += `${vendorStyleTags}<script data-stx-scoped data-stx-run="always">${transformedScript}</script>
 `;
           continue;
         }
@@ -613,7 +613,7 @@ export async function processIncludes(template, context, filePath, options, depe
           const extraAttrs = scriptAttrs.replace(/\bclient\b/i, "").trim();
           signalScopeId = `stx_scope_${path.basename(includeFilePath, ".stx").replace(/[^a-zA-Z0-9]/g, "_")}_${++scopeIdCounter}`;
           const resolvedContent = transformStoreImports(scriptContent), tail = buildScopeRegistrationTail(resolvedContent, signalScopeId), wrapped = wrapClientScript(resolvedContent, tail);
-          preservedScript += `${vendorStyleTags}<script data-stx-scoped${extraAttrs ? ` ${extraAttrs}` : ""}>${wrapped}</script>
+          preservedScript += `${vendorStyleTags}<script data-stx-scoped data-stx-run="always"${extraAttrs ? ` ${extraAttrs}` : ""}>${wrapped}</script>
 `;
         }
       }

package/dist/index.d.ts

@@ -28,6 +28,22 @@ export { type HydrationOptions } from './hydration';
 // shapes with different field sets; those are kept private to their modules
 // to avoid silently shadowing the user-facing one. Surfaced by stacksjs/stx#1707.
 export { type CookieOptions } from './composables/use-cookie';
+// Storage composables were reachable ONLY via the './composables' subpath, so
+// `import { useLocalStorage } from '@stacksjs/stx'` failed with TS2614 while
+// `state`/`derived` imported fine — and a `functions/` composable (which the
+// docs recommend for anything with persistence) had to reach for the subpath,
+// where the same identifier used to return a different shape. See #1797.
+export {
+  clearStorage,
+  getStorageKeys,
+  getStorageSize,
+  type StorageRef,
+  type StorageType,
+  useLocalStorage,
+  useSessionStorage,
+  useStorage,
+  type UseStorageOptions,
+} from './composables/use-storage';
 export { formatSize, getTotalSize } from './deploy/index';
 export { type ImageRenderResult, type ImageVariant, type ProcessedImage, clearImageCache, getFallbackVariant, getMimeType, groupVariantsByFormat, optimizeImage, processImage } from './image-optimization/index';
 export { type AnalysisResult } from './analyzer';
@@ -62,6 +78,7 @@ export * from './async-components';
 export * from './auth';
 export * from './build';
 export * from './build-assets';
+export * from './build-id';
 export * from './build-mode-detector';
 export * from './build-optimizer';
 export * from './broadcasting';

package/dist/index.js

@@ -1,3 +1,11 @@
+export {
+  clearStorage,
+  getStorageKeys,
+  getStorageSize,
+  useLocalStorage,
+  useSessionStorage,
+  useStorage
+} from "./composables/use-storage.js";
 export { formatSize, getTotalSize } from "./deploy/index.js";
 export { clearImageCache, getFallbackVariant, getMimeType, groupVariantsByFormat, optimizeImage, processImage } from "./image-optimization/index.js";
 export { fileExists } from "./utils.js";
@@ -21,6 +29,7 @@ export * from "./async-components.js";
 export * from "./auth.js";
 export * from "./build.js";
 export * from "./build-assets.js";
+export * from "./build-id.js";
 export * from "./build-mode-detector.js";
 export * from "./build-optimizer.js";
 export * from "./broadcasting.js";

package/dist/process.js

@@ -37,7 +37,8 @@ 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 { ensureDocumentShell, hasDocumentShell, injectCloakStyle, injectConfigHeadTags } from "./document-shell.js";
+import { injectBuildId } from "./build-id.js";
+import { applyHtmlAttrs, ensureDocumentShell, hasDocumentShell, injectCloakStyle, injectConfigHeadTags, mergeHtmlAttrs } 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";
@@ -276,14 +277,16 @@ export async function processDirectives(template, context, filePath, options, de
           script: [...baseHeadConfig.script || [], ...runtimeHead.script || []],
           headRaw: [baseHeadConfig.headRaw, pageHeadRaw].filter(Boolean).join(`
 `),
-          ...runtimeHead.htmlAttrs && { htmlAttrs: { ...baseHeadConfig.htmlAttrs || {}, ...runtimeHead.htmlAttrs } },
+          ...runtimeHead.htmlAttrs && { htmlAttrs: mergeHtmlAttrs(baseHeadConfig.htmlAttrs, runtimeHead.htmlAttrs) },
           ...runtimeHead.bodyAttrs && { bodyAttrs: { ...baseHeadConfig.bodyAttrs || {}, ...runtimeHead.bodyAttrs } }
         }, alreadyShelled = hasDocumentShell(result);
         result = ensureDocumentShell(result, headConfig, {
           ...options.app?.colorMode && { colorMode: options.app.colorMode }
         });
-        if (alreadyShelled)
+        if (alreadyShelled) {
           result = injectConfigHeadTags(result, baseHeadConfig);
+          result = applyHtmlAttrs(result, headConfig.htmlAttrs);
+        }
         const layoutComment = result.match(/<!-- stx-layout: ([^ ]+) -->/);
         if (layoutComment && result.includes("<head")) {
           const layoutName = layoutComment[1], layoutGroup = deriveLayoutGroup(layoutName);
@@ -303,6 +306,7 @@ export async function processDirectives(template, context, filePath, options, de
         const colorModeConfig = options.app?.colorMode;
         if (colorModeConfig)
           result = injectColorModeBootScript(result, colorModeConfig);
+        result = injectBuildId(result);
         result = placeSignalsRuntimeBeforeScripts(result);
       }
       if (isTopLevel)

package/dist/production-builder.js

@@ -5,7 +5,7 @@ import { buildRuntimeAsset, buildRouterAsset } from "./build-assets.js";
 import { compileTemplate } from "./template-compiler.js";
 import { generateManifest, writeManifest } from "./manifest.js";
 import { injectColorModeBootScript } from "./color-mode-boot.js";
-import { ensureDocumentShell } from "./document-shell.js";
+import { applyHtmlAttrs, ensureDocumentShell } from "./document-shell.js";
 import { extractContainerContent } from "./app-shell.js";
 import { injectCrosswindCSS } from "./dev-server/crosswind.js";
 import { loadStxConfig } from "./config.js";
@@ -88,6 +88,8 @@ export async function buildForProduction(options = {}) {
       });
       if (colorModeConfig)
         compiled.html = injectColorModeBootScript(compiled.html, colorModeConfig);
+      if (headConfigDefault.htmlAttrs)
+        compiled.html = applyHtmlAttrs(compiled.html, headConfigDefault.htmlAttrs);
       if (!/<body[^>]*\bdata-stx=/.test(compiled.html)) {
         const dataStxMatch = compiled.html.match(/<(?!body\b)[a-zA-Z][a-zA-Z0-9-]*\b[^>]*?\s(data-stx="[^"]+")[^>]*>/);
         if (dataStxMatch && dataStxMatch[1]) {