@stacksjs/stx 0.2.146 → 0.2.148

package/dist/client-script.d.ts

@@ -43,6 +43,11 @@ export declare function renderVendorStyleTags(styles: VendorCssImport[]): string
  * helpers together with the component, exactly like an explicit user import.
  */
 export declare function injectBrowserCoreAutoImports(code: string): BrowserCoreAutoImportResult;
+/**
+ * Blank out comments and string literals, preserving length and line structure
+ * so offsets still line up, so that identifier detection only ever sees code.
+ */
+export declare function stripCommentsAndLiterals(code: string): string;
 /**
  * Generate destructuring statements for auto-imported symbols
  * These access globals set up by the STX runtime and @stacksjs/browser

package/dist/client-script.js

@@ -250,7 +250,7 @@ const STX_AUTO_IMPORTS = [
   "useIntervalFn"
 ];
 export function injectBrowserCoreAutoImports(code) {
-  const explicitlyImported = new Set;
+  const searchable = stripCommentsAndLiterals(code), explicitlyImported = new Set;
   for (const match of code.matchAll(/^\s*import\s+(?:type\s+)?\{([^}]*)\}\s+from\s+['"][^'"]+['"]\s*;?\s*$/gm))
     for (const specifier of match[1].split(",")) {
       const localName = specifier.trim().split(/\s+as\s+/).pop()?.replace(/^type\s+/, "").trim();
@@ -258,9 +258,9 @@ export function injectBrowserCoreAutoImports(code) {
         explicitlyImported.add(localName);
     }
   const locallyDeclared = new Set;
-  for (const match of code.matchAll(/\b(?:const|let|var|function|class)\s+([A-Za-z_$][\w$]*)/g))
+  for (const match of searchable.matchAll(/\b(?:const|let|var|function|class)\s+([A-Za-z_$][\w$]*)/g))
     locallyDeclared.add(match[1]);
-  for (const match of code.matchAll(/\b(?:const|let|var)\s*\{([^}]*)\}/g))
+  for (const match of searchable.matchAll(/\b(?:const|let|var)\s*\{([^}]*)\}/g))
     for (const binding of match[1].split(",")) {
       const localName = binding.trim().split(/[:=]/).pop()?.trim();
       if (localName)
@@ -269,8 +269,8 @@ export function injectBrowserCoreAutoImports(code) {
   const imports = BROWSER_CORE_IMPORTS.filter((symbol) => {
     if (explicitlyImported.has(symbol) || locallyDeclared.has(symbol))
       return !1;
-    return new RegExp(`\\b${symbol}\\b`).test(code);
-  }), models = detectModelUsage(code).filter((model) => !explicitlyImported.has(model) && !locallyDeclared.has(model));
+    return new RegExp(`\\b${symbol}\\s*\\(`).test(searchable);
+  }), models = detectModelUsage(searchable).filter((model) => !explicitlyImported.has(model) && !locallyDeclared.has(model));
   if (imports.length === 0 && models.length === 0)
     return { code, imports, models };
   return {
@@ -342,6 +342,50 @@ const JS_BUILTINS = new Set([
   "Modal",
   "Intl"
 ]);
+export function stripCommentsAndLiterals(code) {
+  let out = "", i = 0;
+  while (i < code.length) {
+    const two = code.slice(i, i + 2);
+    if (two === "//") {
+      while (i < code.length && code[i] !== `
+`)
+        out += " ", i++;
+      continue;
+    }
+    if (two === "/*") {
+      while (i < code.length && code.slice(i, i + 2) !== "*/")
+        out += code[i] === `
+` ? `
+` : " ", i++;
+      out += "  ";
+      i += 2;
+      continue;
+    }
+    const ch = code[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const quote = ch;
+      out += " ";
+      i++;
+      while (i < code.length && code[i] !== quote) {
+        if (code[i] === "\\") {
+          out += "  ";
+          i += 2;
+          continue;
+        }
+        out += code[i] === `
+` ? `
+` : " ";
+        i++;
+      }
+      out += " ";
+      i++;
+      continue;
+    }
+    out += ch;
+    i++;
+  }
+  return out;
+}
 function detectModelUsage(code) {
   const models = new Set, modelPattern = /\b([A-Z][a-zA-Z0-9]*)\s*\.\s*(all|find|first|get|where|orderBy|orderByDesc|limit|select|pluck|create|update|delete)\s*\(/g;
   let match;

package/dist/color-mode-boot.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Build the synchronous pre-paint `<script>`.
+ *
+ * Every storage access is wrapped: a sandboxed origin or disabled storage must
+ * degrade to the default mode, never throw. A throw here is unusually costly
+ * because the script sits above the application shell — an uncaught error would
+ * block the rest of the document.
+ */
+export declare function generateColorModeBootScript(options?: ColorModeBootConfig): string;
+/**
+ * Insert the boot script as the first thing in `<head>`.
+ *
+ * Placement matters twice over: the script must run before the browser paints,
+ * and a stylesheet `<link>` above it would block its execution (CSS blocks JS),
+ * delaying the very thing it exists to make early.
+ *
+ * `<meta charset>` is stepped over when it leads the head, so the encoding
+ * declaration keeps its place at the top of the document.
+ *
+ * Idempotent — a document that already carries the marker is returned
+ * unchanged, so this is safe on paths that run it more than once.
+ */
+export declare function injectColorModeBootScript(html: string, options?: ColorModeBootConfig): string;
+/**
+ * Pre-paint color-mode bootstrap (stacksjs/stx#1794).
+ *
+ * `useColorMode` is part of the client signals runtime: it reads localStorage
+ * at call time, after the runtime bundle has loaded and hydration has begun.
+ * That is too late. Applying the theme post-hydration guarantees a flash of the
+ * wrong theme on every cold load for every user whose stored preference differs
+ * from the default — which is why apps hand-write a render-blocking snippet in
+ * `<head>` and why `useColorMode` could not replace it.
+ *
+ * This module emits that snippet from the *same* option surface `useColorMode`
+ * takes, so the duplication collapses into one declaration in `stx.config.ts`:
+ *
+ * ```ts
+ * // stx.config.ts
+ * export default {
+ *   app: {
+ *     colorMode: { storageKey: 'theme', attribute: 'data-theme' },
+ *   },
+ * }
+ * ```
+ *
+ * The generated script is deliberately render-blocking, is injected as the
+ * first thing inside `<head>` (above any stylesheet), and touches the root
+ * element synchronously.
+ *
+ * ## Staying in lockstep with useColorMode
+ *
+ * The boot script must apply *exactly* what `useColorMode` will apply on
+ * hydration. If they disagree the flash comes back — the boot script would set
+ * one thing and hydration would immediately undo it, which is worse than not
+ * having a boot script at all. So this mirrors the runtime's `applyDOM` and
+ * `readPersisted` precisely, including two limitations that are NOT fixed here:
+ *
+ *   - `attribute` and `darkClass` are either/or, never both (stacksjs/stx#1788)
+ *   - the persisted vocabulary is exactly `light | dark | auto` — `'system'`
+ *     is not accepted (also #1788)
+ *
+ * Mirroring the limitation is intentional. When #1788 lands, both sides change
+ * together; `test/directives/color-mode-boot.test.ts` pins them to the same
+ * expectations so drift fails the suite rather than shipping a flash.
+ *
+ * The script publishes its resolved configuration on `window.__STX_COLOR_MODE__`
+ * so a bare `useColorMode()` call picks up the app's configured storage key and
+ * attribute without the options having to be repeated at the call site.
+ *
+ * @module color-mode-boot
+ */
+/** Marker attribute — makes injection idempotent and findable by tests. */
+export declare const COLOR_MODE_BOOT_MARKER: 'data-stx-color-mode-boot';
+/** The global the boot script publishes its resolved config on. */
+export declare const COLOR_MODE_BOOT_GLOBAL: '__STX_COLOR_MODE__';
+/**
+ * Pre-paint options. A strict subset of `ColorModeOptions` — only the fields
+ * that affect what lands on the root element before paint. `disableTransitions`
+ * is deliberately absent: nothing has painted yet, so there is no transition to
+ * suppress, and forcing a reflow in the critical path would only cost time.
+ */
+export declare interface ColorModeBootConfig {
+  storageKey?: string
+  initialMode?: ColorModeBootMode
+  darkClass?: string
+  attribute?: string
+}
+export type ColorModeBootMode = 'light' | 'dark' | 'auto';

package/dist/color-mode-boot.js

@@ -0,0 +1,35 @@
+export const COLOR_MODE_BOOT_MARKER = "data-stx-color-mode-boot", COLOR_MODE_BOOT_GLOBAL = "__STX_COLOR_MODE__";
+const MODES = new Set(["light", "dark", "auto"]), ATTRIBUTE_PATTERN = /^[a-z][\w:-]*$/i, CLASS_PATTERN = /^[\w-]+$/;
+function resolveConfig(options) {
+  const storageKey = options.storageKey ?? "stx-color-mode", initialMode = options.initialMode ?? "auto", darkClass = options.darkClass ?? "dark", attribute = options.attribute ?? null;
+  if (typeof storageKey !== "string" || storageKey.length === 0)
+    throw Error("colorMode.storageKey must be a non-empty string");
+  if (!MODES.has(initialMode))
+    throw Error(`colorMode.initialMode must be one of light, dark, auto \u2014 got ${JSON.stringify(initialMode)}`);
+  if (typeof darkClass !== "string" || !CLASS_PATTERN.test(darkClass))
+    throw Error(`colorMode.darkClass must be a single CSS class name \u2014 got ${JSON.stringify(darkClass)}`);
+  if (attribute !== null && (typeof attribute !== "string" || !ATTRIBUTE_PATTERN.test(attribute)))
+    throw Error(`colorMode.attribute must be a valid HTML attribute name \u2014 got ${JSON.stringify(attribute)}`);
+  return { storageKey, initialMode, darkClass, attribute };
+}
+function serializeForScript(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+export function generateColorModeBootScript(options = {}) {
+  const config = resolveConfig(options), body = `(function(){"use strict";var c=${serializeForScript(config)};var p=c.initialMode;try{var v=localStorage.getItem(c.storageKey);if(v==="light"||v==="dark"||v==="auto")p=v}catch(e){}var m=p;if(p==="auto"){try{m=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"}catch(e){m="light"}}var r=document.documentElement;if(c.attribute){r.setAttribute(c.attribute,m)}else if(m==="dark"){r.classList.add(c.darkClass)}else{r.classList.remove(c.darkClass)}try{window.${COLOR_MODE_BOOT_GLOBAL}={storageKey:c.storageKey,initialMode:c.initialMode,darkClass:c.darkClass,attribute:c.attribute,preference:p,mode:m}}catch(e){}}());`;
+  return `<script ${COLOR_MODE_BOOT_MARKER}>${body}</script>`;
+}
+export function injectColorModeBootScript(html, options = {}) {
+  if (html.includes(COLOR_MODE_BOOT_MARKER))
+    return html;
+  const headOpen = /<head\b[^>]*>/i.exec(html);
+  if (!headOpen)
+    return html;
+  let insertAt = headOpen.index + headOpen[0].length;
+  const afterHead = html.slice(insertAt), charset = /^\s*<meta\b[^>]*\bcharset\b[^>]*>/i.exec(afterHead);
+  if (charset)
+    insertAt += charset[0].length;
+  const script = generateColorModeBootScript(options);
+  return `${html.slice(0, insertAt)}
+  ${script}${html.slice(insertAt)}`;
+}

package/dist/composables/use-color-mode.js

@@ -1,9 +1,9 @@
 export function useColorMode(options = {}) {
-  const {
-    storageKey = "stx-color-mode",
-    initialMode = "auto",
-    darkClass = "dark",
-    attribute,
+  const boot = typeof window < "u" ? window.__STX_COLOR_MODE__ : null, {
+    storageKey = boot?.storageKey ?? "stx-color-mode",
+    initialMode = boot?.initialMode ?? "auto",
+    darkClass = boot?.darkClass ?? "dark",
+    attribute = boot?.attribute,
     disableTransitions = !0
   } = options;
   let preference = initialMode, resolved = "light";

package/dist/composables/use-storage.js

@@ -61,7 +61,12 @@ export function useStorage(key, defaultValue, options = {}) {
     const onStorage = (event) => {
       if (event.key === key && event.storageArea === getStorage()) {
         const prevValue = currentValue;
-        currentValue = event.newValue ? serializer.read(event.newValue) : defaultValue;
+        try {
+          currentValue = event.newValue ? serializer.read(event.newValue) : defaultValue;
+        } catch (e) {
+          console.warn(`[useStorage] Failed to read key "${key}" from a cross-tab update:`, e);
+          return;
+        }
         notify(currentValue, prevValue);
       }
     };