@stacksjs/stx 0.2.155 → 0.2.156

package/dist/state-dir.d.ts

@@ -1,3 +1,7 @@
+/** The directory used when nothing configures one. */
+export declare const DEFAULT_STATE_DIR = ".stx";
+/** Environment variable that overrides both the config and the default. */
+export declare const STATE_DIR_ENV_VAR = "STX_DIR";
 /**
  * Records the `stateDir` coming from `stx.config.ts`.
  *
@@ -30,7 +34,3 @@ export declare function stateDir(root?: string, ...segments: string[]): string;
  */
 export declare function rebaseOntoStateDir(value: string): string;
 export declare function rebaseOntoStateDir(value: string | undefined): string | undefined;
-/** The directory used when nothing configures one. */
-export declare const DEFAULT_STATE_DIR: '.stx';
-/** Environment variable that overrides both the config and the default. */
-export declare const STATE_DIR_ENV_VAR: 'STX_DIR';

package/dist/state-management.d.ts

@@ -75,18 +75,6 @@ export declare function createStoreDirective(storeName: string): {
   hasEndTag: boolean
   handler: () => string
 };
-/**
- * Serialize all stores for SSR hydration.
- */
-export declare function serializeStores(): string;
-/**
- * Hydrate stores from serialized state.
- */
-export declare function hydrateStores(serialized: string): void;
-/**
- * Generate hydration script for SSR.
- */
-export declare function generateHydrationScript(): string;
 /**
  * Initialize DevTools integration.
  */

package/dist/state-management.js

@@ -1,3 +1,4 @@
+import { recordStoreMutation, registerStore as registerDevToolsStore } from "./devtools.js";
 const globalState = {
   stores: new Map,
   subscriptions: new Map
@@ -105,8 +106,9 @@ export function createStore(initialValue, options = {}) {
         console.error("[stx-store] Subscriber error:", error);
       }
   }, devToolsNotify = devtools ? (action, newValue) => {
-    if (typeof window < "u" && window.__STX_DEVTOOLS__)
-      window.__STX_DEVTOOLS__.onStoreChange(name || "unnamed", action, newValue);
+    recordStoreMutation(name || "unnamed", action, currentValue, newValue);
+    if (typeof window < "u")
+      window.__STX_DEVTOOLS__?.onStoreChange?.(name || "unnamed", action, newValue);
   } : () => {}, baseSet = (value) => {
     const prevValue = currentValue;
     if (!equals(value, prevValue)) {
@@ -152,8 +154,11 @@ export function createStore(initialValue, options = {}) {
   };
   for (const mw of middleware.reverse())
     wrappedSet = mw(baseSet, () => currentValue, store)(wrappedSet);
-  if (name)
+  if (name) {
     registerStore(name, store);
+    if (devtools)
+      registerDevToolsStore(name, currentValue ?? {}, {}, []);
+  }
   return store;
 }
 export function createReadonlyStore(getter, options = {}) {
@@ -324,28 +329,6 @@ export function createStoreDirective(storeName) {
     }
   };
 }
-export function serializeStores() {
-  const state = {};
-  for (const [name, store] of globalState.stores.entries())
-    state[name] = store.get();
-  return JSON.stringify(state);
-}
-export function hydrateStores(serialized) {
-  try {
-    const state = JSON.parse(serialized);
-    for (const [name, value] of Object.entries(state)) {
-      const store = getStore(name);
-      if (store)
-        store.set(value);
-    }
-  } catch (error) {
-    console.error("[stx-store] Hydration failed:", error);
-  }
-}
-export function generateHydrationScript() {
-  return `<script>window.__STX_STORE_STATE__=${serializeStores()};
-if(window.__STX_HYDRATE_STORES__){window.__STX_HYDRATE_STORES__()}</script>`;
-}
 export function initDevTools() {
   if (typeof window > "u")
     return;

package/dist/store-imports.d.ts

@@ -22,3 +22,26 @@
  * Also transforms @composables imports to window.__composables.
  */
 export declare function transformStoreImports(code: string): string;
+/**
+ * Remove `import` statements from a store or composable module body.
+ *
+ * These files are concatenated into one browser IIFE, so their imports have to
+ * go: `state`, `derived` and `defineStore` are runtime globals rather than real
+ * modules, and leaving the statements in makes the transpiler emit `require()`
+ * calls that fail in the browser.
+ *
+ * The previous pattern was line-anchored (`^import\s+.*from …$`), so a
+ * multi-line specifier list survived it — and survived Bun's transpiler too,
+ * because `import` is legal at a module's top level. It only failed once the
+ * body had been wrapped in the shared IIFE, where an import is a SyntaxError
+ * that takes EVERY store in the bundle with it, reported as a misleading
+ * "Store not found" (stacksjs/stx#1859).
+ *
+ * `[^'"]` between `import` and `from` is what keeps a multi-line match from
+ * running past its own statement into the next one's specifier: the clause
+ * never contains a quote, and the module specifier always does.
+ *
+ * Shared by both loaders because they carried byte-identical copies, which is
+ * how one of them would have been fixed and the other left behind.
+ */
+export declare function stripModuleImports(code: string): string;

package/dist/store-imports.js

@@ -11,3 +11,6 @@ export function transformStoreImports(code) {
   });
   return code;
 }
+export function stripModuleImports(code) {
+  return code.replace(/^import\s+[^'"]*?from\s*['"][^'"]+['"]\s*;?[ \t]*$/gm, "").replace(/^import\s+['"][^'"]+['"]\s*;?[ \t]*$/gm, "");
+}

package/dist/store-loader.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Store Auto-Loader
+ *
+ * Discovers .ts files in storesDir, bundles them with Bun.build,
+ * and returns a <script> tag to inject into the page. Stores are
+ * registered before any <script client> blocks run, so useStore()
+ * always finds them.
+ *
+ * @module store-loader
+ */
 export declare function getStoreScript(storesDir?: string): Promise<string | null>;
 /**
  * Clear the cached store script (for dev mode hot reload).

package/dist/store-loader.js

@@ -2,7 +2,8 @@ import path from "node:path";
 import { loadStxConfig } from "./config.js";
 import { getPublicEnvDefine } from "./public-env.js";
 import { STX_RUNTIME_GLOBALS } from "./runtime-globals.js";
-import { transformStoreImports } from "./store-imports.js";
+import { readSigned, sourceSignature, writeSigned } from "./source-signature.js";
+import { stripModuleImports, transformStoreImports } from "./store-imports.js";
 const _cachedStoreScripts = new Map;
 function collectDeclaredNames(code, into) {
   for (const match of code.matchAll(/\b(?:const|let|var|function|class)\s+([A-Z_a-z$][\w$]*)/g))
@@ -29,9 +30,6 @@ export async function getStoreScript(storesDir) {
     const config = await loadStxConfig();
     resolvedDir = path.resolve(config.root || process.cwd(), config.storesDir || "stores");
   }
-  const cached = _cachedStoreScripts.get(resolvedDir);
-  if (cached !== void 0)
-    return cached || null;
   const glob = new Bun.Glob("*.ts"), storeFiles = [];
   try {
     for await (const file of glob.scan({ cwd: resolvedDir, absolute: !0 })) {
@@ -43,11 +41,14 @@ export async function getStoreScript(storesDir) {
       storeFiles.push(file);
     }
   } catch {
-    _cachedStoreScripts.set(resolvedDir, "");
+    writeSigned(_cachedStoreScripts, resolvedDir, "", "");
     return null;
   }
+  const signature = sourceSignature(storeFiles), cached = readSigned(_cachedStoreScripts, resolvedDir, signature);
+  if (cached !== void 0)
+    return cached || null;
   if (storeFiles.length === 0) {
-    _cachedStoreScripts.set(resolvedDir, "");
+    writeSigned(_cachedStoreScripts, resolvedDir, signature, "");
     return null;
   }
   const filesWithDeps = [];
@@ -70,7 +71,7 @@ export async function getStoreScript(storesDir) {
       const storeName = path.basename(file, ".ts");
       collectDeclaredNames(code, declaredNames);
       code = transformStoreImports(code);
-      code = code.replace(/^import\s+.*from\s+['"][^'"]+['"]\s*;?\s*$/gm, "");
+      code = stripModuleImports(code);
       code = code.replace(/^export\s+(default\s+)?/gm, "");
       code = transpiler.transformSync(code);
       chunks.push(`// Store: ${storeName}
@@ -79,7 +80,7 @@ ${code.trim()}`);
       console.warn(`[stx] Failed to load store ${file}:`, e);
     }
   if (chunks.length === 0) {
-    _cachedStoreScripts.set(resolvedDir, "");
+    writeSigned(_cachedStoreScripts, resolvedDir, signature, "");
     return null;
   }
   const joinedChunks = chunks.join(`
@@ -90,7 +91,7 @@ ${STX_RUNTIME_GLOBALS.filter((name) => !declaredNames.has(name) && new RegExp(`\
 `)}
 ${joinedChunks}
 })();`;
-  _cachedStoreScripts.set(resolvedDir, code);
+  writeSigned(_cachedStoreScripts, resolvedDir, signature, code);
   return code;
 }
 export function clearStoreCache() {

package/dist/story/analytics.d.ts

@@ -1,85 +1,163 @@
 /**
- * Generate analytics dashboard HTML
+ * STX Story - Component Usage Analytics
+ * Track which components are viewed most, which props are changed most
  */
-export declare function getAnalyticsDashboardHtml(mostViewed: Array<{ componentId: string, viewCount: number }>, mostChangedProps: Array<{ propName: string, changeCount: number }>): string;
 /**
- * Generate analytics styles
+ * Analytics event types
  */
-export declare function getAnalyticsStyles(): string;
+export type AnalyticsEventType = 'view' | 'prop_change' | 'variant_switch' | 'search' | 'bookmark' | 'copy_code' | 'test_run';
 /**
  * Analytics event
  */
-export declare interface AnalyticsEvent {
-  type: AnalyticsEventType
-  timestamp: number
-  componentId?: string
-  variantId?: string
-  propName?: string
-  query?: string
-  metadata?: Record<string, any>
+export interface AnalyticsEvent {
+    /** Event type */
+    type: AnalyticsEventType;
+    /** Timestamp */
+    timestamp: number;
+    /** Component ID */
+    componentId?: string;
+    /** Variant ID */
+    variantId?: string;
+    /** Prop name (for prop_change) */
+    propName?: string;
+    /** Search query (for search) */
+    query?: string;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
 }
 /**
  * Component analytics summary
  */
-export declare interface ComponentAnalytics {
-  componentId: string
-  componentName: string
-  viewCount: number
-  uniqueViews: number
-  lastViewed?: number
-  propChanges: Record<string, number>
-  topChangedProps: string[]
-  variantViews: Record<string, number>
-  avgTimeSpent: number
+export interface ComponentAnalytics {
+    /** Component ID */
+    componentId: string;
+    /** Component name */
+    componentName: string;
+    /** Total views */
+    viewCount: number;
+    /** Unique view sessions */
+    uniqueViews: number;
+    /** Last viewed timestamp */
+    lastViewed?: number;
+    /** Prop change counts */
+    propChanges: Record<string, number>;
+    /** Most changed props */
+    topChangedProps: string[];
+    /** Variant view counts */
+    variantViews: Record<string, number>;
+    /** Average time spent (ms) */
+    avgTimeSpent: number;
 }
 /**
  * Analytics storage
  */
-export declare interface AnalyticsStorage {
-  version: number
-  events: AnalyticsEvent[]
-  sessions: AnalyticsSession[]
+export interface AnalyticsStorage {
+    version: number;
+    events: AnalyticsEvent[];
+    sessions: AnalyticsSession[];
 }
 /**
  * Analytics session
  */
-export declare interface AnalyticsSession {
-  id: string
-  startTime: number
-  endTime?: number
-  componentViews: string[]
+export interface AnalyticsSession {
+    id: string;
+    startTime: number;
+    endTime?: number;
+    componentViews: string[];
 }
-/**
- * Analytics event types
- */
-export type AnalyticsEventType = | 'view'
-  | 'prop_change'
-  | 'variant_switch'
-  | 'search'
-  | 'bookmark'
-  | 'copy_code'
-  | 'test_run';
 /**
  * Analytics tracker
  */
 export declare class AnalyticsTracker {
-  constructor(rootDir: string);
-  save(): Promise<void>;
-  startSession(): void;
-  endSession(): void;
-  track(event: Omit<AnalyticsEvent, 'timestamp'>): void;
-  trackView(componentId: string, variantId?: string): void;
-  trackPropChange(componentId: string, propName: string, value: any): void;
-  trackVariantSwitch(componentId: string, variantId: string): void;
-  trackSearch(query: string, resultCount: number): void;
-  getComponentAnalytics(componentId: string, componentName: string): ComponentAnalytics;
-  getMostViewedComponents(limit?: number): Array<{ componentId: string, viewCount: number }>;
-  getMostChangedProps(limit?: number): Array<{ propName: string, changeCount: number }>;
-  getSearchAnalytics(): {
-    totalSearches: number
-    topQueries: Array<{ query: string, count: number }>
-    avgResultCount: number
-  };
-  clear(): void;
-  exportAnalytics(): string;
+    private storage;
+    private storagePath;
+    private currentSession;
+    private dirty;
+    private viewStartTimes;
+    constructor(rootDir: string);
+    private loadStorage;
+    save(): Promise<void>;
+    /**
+     * Start a new session
+     */
+    startSession(): void;
+    /**
+     * End current session
+     */
+    endSession(): void;
+    /**
+     * Track an event
+     */
+    track(event: Omit<AnalyticsEvent, 'timestamp'>): void;
+    /**
+     * Track component view
+     */
+    trackView(componentId: string, variantId?: string): void;
+    /**
+     * End view timing for a component
+     */
+    private endViewTiming;
+    /**
+     * Track prop change
+     */
+    trackPropChange(componentId: string, propName: string, value: any): void;
+    /**
+     * Track variant switch
+     */
+    trackVariantSwitch(componentId: string, variantId: string): void;
+    /**
+     * Track search
+     */
+    trackSearch(query: string, resultCount: number): void;
+    /**
+     * Get analytics for a component
+     */
+    getComponentAnalytics(componentId: string, componentName: string): ComponentAnalytics;
+    /**
+     * Get most viewed components
+     */
+    getMostViewedComponents(limit?: number): Array<{
+        componentId: string;
+        viewCount: number;
+    }>;
+    /**
+     * Get most changed props across all components
+     */
+    getMostChangedProps(limit?: number): Array<{
+        propName: string;
+        changeCount: number;
+    }>;
+    /**
+     * Get search analytics
+     */
+    getSearchAnalytics(): {
+        totalSearches: number;
+        topQueries: Array<{
+            query: string;
+            count: number;
+        }>;
+        avgResultCount: number;
+    };
+    /**
+     * Clear all analytics
+     */
+    clear(): void;
+    /**
+     * Export analytics as JSON
+     */
+    exportAnalytics(): string;
 }
+/**
+ * Generate analytics dashboard HTML
+ */
+export declare function getAnalyticsDashboardHtml(mostViewed: Array<{
+    componentId: string;
+    viewCount: number;
+}>, mostChangedProps: Array<{
+    propName: string;
+    changeCount: number;
+}>): string;
+/**
+ * Generate analytics styles
+ */
+export declare function getAnalyticsStyles(): string;

package/dist/story/bookmarks.d.ts

@@ -1,49 +1,102 @@
 /**
- * Generate bookmarks panel HTML
- */
-export declare function getBookmarksPanelHtml(bookmarks: Bookmark[]): string;
-/**
- * Generate bookmarks panel styles
+ * STX Story - Bookmarks
+ * Bookmark component+variant+props combinations for quick access
  */
-export declare function getBookmarksPanelStyles(): string;
-/**
- * Generate bookmarks client script
- */
-export declare function getBookmarksScript(): string;
 /**
  * Bookmark entry
  */
-export declare interface Bookmark {
-  id: string
-  name: string
-  storyId: string
-  variantId: string
-  props: Record<string, any>
-  created: number
-  notes?: string
-  color?: string
+export interface Bookmark {
+    /** Bookmark ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Story ID */
+    storyId: string;
+    /** Variant ID */
+    variantId: string;
+    /** Props state */
+    props: Record<string, any>;
+    /** Created timestamp */
+    created: number;
+    /** Notes */
+    notes?: string;
+    /** Color label */
+    color?: string;
 }
 /**
  * Bookmarks storage
  */
-export declare interface BookmarksStorage {
-  version: number
-  bookmarks: Bookmark[]
+export interface BookmarksStorage {
+    version: number;
+    bookmarks: Bookmark[];
 }
 /**
  * Bookmarks manager
  */
 export declare class BookmarksManager {
-  constructor(rootDir: string);
-  save(): Promise<void>;
-  addBookmark(storyId: string, variantId: string, props: Record<string, any>, options?: { name?: string, notes?: string, color?: string }): Bookmark;
-  getAllBookmarks(): Bookmark[];
-  getBookmarksForStory(storyId: string): Bookmark[];
-  getBookmark(id: string): Bookmark | undefined;
-  isBookmarked(storyId: string, variantId: string): boolean;
-  updateBookmark(id: string, updates: Partial<Omit<Bookmark, 'id' | 'created'>>): Bookmark | undefined;
-  deleteBookmark(id: string): boolean;
-  toggleBookmark(storyId: string, variantId: string, props: Record<string, any>): { added: boolean, bookmark?: Bookmark };
-  exportBookmarks(): string;
-  importBookmarks(json: string, merge?: boolean): number;
+    private storage;
+    private storagePath;
+    private dirty;
+    constructor(rootDir: string);
+    private loadStorage;
+    save(): Promise<void>;
+    /**
+     * Add a bookmark
+     */
+    addBookmark(storyId: string, variantId: string, props: Record<string, any>, options?: {
+        name?: string;
+        notes?: string;
+        color?: string;
+    }): Bookmark;
+    /**
+     * Get all bookmarks
+     */
+    getAllBookmarks(): Bookmark[];
+    /**
+     * Get bookmarks for a story
+     */
+    getBookmarksForStory(storyId: string): Bookmark[];
+    /**
+     * Get a bookmark by ID
+     */
+    getBookmark(id: string): Bookmark | undefined;
+    /**
+     * Check if a combination is bookmarked
+     */
+    isBookmarked(storyId: string, variantId: string): boolean;
+    /**
+     * Update a bookmark
+     */
+    updateBookmark(id: string, updates: Partial<Omit<Bookmark, 'id' | 'created'>>): Bookmark | undefined;
+    /**
+     * Delete a bookmark
+     */
+    deleteBookmark(id: string): boolean;
+    /**
+     * Toggle bookmark for a combination
+     */
+    toggleBookmark(storyId: string, variantId: string, props: Record<string, any>): {
+        added: boolean;
+        bookmark?: Bookmark;
+    };
+    /**
+     * Export bookmarks
+     */
+    exportBookmarks(): string;
+    /**
+     * Import bookmarks
+     */
+    importBookmarks(json: string, merge?: boolean): number;
 }
+/**
+ * Generate bookmarks panel HTML
+ */
+export declare function getBookmarksPanelHtml(bookmarks: Bookmark[]): string;
+/**
+ * Generate bookmarks panel styles
+ */
+export declare function getBookmarksPanelStyles(): string;
+/**
+ * Generate bookmarks client script
+ */
+export declare function getBookmarksScript(): string;