@servlyadmin/runtime-core 0.1.46 → 0.2.1

package/README.md

@@ -45,6 +45,34 @@ const app = await mount({
 });
 ```
 
+### With Loading & Error States
+
+```typescript
+const app = await mount({
+  componentId: 'my-component-id',
+  target: '#app',
+  props: { title: 'Hello' },
+  
+  // Show loading indicator
+  loadingComponent: '<div class="skeleton animate-pulse h-32 bg-gray-200 rounded"></div>',
+  
+  // Show error message on failure
+  errorComponent: (err) => `<div class="text-red-500">Failed to load: ${err.message}</div>`,
+  
+  // Optional: delay before showing loading (avoids flash for fast loads)
+  loadingDelay: 200,
+  
+  // Optional: minimum time to show loading (avoids flash)
+  minLoadingTime: 500,
+  
+  // Lifecycle callbacks
+  onLoadStart: () => console.log('Loading...'),
+  onLoadEnd: () => console.log('Done!'),
+  onReady: (result) => console.log('Mounted!'),
+  onError: (err) => console.error('Failed:', err)
+});
+```
+
 ### With Version & Cache Control
 
 ```typescript
@@ -133,6 +161,36 @@ const { data } = await fetchComponent('my-component', {
 });
 ```
 
+## Prefetching
+
+Preload components for faster subsequent rendering:
+
+```typescript
+import { prefetch, prefetchAll, prefetchOnHover, prefetchOnVisible, prefetchOnIdle } from '@servlyadmin/runtime-core';
+
+// Prefetch a single component
+await prefetch('pricing-card');
+
+// Prefetch multiple components
+await prefetchAll(['pricing-card', 'contact-form', 'navbar']);
+
+// Prefetch with versions
+await prefetchAll([
+  { id: 'pricing-card', version: '^1.0.0' },
+  { id: 'contact-form', version: 'latest' }
+]);
+
+// Prefetch on hover (great for modals/dialogs)
+const cleanup = prefetchOnHover('#open-modal-btn', 'modal-component');
+// Later: cleanup() to remove listener
+
+// Prefetch when element becomes visible (Intersection Observer)
+const cleanup = prefetchOnVisible('#pricing-section', ['pricing-card', 'feature-list']);
+
+// Prefetch when browser is idle (non-critical components)
+prefetchOnIdle(['footer', 'sidebar', 'help-modal']);
+```
+
 ## Core Concepts
 
 ### Layout Elements
@@ -204,6 +262,16 @@ const app = await mount({
     apiKey?: string,
     retryConfig?: RetryConfig,
   },
+  
+  // Loading & Error States
+  loadingComponent?: string | HTMLElement,  // HTML to show while loading
+  errorComponent?: (err: Error) => string | HTMLElement,  // Error display
+  loadingDelay?: number,         // Delay before showing loading (ms)
+  minLoadingTime?: number,       // Minimum loading display time (ms)
+  
+  // Lifecycle Callbacks
+  onLoadStart?: () => void,      // Called when loading starts
+  onLoadEnd?: () => void,        // Called when loading ends
   onReady?: (result: MountResult) => void,
   onError?: (error: Error) => void,
 });
@@ -383,6 +451,53 @@ hasTemplateSyntax('{{props.name}}'); // true
 hasTemplateSyntax('static text');    // false
 ```
 
+### Prefetch API
+
+Preload components for faster subsequent rendering.
+
+```typescript
+import { 
+  prefetch, 
+  prefetchAll, 
+  prefetchOnHover, 
+  prefetchOnVisible, 
+  prefetchOnIdle 
+} from '@servlyadmin/runtime-core';
+
+// Prefetch single component
+await prefetch('pricing-card');
+await prefetch('pricing-card', '^1.0.0');  // With version
+
+// Prefetch multiple components
+const { success, failed } = await prefetchAll([
+  'pricing-card',
+  'contact-form',
+  { id: 'navbar', version: '^2.0.0' }
+]);
+
+// Prefetch on hover (returns cleanup function)
+const cleanup = prefetchOnHover(
+  '#open-modal-btn',  // Target element
+  'modal-component',  // Component ID
+  'latest',           // Version
+  { delay: 100 }      // Options: delay before prefetch
+);
+// Later: cleanup()
+
+// Prefetch when element becomes visible
+const cleanup = prefetchOnVisible(
+  '#pricing-section',                    // Target element
+  ['pricing-card', 'feature-list'],      // Components to prefetch
+  { rootMargin: '100px', threshold: 0 }  // IntersectionObserver options
+);
+
+// Prefetch during browser idle time
+prefetchOnIdle(
+  ['footer', 'sidebar', 'help-modal'],
+  { timeout: 5000 }  // Max wait time before forcing prefetch
+);
+```
+
 ## Slots
 
 Components can define slots for content injection:

package/dist/index.cjs

@@ -720,6 +720,7 @@ __export(index_exports, {
   extractDependenciesFromCode: () => extractDependenciesFromCode,
   extractOverrideDependencies: () => extractOverrideDependencies,
   extractReferencedViewIds: () => extractReferencedViewIds,
+  extractSlotBindings: () => extractSlotBindings,
   fetchComponent: () => fetchComponent,
   fetchComponentWithDependencies: () => fetchComponentWithDependencies,
   formatStyleValue: () => formatStyleValue,
@@ -777,7 +778,12 @@ __export(index_exports, {
   mountData: () => mountData,
   navigateTo: () => navigateTo,
   parseVersion: () => parseVersion,
+  prefetch: () => prefetch,
+  prefetchAll: () => prefetchAll,
   prefetchComponents: () => prefetchComponents,
+  prefetchOnHover: () => prefetchOnHover,
+  prefetchOnIdle: () => prefetchOnIdle,
+  prefetchOnVisible: () => prefetchOnVisible,
   preloadIcons: () => preloadIcons,
   preloadTailwind: () => preloadTailwind,
   preventFOUC: () => preventFOUC,
@@ -1519,8 +1525,96 @@ function resolveBindingPath(path, context) {
   }
   return navigatePath(source, parts.slice(startIndex));
 }
+var FUNCTION_CALL_REGEX = /^(\w+)\s*\((.*)\)$/s;
+function executeGlobalFunction(funcName, argsStr, context) {
+  if (context.functionMap?.[funcName]) {
+    try {
+      const args = parseFunctionArguments(argsStr, context);
+      return context.functionMap[funcName](...args);
+    } catch (error) {
+      console.error(`[GlobalFunction] Error executing ${funcName}:`, error);
+      return void 0;
+    }
+  }
+  const func = context.globalFunctions?.find((f) => f.name === funcName);
+  if (!func) {
+    console.warn(`[GlobalFunction] Function not found: ${funcName}`);
+    return void 0;
+  }
+  try {
+    const args = parseFunctionArguments(argsStr, context);
+    const paramNames = func.parameters.map((p) => p.name);
+    const fnBody = `
+      const state = __ctx__.state || {};
+      const props = __ctx__.props || {};
+      const config = __ctx__.configs || __ctx__.context || {};
+      ${func.code}
+    `;
+    const fn = new Function("__ctx__", ...paramNames, fnBody);
+    return fn(context, ...args);
+  } catch (error) {
+    console.error(`[GlobalFunction] Error executing ${funcName}:`, error);
+    return void 0;
+  }
+}
+function parseFunctionArguments(argsStr, context) {
+  if (!argsStr.trim()) return [];
+  const args = [];
+  let current = "";
+  let depth = 0;
+  let inString = false;
+  let stringChar = "";
+  for (let i = 0; i < argsStr.length; i++) {
+    const char = argsStr[i];
+    const prevChar = argsStr[i - 1];
+    if ((char === '"' || char === "'") && prevChar !== "\\") {
+      if (!inString) {
+        inString = true;
+        stringChar = char;
+      } else if (char === stringChar) {
+        inString = false;
+      }
+    }
+    if (!inString) {
+      if (char === "(" || char === "[" || char === "{") depth++;
+      if (char === ")" || char === "]" || char === "}") depth--;
+    }
+    if (char === "," && depth === 0 && !inString) {
+      args.push(parseArgumentValue(current.trim(), context));
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  if (current.trim()) {
+    args.push(parseArgumentValue(current.trim(), context));
+  }
+  return args;
+}
+function parseArgumentValue(value, context) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  if (!isNaN(Number(trimmed)) && trimmed !== "") {
+    return Number(trimmed);
+  }
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null") return null;
+  if (trimmed === "undefined") return void 0;
+  if (trimmed.startsWith("{{") && trimmed.endsWith("}}")) {
+    return resolveTemplateValue(trimmed, context);
+  }
+  return resolveBindingPath(trimmed, context);
+}
 function resolveExpression(expression, context) {
   const trimmed = expression.trim();
+  const funcMatch = trimmed.match(FUNCTION_CALL_REGEX);
+  if (funcMatch) {
+    const [, funcName, argsStr] = funcMatch;
+    return executeGlobalFunction(funcName, argsStr, context);
+  }
   const comparisonOperators = ["===", "!==", "==", "!=", ">=", "<=", ">", "<"];
   for (const op of comparisonOperators) {
     if (trimmed.includes(op)) {
@@ -2437,6 +2531,203 @@ function getUrlInfo() {
 }
 
 // src/eventSystem.ts
+function createShortcuts(ctx) {
+  return {
+    /**
+     * Render a dynamic list of items using a blueprint view
+     * This is a simplified version for runtime - full implementation requires DOM access
+     */
+    renderDynamicList: (options) => {
+      const { blueprint, targetContainer, data = [], clearExisting = true, itemProps = {} } = options;
+      const container = typeof document !== "undefined" ? document.querySelector(targetContainer) || document.querySelector(`[data-servly-id="${targetContainer.replace("#", "")}"]`) : null;
+      if (!container) {
+        console.warn(`[shortcuts.renderDynamicList] Container not found: ${targetContainer}`);
+        return { success: false, error: "Container not found" };
+      }
+      if (clearExisting) {
+        container.innerHTML = "";
+      }
+      const event = new CustomEvent("servly:renderDynamicList", {
+        bubbles: true,
+        detail: {
+          blueprint,
+          targetContainer,
+          data,
+          itemProps,
+          container
+        }
+      });
+      container.dispatchEvent(event);
+      return { success: true, itemCount: data.length };
+    },
+    /**
+     * Quick list rendering helper
+     */
+    renderList: (blueprint, targetContainer, data, options = {}) => {
+      return createShortcuts(ctx).renderDynamicList({
+        blueprint,
+        targetContainer,
+        data,
+        ...options
+      });
+    },
+    /**
+     * Set state value
+     */
+    setState: (key, value) => {
+      if (ctx.stateManager) {
+        ctx.stateManager.set(key, value, ctx.elementId);
+        return { success: true };
+      }
+      return { success: false, error: "No state manager" };
+    },
+    /**
+     * Get state value
+     */
+    getState: (key) => {
+      if (ctx.stateManager) {
+        return ctx.stateManager.get(key);
+      }
+      return void 0;
+    },
+    /**
+     * Toggle state value
+     */
+    toggleState: (key) => {
+      if (ctx.stateManager) {
+        ctx.stateManager.toggle(key, ctx.elementId);
+        return { success: true };
+      }
+      return { success: false, error: "No state manager" };
+    },
+    /**
+     * Navigate to URL
+     */
+    navigateTo: (url, options) => {
+      navigateTo(url, options);
+      return { success: true };
+    },
+    /**
+     * Log to console (for debugging)
+     */
+    log: (...args) => {
+      console.log("[Servly]", ...args);
+    },
+    /**
+     * Show alert
+     */
+    alert: (message) => {
+      if (typeof alert !== "undefined") {
+        alert(message);
+      }
+    },
+    /**
+     * Get element by ID
+     */
+    getElement: (id) => {
+      if (typeof document === "undefined") return null;
+      return document.querySelector(`[data-servly-id="${id}"]`) || document.getElementById(id);
+    },
+    /**
+     * Set element text content
+     */
+    setText: (selector, text) => {
+      if (typeof document === "undefined") return { success: false };
+      const el = document.querySelector(selector) || document.querySelector(`[data-servly-id="${selector.replace("#", "")}"]`);
+      if (el) {
+        el.textContent = text;
+        return { success: true };
+      }
+      return { success: false, error: "Element not found" };
+    },
+    /**
+     * Add class to element
+     */
+    addClass: (selector, className) => {
+      if (typeof document === "undefined") return { success: false };
+      const el = document.querySelector(selector);
+      if (el) {
+        el.classList.add(className);
+        return { success: true };
+      }
+      return { success: false, error: "Element not found" };
+    },
+    /**
+     * Remove class from element
+     */
+    removeClass: (selector, className) => {
+      if (typeof document === "undefined") return { success: false };
+      const el = document.querySelector(selector);
+      if (el) {
+        el.classList.remove(className);
+        return { success: true };
+      }
+      return { success: false, error: "Element not found" };
+    },
+    /**
+     * Toggle class on element
+     */
+    toggleClass: (selector, className) => {
+      if (typeof document === "undefined") return { success: false };
+      const el = document.querySelector(selector);
+      if (el) {
+        el.classList.toggle(className);
+        return { success: true };
+      }
+      return { success: false, error: "Element not found" };
+    },
+    /**
+     * Local storage helpers
+     */
+    localStorage: {
+      get: (key, defaultValue) => getLocalStorage(key, defaultValue),
+      set: (key, value) => setLocalStorage(key, value),
+      remove: (key) => {
+        if (typeof localStorage !== "undefined") {
+          localStorage.removeItem(key);
+        }
+      }
+    },
+    /**
+     * Session storage helpers
+     */
+    sessionStorage: {
+      get: (key, defaultValue) => getSessionStorage(key, defaultValue),
+      set: (key, value) => setSessionStorage(key, value),
+      remove: (key) => {
+        if (typeof sessionStorage !== "undefined") {
+          sessionStorage.removeItem(key);
+        }
+      }
+    },
+    /**
+     * Clipboard helpers
+     */
+    clipboard: {
+      copy: async (text) => {
+        if (typeof navigator !== "undefined" && navigator.clipboard) {
+          try {
+            await navigator.clipboard.writeText(text);
+            return { success: true };
+          } catch (error) {
+            return { success: false, error };
+          }
+        }
+        return { success: false, error: "Clipboard not available" };
+      }
+    },
+    /**
+     * Delay execution
+     */
+    delay: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    /**
+     * Current context accessors
+     */
+    currentItem: ctx.currentItem,
+    currentIndex: ctx.currentIndex,
+    elementId: ctx.elementId
+  };
+}
 var builtInPlugins = {
   /**
    * Set state value
@@ -2563,6 +2854,7 @@ var builtInPlugins = {
     const code = action.code || action.config?.code;
     if (!code) return { success: false, error: "No code provided" };
     try {
+      const shortcuts = createShortcuts(ctx);
       const fn = new Function(
         "event",
         "props",
@@ -2571,6 +2863,7 @@ var builtInPlugins = {
         "stateManager",
         "currentItem",
         "currentIndex",
+        "shortcuts",
         code
       );
       const result = fn(
@@ -2580,7 +2873,8 @@ var builtInPlugins = {
         ctx.context.context || {},
         ctx.stateManager,
         ctx.currentItem,
-        ctx.currentIndex
+        ctx.currentIndex,
+        shortcuts
       );
       return { success: true, result };
     } catch (error) {
@@ -5296,18 +5590,78 @@ async function mount(options) {
     eventHandlers,
     fetchOptions = {},
     onReady,
-    onError
+    onError,
+    onLoadStart,
+    onLoadEnd,
+    loadingComponent,
+    errorComponent,
+    loadingDelay = 0,
+    minLoadingTime = 0
   } = options;
+  const container = typeof target === "string" ? document.querySelector(target) : target;
+  if (!container) {
+    const err = new Error(`Target container not found: ${target}`);
+    onError?.(err);
+    throw err;
+  }
+  let loadingElement = null;
+  let loadingTimeout = null;
+  let loadingStartTime = null;
+  const showLoading = () => {
+    if (loadingComponent) {
+      loadingStartTime = Date.now();
+      if (typeof loadingComponent === "string") {
+        loadingElement = document.createElement("div");
+        loadingElement.innerHTML = loadingComponent;
+        loadingElement = loadingElement.firstElementChild || loadingElement;
+      } else {
+        loadingElement = loadingComponent.cloneNode(true);
+      }
+      container.appendChild(loadingElement);
+    }
+  };
+  const removeLoading = async () => {
+    if (loadingTimeout) {
+      clearTimeout(loadingTimeout);
+      loadingTimeout = null;
+    }
+    if (loadingStartTime && minLoadingTime > 0) {
+      const elapsed = Date.now() - loadingStartTime;
+      if (elapsed < minLoadingTime) {
+        await new Promise((resolve) => setTimeout(resolve, minLoadingTime - elapsed));
+      }
+    }
+    if (loadingElement && loadingElement.parentNode) {
+      loadingElement.parentNode.removeChild(loadingElement);
+      loadingElement = null;
+    }
+  };
+  const showError = (err) => {
+    if (errorComponent) {
+      const errorContent = errorComponent(err);
+      if (typeof errorContent === "string") {
+        container.innerHTML = errorContent;
+      } else {
+        container.innerHTML = "";
+        container.appendChild(errorContent);
+      }
+    }
+  };
   try {
-    const container = typeof target === "string" ? document.querySelector(target) : target;
-    if (!container) {
-      throw new Error(`Target container not found: ${target}`);
+    onLoadStart?.();
+    if (loadingComponent) {
+      if (loadingDelay > 0) {
+        loadingTimeout = setTimeout(showLoading, loadingDelay);
+      } else {
+        showLoading();
+      }
     }
     const fetchResult = await fetchComponentWithDependencies(componentId, {
       ...fetchOptions,
       version
     });
     const { data, fromCache, version: resolvedVersion, registry, views } = fetchResult;
+    await removeLoading();
     const bindingContext = {
       props,
       state,
@@ -5338,10 +5692,14 @@ async function mount(options) {
       fromCache,
       version: resolvedVersion
     };
+    onLoadEnd?.();
     onReady?.(result);
     return result;
   } catch (error) {
     const err = error instanceof Error ? error : new Error(String(error));
+    await removeLoading();
+    showError(err);
+    onLoadEnd?.();
     onError?.(err);
     throw err;
   }
@@ -5387,6 +5745,108 @@ function mountData(options) {
   };
 }
 
+// src/prefetch.ts
+async function prefetch(componentId, version = "latest", options = {}) {
+  const { includeDependencies = true, ...fetchOptions } = options;
+  try {
+    if (includeDependencies) {
+      await fetchComponentWithDependencies(componentId, { ...fetchOptions, version });
+    } else {
+      await fetchComponent(componentId, { ...fetchOptions, version });
+    }
+    return true;
+  } catch (error) {
+    console.warn(`[Servly] Failed to prefetch ${componentId}:`, error);
+    return false;
+  }
+}
+async function prefetchAll(components, options = {}) {
+  const results = await Promise.allSettled(
+    components.map((comp) => {
+      const id = typeof comp === "string" ? comp : comp.id;
+      const version = typeof comp === "string" ? "latest" : comp.version || "latest";
+      return prefetch(id, version, options).then((success2) => ({ id, success: success2 }));
+    })
+  );
+  const success = [];
+  const failed = [];
+  for (const result of results) {
+    if (result.status === "fulfilled" && result.value.success) {
+      success.push(result.value.id);
+    } else {
+      const id = result.status === "fulfilled" ? result.value.id : "unknown";
+      failed.push(id);
+    }
+  }
+  return { success, failed };
+}
+function prefetchOnVisible(target, components, options = {}) {
+  const { rootMargin = "100px", threshold = 0, ...prefetchOptions } = options;
+  const element = typeof target === "string" ? document.querySelector(target) : target;
+  if (!element) {
+    console.warn(`[Servly] prefetchOnVisible: Target not found: ${target}`);
+    return () => {
+    };
+  }
+  let hasPrefetched = false;
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting && !hasPrefetched) {
+          hasPrefetched = true;
+          prefetchAll(components, prefetchOptions);
+          observer.disconnect();
+        }
+      }
+    },
+    { rootMargin, threshold }
+  );
+  observer.observe(element);
+  return () => observer.disconnect();
+}
+function prefetchOnIdle(components, options = {}) {
+  const { timeout = 5e3, ...prefetchOptions } = options;
+  const callback = () => {
+    prefetchAll(components, prefetchOptions);
+  };
+  if ("requestIdleCallback" in window) {
+    window.requestIdleCallback(callback, { timeout });
+  } else {
+    setTimeout(callback, 1);
+  }
+}
+function prefetchOnHover(target, componentId, version = "latest", options = {}) {
+  const { delay = 100, ...prefetchOptions } = options;
+  const element = typeof target === "string" ? document.querySelector(target) : target;
+  if (!element) {
+    console.warn(`[Servly] prefetchOnHover: Target not found: ${target}`);
+    return () => {
+    };
+  }
+  let timeoutId = null;
+  let hasPrefetched = false;
+  const handleMouseEnter = () => {
+    if (hasPrefetched) return;
+    timeoutId = setTimeout(() => {
+      hasPrefetched = true;
+      prefetch(componentId, version, prefetchOptions);
+    }, delay);
+  };
+  const handleMouseLeave = () => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+  element.addEventListener("mouseenter", handleMouseEnter);
+  element.addEventListener("mouseleave", handleMouseLeave);
+  return () => {
+    element.removeEventListener("mouseenter", handleMouseEnter);
+    element.removeEventListener("mouseleave", handleMouseLeave);
+    if (timeoutId) clearTimeout(timeoutId);
+  };
+}
+
 // src/version.ts
 function parseVersion(version) {
   const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
@@ -5757,6 +6217,55 @@ function getSampleValue(def) {
 // src/index.ts
 init_registry();
 init_tailwind();
+
+// src/slotBindings.ts
+function extractSlotBindings(layout) {
+  const bindings = /* @__PURE__ */ new Map();
+  const elementMap = /* @__PURE__ */ new Map();
+  for (const element of layout) {
+    elementMap.set(element.i, element);
+  }
+  const traceToProps = (element, propPath, visited = /* @__PURE__ */ new Set()) => {
+    if (visited.has(element.i)) return null;
+    visited.add(element.i);
+    const inputs = element.configuration?.bindings?.inputs || {};
+    const binding = inputs[propPath];
+    if (!binding) return null;
+    if (binding.source === "props" && binding.path) {
+      return binding.path;
+    }
+    if (binding.source === "parent" && binding.path && element.parent) {
+      const parentElement = elementMap.get(element.parent);
+      if (parentElement) {
+        return traceToProps(parentElement, binding.path, visited);
+      }
+    }
+    return null;
+  };
+  for (const element of layout) {
+    if (element.componentId !== "slot") continue;
+    const inputs = element.configuration?.bindings?.inputs || {};
+    const slotId = element.configuration?.slotName || element.i;
+    for (const [targetProp, binding] of Object.entries(inputs)) {
+      if (["child", "children", "content"].includes(targetProp)) {
+        const b = binding;
+        if (!b) continue;
+        if (b.source === "props" && b.path) {
+          bindings.set(b.path, slotId);
+        } else if (b.source === "parent" && b.path && element.parent) {
+          const parentElement = elementMap.get(element.parent);
+          if (parentElement) {
+            const originalProp = traceToProps(parentElement, b.path);
+            if (originalProp) {
+              bindings.set(originalProp, slotId);
+            }
+          }
+        }
+      }
+    }
+  }
+  return bindings;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AnalyticsCollector,
@@ -5806,6 +6315,7 @@ init_tailwind();
   extractDependenciesFromCode,
   extractOverrideDependencies,
   extractReferencedViewIds,
+  extractSlotBindings,
   fetchComponent,
   fetchComponentWithDependencies,
   formatStyleValue,
@@ -5863,7 +6373,12 @@ init_tailwind();
   mountData,
   navigateTo,
   parseVersion,
+  prefetch,
+  prefetchAll,
   prefetchComponents,
+  prefetchOnHover,
+  prefetchOnIdle,
+  prefetchOnVisible,
   preloadIcons,
   preloadTailwind,
   preventFOUC,

package/dist/index.js

@@ -718,8 +718,96 @@ function resolveBindingPath(path, context) {
   }
   return navigatePath(source, parts.slice(startIndex));
 }
+var FUNCTION_CALL_REGEX = /^(\w+)\s*\((.*)\)$/s;
+function executeGlobalFunction(funcName, argsStr, context) {
+  if (context.functionMap?.[funcName]) {
+    try {
+      const args = parseFunctionArguments(argsStr, context);
+      return context.functionMap[funcName](...args);
+    } catch (error) {
+      console.error(`[GlobalFunction] Error executing ${funcName}:`, error);
+      return void 0;
+    }
+  }
+  const func = context.globalFunctions?.find((f) => f.name === funcName);
+  if (!func) {
+    console.warn(`[GlobalFunction] Function not found: ${funcName}`);
+    return void 0;
+  }
+  try {
+    const args = parseFunctionArguments(argsStr, context);
+    const paramNames = func.parameters.map((p) => p.name);
+    const fnBody = `
+      const state = __ctx__.state || {};
+      const props = __ctx__.props || {};
+      const config = __ctx__.configs || __ctx__.context || {};
+      ${func.code}
+    `;
+    const fn = new Function("__ctx__", ...paramNames, fnBody);
+    return fn(context, ...args);
+  } catch (error) {
+    console.error(`[GlobalFunction] Error executing ${funcName}:`, error);
+    return void 0;
+  }
+}
+function parseFunctionArguments(argsStr, context) {
+  if (!argsStr.trim()) return [];
+  const args = [];
+  let current = "";
+  let depth = 0;
+  let inString = false;
+  let stringChar = "";
+  for (let i = 0; i < argsStr.length; i++) {
+    const char = argsStr[i];
+    const prevChar = argsStr[i - 1];
+    if ((char === '"' || char === "'") && prevChar !== "\\") {
+      if (!inString) {
+        inString = true;
+        stringChar = char;
+      } else if (char === stringChar) {
+        inString = false;
+      }
+    }
+    if (!inString) {
+      if (char === "(" || char === "[" || char === "{") depth++;
+      if (char === ")" || char === "]" || char === "}") depth--;
+    }
+    if (char === "," && depth === 0 && !inString) {
+      args.push(parseArgumentValue(current.trim(), context));
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  if (current.trim()) {
+    args.push(parseArgumentValue(current.trim(), context));
+  }
+  return args;
+}
+function parseArgumentValue(value, context) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  if (!isNaN(Number(trimmed)) && trimmed !== "") {
+    return Number(trimmed);
+  }
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null") return null;
+  if (trimmed === "undefined") return void 0;
+  if (trimmed.startsWith("{{") && trimmed.endsWith("}}")) {
+    return resolveTemplateValue(trimmed, context);
+  }
+  return resolveBindingPath(trimmed, context);
+}
 function resolveExpression(expression, context) {
   const trimmed = expression.trim();
+  const funcMatch = trimmed.match(FUNCTION_CALL_REGEX);
+  if (funcMatch) {
+    const [, funcName, argsStr] = funcMatch;
+    return executeGlobalFunction(funcName, argsStr, context);
+  }
   const comparisonOperators = ["===", "!==", "==", "!=", ">=", "<=", ">", "<"];
   for (const op of comparisonOperators) {
     if (trimmed.includes(op)) {
@@ -1636,6 +1724,203 @@ function getUrlInfo() {
 }
 
 // src/eventSystem.ts
+function createShortcuts(ctx) {
+  return {
+    /**
+     * Render a dynamic list of items using a blueprint view
+     * This is a simplified version for runtime - full implementation requires DOM access
+     */
+    renderDynamicList: (options) => {
+      const { blueprint, targetContainer, data = [], clearExisting = true, itemProps = {} } = options;
+      const container = typeof document !== "undefined" ? document.querySelector(targetContainer) || document.querySelector(`[data-servly-id="${targetContainer.replace("#", "")}"]`) : null;
+      if (!container) {
+        console.warn(`[shortcuts.renderDynamicList] Container not found: ${targetContainer}`);
+        return { success: false, error: "Container not found" };
+      }
+      if (clearExisting) {
+        container.innerHTML = "";
+      }
+      const event = new CustomEvent("servly:renderDynamicList", {
+        bubbles: true,
+        detail: {
+          blueprint,
+          targetContainer,
+          data,
+          itemProps,
+          container
+        }
+      });
+      container.dispatchEvent(event);
+      return { success: true, itemCount: data.length };
+    },
+    /**
+     * Quick list rendering helper
+     */
+    renderList: (blueprint, targetContainer, data, options = {}) => {
+      return createShortcuts(ctx).renderDynamicList({
+        blueprint,
+        targetContainer,
+        data,
+        ...options
+      });
+    },
+    /**
+     * Set state value
+     */
+    setState: (key, value) => {
+      if (ctx.stateManager) {
+        ctx.stateManager.set(key, value, ctx.elementId);
+        return { success: true };
+      }
+      return { success: false, error: "No state manager" };
+    },
+    /**
+     * Get state value
+     */
+    getState: (key) => {
+      if (ctx.stateManager) {
+        return ctx.stateManager.get(key);
+      }
+      return void 0;
+    },
+    /**
+     * Toggle state value
+     */
+    toggleState: (key) => {
+      if (ctx.stateManager) {
+        ctx.stateManager.toggle(key, ctx.elementId);
+        return { success: true };
+      }
+      return { success: false, error: "No state manager" };
+    },
+    /**
+     * Navigate to URL
+     */
+    navigateTo: (url, options) => {
+      navigateTo(url, options);
+      return { success: true };
+    },
+    /**
+     * Log to console (for debugging)
+     */
+    log: (...args) => {
+      console.log("[Servly]", ...args);
+    },
+    /**
+     * Show alert
+     */
+    alert: (message) => {
+      if (typeof alert !== "undefined") {
+        alert(message);
+      }
+    },
+    /**
+     * Get element by ID
+     */
+    getElement: (id) => {
+      if (typeof document === "undefined") return null;
+      return document.querySelector(`[data-servly-id="${id}"]`) || document.getElementById(id);
+    },
+    /**
+     * Set element text content
+     */
+    setText: (selector, text) => {
+      if (typeof document === "undefined") return { success: false };
+      const el = document.querySelector(selector) || document.querySelector(`[data-servly-id="${selector.replace("#", "")}"]`);
+      if (el) {
+        el.textContent = text;
+        return { success: true };
+      }
+      return { success: false, error: "Element not found" };
+    },
+    /**
+     * Add class to element
+     */
+    addClass: (selector, className) => {
+      if (typeof document === "undefined") return { success: false };
+      const el = document.querySelector(selector);
+      if (el) {
+        el.classList.add(className);
+        return { success: true };
+      }
+      return { success: false, error: "Element not found" };
+    },
+    /**
+     * Remove class from element
+     */
+    removeClass: (selector, className) => {
+      if (typeof document === "undefined") return { success: false };
+      const el = document.querySelector(selector);
+      if (el) {
+        el.classList.remove(className);
+        return { success: true };
+      }
+      return { success: false, error: "Element not found" };
+    },
+    /**
+     * Toggle class on element
+     */
+    toggleClass: (selector, className) => {
+      if (typeof document === "undefined") return { success: false };
+      const el = document.querySelector(selector);
+      if (el) {
+        el.classList.toggle(className);
+        return { success: true };
+      }
+      return { success: false, error: "Element not found" };
+    },
+    /**
+     * Local storage helpers
+     */
+    localStorage: {
+      get: (key, defaultValue) => getLocalStorage(key, defaultValue),
+      set: (key, value) => setLocalStorage(key, value),
+      remove: (key) => {
+        if (typeof localStorage !== "undefined") {
+          localStorage.removeItem(key);
+        }
+      }
+    },
+    /**
+     * Session storage helpers
+     */
+    sessionStorage: {
+      get: (key, defaultValue) => getSessionStorage(key, defaultValue),
+      set: (key, value) => setSessionStorage(key, value),
+      remove: (key) => {
+        if (typeof sessionStorage !== "undefined") {
+          sessionStorage.removeItem(key);
+        }
+      }
+    },
+    /**
+     * Clipboard helpers
+     */
+    clipboard: {
+      copy: async (text) => {
+        if (typeof navigator !== "undefined" && navigator.clipboard) {
+          try {
+            await navigator.clipboard.writeText(text);
+            return { success: true };
+          } catch (error) {
+            return { success: false, error };
+          }
+        }
+        return { success: false, error: "Clipboard not available" };
+      }
+    },
+    /**
+     * Delay execution
+     */
+    delay: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    /**
+     * Current context accessors
+     */
+    currentItem: ctx.currentItem,
+    currentIndex: ctx.currentIndex,
+    elementId: ctx.elementId
+  };
+}
 var builtInPlugins = {
   /**
    * Set state value
@@ -1762,6 +2047,7 @@ var builtInPlugins = {
     const code = action.code || action.config?.code;
     if (!code) return { success: false, error: "No code provided" };
     try {
+      const shortcuts = createShortcuts(ctx);
       const fn = new Function(
         "event",
         "props",
@@ -1770,6 +2056,7 @@ var builtInPlugins = {
         "stateManager",
         "currentItem",
         "currentIndex",
+        "shortcuts",
         code
       );
       const result = fn(
@@ -1779,7 +2066,8 @@ var builtInPlugins = {
         ctx.context.context || {},
         ctx.stateManager,
         ctx.currentItem,
-        ctx.currentIndex
+        ctx.currentIndex,
+        shortcuts
       );
       return { success: true, result };
     } catch (error) {
@@ -4491,18 +4779,78 @@ async function mount(options) {
     eventHandlers,
     fetchOptions = {},
     onReady,
-    onError
+    onError,
+    onLoadStart,
+    onLoadEnd,
+    loadingComponent,
+    errorComponent,
+    loadingDelay = 0,
+    minLoadingTime = 0
   } = options;
+  const container = typeof target === "string" ? document.querySelector(target) : target;
+  if (!container) {
+    const err = new Error(`Target container not found: ${target}`);
+    onError?.(err);
+    throw err;
+  }
+  let loadingElement = null;
+  let loadingTimeout = null;
+  let loadingStartTime = null;
+  const showLoading = () => {
+    if (loadingComponent) {
+      loadingStartTime = Date.now();
+      if (typeof loadingComponent === "string") {
+        loadingElement = document.createElement("div");
+        loadingElement.innerHTML = loadingComponent;
+        loadingElement = loadingElement.firstElementChild || loadingElement;
+      } else {
+        loadingElement = loadingComponent.cloneNode(true);
+      }
+      container.appendChild(loadingElement);
+    }
+  };
+  const removeLoading = async () => {
+    if (loadingTimeout) {
+      clearTimeout(loadingTimeout);
+      loadingTimeout = null;
+    }
+    if (loadingStartTime && minLoadingTime > 0) {
+      const elapsed = Date.now() - loadingStartTime;
+      if (elapsed < minLoadingTime) {
+        await new Promise((resolve) => setTimeout(resolve, minLoadingTime - elapsed));
+      }
+    }
+    if (loadingElement && loadingElement.parentNode) {
+      loadingElement.parentNode.removeChild(loadingElement);
+      loadingElement = null;
+    }
+  };
+  const showError = (err) => {
+    if (errorComponent) {
+      const errorContent = errorComponent(err);
+      if (typeof errorContent === "string") {
+        container.innerHTML = errorContent;
+      } else {
+        container.innerHTML = "";
+        container.appendChild(errorContent);
+      }
+    }
+  };
   try {
-    const container = typeof target === "string" ? document.querySelector(target) : target;
-    if (!container) {
-      throw new Error(`Target container not found: ${target}`);
+    onLoadStart?.();
+    if (loadingComponent) {
+      if (loadingDelay > 0) {
+        loadingTimeout = setTimeout(showLoading, loadingDelay);
+      } else {
+        showLoading();
+      }
     }
     const fetchResult = await fetchComponentWithDependencies(componentId, {
       ...fetchOptions,
       version
     });
     const { data, fromCache, version: resolvedVersion, registry, views } = fetchResult;
+    await removeLoading();
     const bindingContext = {
       props,
       state,
@@ -4533,10 +4881,14 @@ async function mount(options) {
       fromCache,
       version: resolvedVersion
     };
+    onLoadEnd?.();
     onReady?.(result);
     return result;
   } catch (error) {
     const err = error instanceof Error ? error : new Error(String(error));
+    await removeLoading();
+    showError(err);
+    onLoadEnd?.();
     onError?.(err);
     throw err;
   }
@@ -4582,6 +4934,108 @@ function mountData(options) {
   };
 }
 
+// src/prefetch.ts
+async function prefetch(componentId, version = "latest", options = {}) {
+  const { includeDependencies = true, ...fetchOptions } = options;
+  try {
+    if (includeDependencies) {
+      await fetchComponentWithDependencies(componentId, { ...fetchOptions, version });
+    } else {
+      await fetchComponent(componentId, { ...fetchOptions, version });
+    }
+    return true;
+  } catch (error) {
+    console.warn(`[Servly] Failed to prefetch ${componentId}:`, error);
+    return false;
+  }
+}
+async function prefetchAll(components, options = {}) {
+  const results = await Promise.allSettled(
+    components.map((comp) => {
+      const id = typeof comp === "string" ? comp : comp.id;
+      const version = typeof comp === "string" ? "latest" : comp.version || "latest";
+      return prefetch(id, version, options).then((success2) => ({ id, success: success2 }));
+    })
+  );
+  const success = [];
+  const failed = [];
+  for (const result of results) {
+    if (result.status === "fulfilled" && result.value.success) {
+      success.push(result.value.id);
+    } else {
+      const id = result.status === "fulfilled" ? result.value.id : "unknown";
+      failed.push(id);
+    }
+  }
+  return { success, failed };
+}
+function prefetchOnVisible(target, components, options = {}) {
+  const { rootMargin = "100px", threshold = 0, ...prefetchOptions } = options;
+  const element = typeof target === "string" ? document.querySelector(target) : target;
+  if (!element) {
+    console.warn(`[Servly] prefetchOnVisible: Target not found: ${target}`);
+    return () => {
+    };
+  }
+  let hasPrefetched = false;
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting && !hasPrefetched) {
+          hasPrefetched = true;
+          prefetchAll(components, prefetchOptions);
+          observer.disconnect();
+        }
+      }
+    },
+    { rootMargin, threshold }
+  );
+  observer.observe(element);
+  return () => observer.disconnect();
+}
+function prefetchOnIdle(components, options = {}) {
+  const { timeout = 5e3, ...prefetchOptions } = options;
+  const callback = () => {
+    prefetchAll(components, prefetchOptions);
+  };
+  if ("requestIdleCallback" in window) {
+    window.requestIdleCallback(callback, { timeout });
+  } else {
+    setTimeout(callback, 1);
+  }
+}
+function prefetchOnHover(target, componentId, version = "latest", options = {}) {
+  const { delay = 100, ...prefetchOptions } = options;
+  const element = typeof target === "string" ? document.querySelector(target) : target;
+  if (!element) {
+    console.warn(`[Servly] prefetchOnHover: Target not found: ${target}`);
+    return () => {
+    };
+  }
+  let timeoutId = null;
+  let hasPrefetched = false;
+  const handleMouseEnter = () => {
+    if (hasPrefetched) return;
+    timeoutId = setTimeout(() => {
+      hasPrefetched = true;
+      prefetch(componentId, version, prefetchOptions);
+    }, delay);
+  };
+  const handleMouseLeave = () => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+  element.addEventListener("mouseenter", handleMouseEnter);
+  element.addEventListener("mouseleave", handleMouseLeave);
+  return () => {
+    element.removeEventListener("mouseenter", handleMouseEnter);
+    element.removeEventListener("mouseleave", handleMouseLeave);
+    if (timeoutId) clearTimeout(timeoutId);
+  };
+}
+
 // src/version.ts
 function parseVersion(version) {
   const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
@@ -4948,6 +5402,55 @@ function getSampleValue(def) {
       return def.defaultValue;
   }
 }
+
+// src/slotBindings.ts
+function extractSlotBindings(layout) {
+  const bindings = /* @__PURE__ */ new Map();
+  const elementMap = /* @__PURE__ */ new Map();
+  for (const element of layout) {
+    elementMap.set(element.i, element);
+  }
+  const traceToProps = (element, propPath, visited = /* @__PURE__ */ new Set()) => {
+    if (visited.has(element.i)) return null;
+    visited.add(element.i);
+    const inputs = element.configuration?.bindings?.inputs || {};
+    const binding = inputs[propPath];
+    if (!binding) return null;
+    if (binding.source === "props" && binding.path) {
+      return binding.path;
+    }
+    if (binding.source === "parent" && binding.path && element.parent) {
+      const parentElement = elementMap.get(element.parent);
+      if (parentElement) {
+        return traceToProps(parentElement, binding.path, visited);
+      }
+    }
+    return null;
+  };
+  for (const element of layout) {
+    if (element.componentId !== "slot") continue;
+    const inputs = element.configuration?.bindings?.inputs || {};
+    const slotId = element.configuration?.slotName || element.i;
+    for (const [targetProp, binding] of Object.entries(inputs)) {
+      if (["child", "children", "content"].includes(targetProp)) {
+        const b = binding;
+        if (!b) continue;
+        if (b.source === "props" && b.path) {
+          bindings.set(b.path, slotId);
+        } else if (b.source === "parent" && b.path && element.parent) {
+          const parentElement = elementMap.get(element.parent);
+          if (parentElement) {
+            const originalProp = traceToProps(parentElement, b.path);
+            if (originalProp) {
+              bindings.set(originalProp, slotId);
+            }
+          }
+        }
+      }
+    }
+  }
+  return bindings;
+}
 export {
   AnalyticsCollector,
   DEFAULT_CACHE_CONFIG,
@@ -4996,6 +5499,7 @@ export {
   extractDependenciesFromCode,
   extractOverrideDependencies,
   extractReferencedViewIds,
+  extractSlotBindings,
   fetchComponent,
   fetchComponentWithDependencies,
   formatStyleValue,
@@ -5053,7 +5557,12 @@ export {
   mountData,
   navigateTo,
   parseVersion,
+  prefetch,
+  prefetchAll,
   prefetchComponents,
+  prefetchOnHover,
+  prefetchOnIdle,
+  prefetchOnVisible,
   preloadIcons,
   preloadTailwind,
   preventFOUC,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@servlyadmin/runtime-core",
-  "version": "0.1.46",
-  "description": "Framework-agnostic core renderer for Servly components",
+  "version": "0.2.1",
+  "description": "Framework-agnostic core renderer for Servly components with prefetching and loading states",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",