@stacksjs/stx 0.2.151 → 0.2.153

package/dist/ssr.d.ts

@@ -16,7 +16,7 @@ export declare function render(template: string, data?: Record<string, unknown>,
 /**
  * Create a STX server application
  */
-export declare function createApp(config?: AppConfig): void;
+export declare function createApp(config?: AppConfig): StxServerApp;
 /** Session data store */
 export declare interface SessionData {
   [key: string]: unknown
@@ -87,6 +87,22 @@ export declare interface AppConfig {
   csrfEnabled?: boolean
   sessionStore?: SessionStore
 }
+/**
+ * Handle returned by {@link createApp} — the server application surface.
+ */
+export declare interface StxServerApp {
+  fetch: (request: Request) => Promise<Response>
+  get: (pattern: string, handler: RouteHandler, middleware?: Middleware[]) => StxServerApp
+  post: (pattern: string, handler: RouteHandler, middleware?: Middleware[]) => StxServerApp
+  put: (pattern: string, handler: RouteHandler, middleware?: Middleware[]) => StxServerApp
+  delete: (pattern: string, handler: RouteHandler, middleware?: Middleware[]) => StxServerApp
+  patch: (pattern: string, handler: RouteHandler, middleware?: Middleware[]) => StxServerApp
+  use: (middleware: Middleware) => StxServerApp
+  render: (template: string, data?: Record<string, unknown>, ctx?: RequestContext) => Promise<Response>
+  redirect: (url: string, status?: 302 | 301 | 303 | 307 | 308) => Response
+  back: (ctx: RequestContext, errors?: ValidationErrors, oldInput?: Record<string, string>) => Response
+  listen: (port?: number) => ReturnType<typeof Bun.serve>
+}
 /** Route handler */
 // eslint-disable-next-line pickier/no-unused-vars
 export type RouteHandler = (ctx: RequestContext) => Response | Promise<Response>;

package/dist/stx.d.ts

@@ -237,11 +237,19 @@ interface StxColorModeOptions {
   /** localStorage key holding the preference. @default 'stx-color-mode' */
   storageKey?: string
   /** Mode used when nothing valid is stored. @default 'auto' */
-  initialMode?: 'light' | 'dark' | 'auto'
-  /** Class applied to `<html>` when dark. @default 'dark' */
-  darkClass?: string
-  /** Attribute applied to `<html>` INSTEAD of the class, e.g. 'data-theme'. */
-  attribute?: string
+  initialMode?: 'light' | 'dark' | 'auto' | 'system'
+  /**
+   * Class applied to `<html>` when dark. @default 'dark'
+   * Applied alongside `attribute`; pass `null` to opt out of the class.
+   */
+  darkClass?: string | null
+  /** Attribute set to the resolved mode on `<html>`, e.g. 'data-theme'. */
+  attribute?: string | null
+  /**
+   * Spelling written to storage for "follow the system".
+   * @default whatever is already stored, else 'auto'
+   */
+  autoValue?: 'auto' | 'system'
   /** Suppress CSS transitions across a mode switch. @default true */
   disableTransitions?: boolean
 }
@@ -257,7 +265,7 @@ declare function useColorMode(_options?: StxColorModeOptions): {
   /** User preference, which may be 'auto'. */
   readonly preference: 'light' | 'dark' | 'auto'
   readonly isDark: boolean
-  set: (mode: 'light' | 'dark' | 'auto') => void
+  set: (mode: 'light' | 'dark' | 'auto' | 'system') => void
   toggle: () => void
   subscribe: (fn: (mode: 'light' | 'dark', preference: 'light' | 'dark' | 'auto') => void) => () => void
 }

package/dist/types/config-types.d.ts

@@ -242,6 +242,7 @@ export declare interface AppHeadConfig {
   link?: Array<Record<string, string>>
   script?: Array<{ src?: string, content?: string, [key: string]: any }>
   headRaw?: string
+  htmlAttrs?: Record<string, string>
   bodyClass?: string
   bodyAttrs?: Record<string, string>
 }

package/dist/utils.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { extractAndStripCssImports, extractBridgeData, injectBrowserCoreAutoImports, processClientScript, renderVendorStyleTags } from "./client-script.js";
 import { COMPONENT_CLIENT_FACTORIES_CONTEXT_KEY, registerComponentClientFactory } from "./component-client-factories.js";
-import { interpolateScriptExpressions, processExpressions, unescapeHtml } from "./expressions.js";
+import { interpolateScriptExpressions, processExpressions } from "./expressions.js";
 import { COMPONENT_SCOPE_LOCAL_GLOBALS, buildRuntimeGlobalsDestructure } from "./runtime-globals.js";
 import { transformStoreImports } from "./store-imports.js";
 import { LRUCache } from "./performance-utils.js";
@@ -648,13 +648,6 @@ ${triedPaths.map((p) => `  - ${p}`).join(`
       templateContent = templateContent.replace(/\{\{\s*text\s*\|\|\s*slot\s*\}\}/g, () => slotContent);
     const { applySlots } = await importOnce("stx/slots", () => import("./slots.js")), { defaultSlot, namedSlots } = parsedSlotContent;
     templateContent = await applySlots(templateContent, defaultSlot, namedSlots, componentContext);
-    for (const [key, value] of Object.entries(componentContext))
-      if (typeof value === "string") {
-        if (value.includes("<") && value.includes(">") || value.includes("&lt;") || value.includes("&quot;")) {
-          const unescaped = unescapeHtml(value);
-          componentContext[key] = unescaped;
-        }
-      }
     const hasSignalScripts = clientScripts.some((s) => /\b(?:state|derived|effect|ref|reactive|computed|watch|watchEffect|useReactiveProp|defineProps|withDefaults|defineEmits|defineExpose|defineSlots)\s*(?:<[^<>()]*>)?\s*\(/.test(s)), clientSignalNames = componentClientSignalNames(clientScripts);
     if (clientSignalNames.length > 0)
       componentContext.__stx_client_signal_names = clientSignalNames;

package/dist/variable-extractor.d.ts

@@ -5,6 +5,14 @@
  * @returns JavaScript code with TypeScript syntax stripped
  */
 export declare function stripTypeScript(scriptContent: string): string;
+/**
+ * Whether a script failure was a module that could not be found.
+ *
+ * Matched on the message because the failure arrives as a plain Error from the
+ * runtime's loader rather than a typed one, and the wording differs between
+ * Bun and Node.
+ */
+export declare function isModuleResolutionFailure(message: string): boolean;
 export declare function extractVariables(scriptContent: string, context: Record<string, unknown>, filePath: string, options?: ExtractVariablesOptions): Promise<void>;
 /**
  * Convert ES module syntax to CommonJS

package/dist/variable-extractor.js

@@ -210,6 +210,9 @@ export function stripTypeScript(scriptContent) {
 `);
   return result;
 }
+export function isModuleResolutionFailure(message) {
+  return /cannot find module|could not resolve|module not found|failed to resolve/i.test(message);
+}
 export async function extractVariables(scriptContent, context, filePath, options = {}) {
   if (!scriptContent.trim())
     return;
@@ -470,10 +473,11 @@ export async function extractVariables(scriptContent, context, filePath, options
       if (!(key in context))
         context[key] = value;
   } catch (primaryError) {
-    if (process.env.STX_DEBUG) {
-      const msg = primaryError instanceof Error ? primaryError.message : String(primaryError);
+    const msg = primaryError instanceof Error ? primaryError.message : String(primaryError);
+    if (isModuleResolutionFailure(msg))
+      console.warn(`[stx] server <script> in ${filePath ?? "<unknown>"} imports a module that does not resolve, so every variable in that script is undefined. Cause: ${msg}`);
+    else if (process.env.STX_DEBUG)
       console.warn(`[stx] server <script> did not execute in ${filePath ?? "<unknown>"} \u2014 falling back to static extraction. Cause: ${msg}`);
-    }
     try {
       await fallbackVariableExtraction(jsContent, context, filePath);
     } catch (fallbackError) {
@@ -590,13 +594,24 @@ export function convertToCommonJS(scriptContent, filePath) {
         convertedLines.push(`const ${name} = await import('${resolved}')`);
         convertedLines.push(`module.exports.${name} = ${name};`);
       } else if (namedImportMatch) {
-        const [, names, source] = namedImportMatch, cleanNames = names.trim(), resolved = resolveSource(source);
-        convertedLines.push(`const { ${cleanNames} } = await import('${resolved}')`);
-        for (const n of cleanNames.split(",")) {
-          const cleanName = n.trim().split(/\s+as\s+/).pop()?.trim();
-          if (cleanName)
-            convertedLines.push(`module.exports.${cleanName} = ${cleanName};`);
+        const [, names, source] = namedImportMatch, resolved = resolveSource(source), specifiers = [], exported = [];
+        for (const raw of names.split(",")) {
+          const specifier = raw.trim();
+          if (!specifier)
+            continue;
+          const aliased = specifier.split(/\s+as\s+/);
+          if (aliased.length === 2) {
+            const [imported, local] = [aliased[0].trim(), aliased[1].trim()];
+            specifiers.push(`${imported}: ${local}`);
+            exported.push(local);
+          } else {
+            specifiers.push(specifier);
+            exported.push(specifier);
+          }
         }
+        convertedLines.push(`const { ${specifiers.join(", ")} } = await import('${resolved}')`);
+        for (const local of exported)
+          convertedLines.push(`module.exports.${local} = ${local};`);
       } else if (sideEffectMatch) {
         const resolved = resolveSource(sideEffectMatch[1]);
         convertedLines.push(`await import('${resolved}')`);

package/dist/visual-testing.d.ts

@@ -1,15 +1,15 @@
 /**
  * Create a snapshot tester
  */
-export declare function createSnapshotTester(config?: VisualTestConfig): void;
+export declare function createSnapshotTester(config?: VisualTestConfig): SnapshotTester;
 /**
  * Create a visual regression tester
  */
-export declare function createVisualRegressionTester(config?: VisualTestConfig): void;
+export declare function createVisualRegressionTester(config?: VisualTestConfig): VisualRegressionTester;
 /**
  * Create a story-based visual tester
  */
-export declare function createStoryTester(config?: VisualTestConfig): void;
+export declare function createStoryTester(config?: VisualTestConfig): StoryTester;
 /**
  * Generate visual test report
  */
@@ -89,6 +89,29 @@ export declare interface Story {
   args?: Record<string, unknown>
   viewports?: Viewport[]
 }
+/** Handle returned by {@link createSnapshotTester}. */
+export declare interface SnapshotTester {
+  snapshot: (html: string, name: string) => Promise<SnapshotResult>
+  snapshotJson: (data: unknown, name: string) => Promise<SnapshotResult>
+  matchInlineSnapshot: (actual: string, expected?: string) => { passed: boolean, expected: string }
+  getConfig: () => Required<VisualTestConfig>
+}
+/** Handle returned by {@link createVisualRegressionTester}. */
+export declare interface VisualRegressionTester {
+  compareScreenshots: (name: string, actual: Buffer, viewport?: string) => Promise<ScreenshotResult>
+  testViewports: (name: string, captureScreenshot: (viewport: Viewport) => Promise<Buffer>, viewports?: Viewport[]) => Promise<ScreenshotResult[]>
+  getSnapshotTester: () => SnapshotTester
+}
+/** Handle returned by {@link createStoryTester}. */
+export declare interface StoryTester {
+  addStory: (story: Story) => void
+  addStories: (storyList: Story[]) => void
+  getStories: () => Story[]
+  getStoriesForComponent: (component: string) => Story[]
+  testStory: (storyId: string) => Promise<VisualTestResult>
+  testAllStories: () => Promise<VisualTestResult[]>
+  generateStoryIndex: () => Promise<string>
+}
 // =============================================================================
 // Test Reporter
 // =============================================================================

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/stx",
   "type": "module",
-  "version": "0.2.151",
+  "version": "0.2.153",
   "description": "A performant UI Framework. Powered by Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -117,12 +117,12 @@
   "dependencies": {
     "@cwcss/crosswind": "^0.2.14",
     "@stacksjs/clapp": "^0.2.0",
-    "@stacksjs/desktop": "0.2.151",
-    "@stacksjs/sanitizer": "0.2.151",
+    "@stacksjs/desktop": "0.2.153",
+    "@stacksjs/sanitizer": "0.2.153",
     "@stacksjs/ts-i18n": "^0.1.11",
-    "bun-plugin-stx": "0.2.151",
+    "bun-plugin-stx": "0.2.153",
     "bunfig": "^0.15.17",
-    "stx-router": "0.2.151",
+    "stx-router": "0.2.153",
     "ts-broadcasting": "^0.0.9",
     "ts-images": "^0.1.9",
     "ts-syntax-highlighter": "^0.2.1"

package/stx.d.ts

@@ -237,11 +237,19 @@ interface StxColorModeOptions {
   /** localStorage key holding the preference. @default 'stx-color-mode' */
   storageKey?: string
   /** Mode used when nothing valid is stored. @default 'auto' */
-  initialMode?: 'light' | 'dark' | 'auto'
-  /** Class applied to `<html>` when dark. @default 'dark' */
-  darkClass?: string
-  /** Attribute applied to `<html>` INSTEAD of the class, e.g. 'data-theme'. */
-  attribute?: string
+  initialMode?: 'light' | 'dark' | 'auto' | 'system'
+  /**
+   * Class applied to `<html>` when dark. @default 'dark'
+   * Applied alongside `attribute`; pass `null` to opt out of the class.
+   */
+  darkClass?: string | null
+  /** Attribute set to the resolved mode on `<html>`, e.g. 'data-theme'. */
+  attribute?: string | null
+  /**
+   * Spelling written to storage for "follow the system".
+   * @default whatever is already stored, else 'auto'
+   */
+  autoValue?: 'auto' | 'system'
   /** Suppress CSS transitions across a mode switch. @default true */
   disableTransitions?: boolean
 }
@@ -257,7 +265,7 @@ declare function useColorMode(_options?: StxColorModeOptions): {
   /** User preference, which may be 'auto'. */
   readonly preference: 'light' | 'dark' | 'auto'
   readonly isDark: boolean
-  set: (mode: 'light' | 'dark' | 'auto') => void
+  set: (mode: 'light' | 'dark' | 'auto' | 'system') => void
   toggle: () => void
   subscribe: (fn: (mode: 'light' | 'dark', preference: 'light' | 'dark' | 'auto') => void) => () => void
 }