@vc-shell/framework 1.2.4-beta.3 → 1.2.4-beta.5

package/core/composables/useWebVitals/index.ts

@@ -0,0 +1,40 @@
+import { onFCP, onLCP, onCLS, onINP, onTTFB } from "web-vitals";
+import type { Metric } from "web-vitals";
+
+export interface IWebVitalsMetric {
+  name: string;
+  value: number;
+  rating: "good" | "needs-improvement" | "poor";
+}
+
+export type WebVitalsCallback = (metric: IWebVitalsMetric) => void;
+
+/**
+ * Registers Core Web Vitals observers (FCP, LCP, CLS, INP, TTFB).
+ * Call once per app session, typically after app.mount().
+ *
+ * @param callback - Optional custom handler. Defaults to console.warn in dev mode.
+ */
+export function useWebVitals(callback?: WebVitalsCallback): void {
+  const defaultCallback: WebVitalsCallback = (metric) => {
+    if (import.meta.env.DEV) {
+      const unit = metric.name === "CLS" ? "" : "ms";
+      const value = metric.name === "CLS" ? metric.value.toFixed(4) : Math.round(metric.value);
+      console.warn(`[web-vitals] ${metric.name}: ${value}${unit} (${metric.rating})`);
+    }
+  };
+
+  const handler = (metric: Metric) => {
+    (callback ?? defaultCallback)({
+      name: metric.name,
+      value: metric.value,
+      rating: metric.rating,
+    });
+  };
+
+  onFCP(handler);
+  onLCP(handler);
+  onCLS(handler);
+  onINP(handler);
+  onTTFB(handler);
+}

package/core/interceptors/index.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { Router } from "vue-router";
 import { useUserManagement } from "@core/composables/useUserManagement";
-import { notification } from "@shared";
+import { notification } from "@shared/components/notifications/core/notification";
 import { createLogger } from "@core/utilities";
 
 const logger = createLogger("interceptors");
@@ -49,24 +49,81 @@ export function registerInterceptors(router: Router) {
         }
       });
     } else {
-      const response = await originalFetch(...args);
+      const [resource, init] = args;
 
-      /**
-       * If the response is unauthorized, logout the user
-       */
-      if (response.status === 401) {
-        //logout user
-        if (isAuthenticated.value) {
-          signOut().then(() => {
-            redirect(router);
-            notification.error(
-              "Access Denied: Your session has expired or you do not have the necessary permissions.\nPlease log in again or contact the administrator for assistance.",
-            );
-          });
+      function isApiRequest(input: RequestInfo | URL): boolean {
+        const raw = typeof input === "string"
+          ? input
+          : input instanceof Request
+            ? input.url
+            : input.toString();
+
+        try {
+          const url = new URL(raw, window.location.origin);
+          return url.origin === window.location.origin && url.pathname.startsWith("/api/");
+        } catch {
+          return false;
         }
       }
 
-      return response;
+      // Scope hardening only to platform API calls
+      if (!isApiRequest(resource)) {
+        return originalFetch(...args);
+      }
+
+      if (!navigator.onLine) {
+        logger.warn("Request blocked: browser is offline", resource);
+        return Promise.reject(new Error("Network unavailable. Please check your connection."));
+      }
+
+      // Always enforce timeout, but preserve external cancellation semantics
+      const controller = new AbortController();
+      let didTimeout = false;
+      const timeoutId = setTimeout(() => {
+        didTimeout = true;
+        controller.abort();
+      }, 30000);
+
+      const externalSignal = init?.signal;
+      const abortFromExternal = () => controller.abort();
+      if (externalSignal?.aborted) {
+        abortFromExternal();
+      } else if (externalSignal) {
+        externalSignal.addEventListener("abort", abortFromExternal, { once: true });
+      }
+
+      try {
+        const response = await originalFetch(resource, {
+          ...(init || {}),
+          signal: controller.signal,
+        });
+
+        /**
+         * If the response is unauthorized, logout the user
+         */
+        if (response.status === 401) {
+          if (isAuthenticated.value) {
+            signOut().then(() => {
+              redirect(router);
+              notification.error(
+                "Access Denied: Your session has expired or you do not have the necessary permissions.\nPlease log in again or contact the administrator for assistance.",
+              );
+            });
+          }
+        }
+
+        return response;
+      } catch (e) {
+        if (didTimeout) {
+          throw new Error("Request timed out. Please try again.");
+        }
+        throw e;
+      } finally {
+        clearTimeout(timeoutId);
+        if (externalSignal) {
+          externalSignal.removeEventListener("abort", abortFromExternal);
+        }
+      }
     }
   };
 

package/core/plugins/ai-agent/components/_internal/VcAiAgentHeader.vue

@@ -41,7 +41,7 @@
 </template>
 
 <script lang="ts" setup>
-import { VcIcon } from "@ui/components";
+import { VcIcon } from "@ui/components/atoms/vc-icon";
 import VcVirtoOzLogo from "@core/plugins/ai-agent/components/_internal/VcVirtoOzLogo.vue";
 
 defineProps<{

package/core/plugins/ai-agent/components/_internal/VcAiAgentIframe.vue

@@ -24,7 +24,7 @@
 
 <script lang="ts" setup>
 import { ref, onMounted, watch } from "vue";
-import { VcIcon } from "@ui/components";
+import { VcIcon } from "@ui/components/atoms/vc-icon";
 import VcAiAgentLoader from "@core/plugins/ai-agent/components/_internal/VcAiAgentLoader.vue";
 
 const props = defineProps<{

package/core/plugins/global-error-handler/index.ts

@@ -0,0 +1,81 @@
+import type { App } from "vue";
+import { notification } from "@shared/components/notifications/core/notification";
+import { parseError } from "@core/utilities/error";
+import { createLogger } from "@core/utilities";
+
+const logger = createLogger("global-error-handler");
+
+function errorKey(err: unknown): string {
+  if (err instanceof Error) return `${err.name}:${err.message}`;
+  return String(err);
+}
+
+const recentErrors = new Map<string, number>();
+const DEDUP_WINDOW_MS = 3000;
+type WindowWithVcGlobalHandlers = Window & { __VC_GLOBAL_ERROR_HANDLERS_INSTALLED__?: boolean };
+
+function isDuplicate(err: unknown): boolean {
+  const key = errorKey(err);
+  const now = Date.now();
+  const last = recentErrors.get(key);
+  if (last && now - last < DEDUP_WINDOW_MS) return true;
+  recentErrors.set(key, now);
+  if (recentErrors.size > 50) {
+    for (const [k, t] of recentErrors) {
+      if (now - t > DEDUP_WINDOW_MS) recentErrors.delete(k);
+    }
+  }
+  return false;
+}
+
+export function setupGlobalErrorHandlers(app: App): void {
+  // 1. Vue component errors — chain to existing handler
+  const existingHandler = app.config.errorHandler;
+  app.config.errorHandler = (err, instance, info) => {
+    logger.error("Unhandled Vue error:", err, "\nInfo:", info);
+    if (!isDuplicate(err)) {
+      const parsed = parseError(err);
+      notification.error(parsed.message, {
+        timeout: 8000,
+        notificationId: `global-vue-${errorKey(err)}`,
+      });
+    }
+    existingHandler?.(err, instance, info);
+  };
+
+  if (typeof window === "undefined") return;
+  const win = window as WindowWithVcGlobalHandlers;
+
+  // Idempotency guard: prevent duplicated listeners when framework is installed multiple times
+  if (win.__VC_GLOBAL_ERROR_HANDLERS_INSTALLED__) return;
+  win.__VC_GLOBAL_ERROR_HANDLERS_INSTALLED__ = true;
+
+  const onUnhandledRejection = (event: PromiseRejectionEvent) => {
+    logger.error("Unhandled rejection:", event.reason);
+    if (!isDuplicate(event.reason)) {
+      const parsed = parseError(event.reason);
+      notification.error(parsed.message, {
+        timeout: 8000,
+        notificationId: `global-rejection-${errorKey(event.reason)}`,
+      });
+    }
+  };
+
+  // 2. Unhandled promise rejections
+  window.addEventListener("unhandledrejection", onUnhandledRejection);
+
+  const onWindowError = (event: ErrorEvent) => {
+    if (!event.error) return;
+    logger.error("Uncaught error:", event.error);
+    if (!isDuplicate(event.error)) {
+      const parsed = parseError(event.error);
+      notification.error(parsed.message, {
+        timeout: 8000,
+        notificationId: `global-error-${errorKey(event.error)}`,
+      });
+    }
+  };
+
+  // 3. Uncaught JS errors
+  window.addEventListener("error", onWindowError);
+}

package/core/plugins/index.ts

@@ -1,4 +1,3 @@
-export * from "@core/plugins/moment";
 export * from "@core/plugins/i18n";
 export * from "@core/plugins/validation";
 export * from "@core/plugins/modularity";

package/core/plugins/modularity/index.ts

@@ -1,9 +1,10 @@
 import { App, Component, inject, resolveComponent } from "vue";
 import { i18n } from "@core/plugins/i18n";
 import { Router } from "vue-router";
-import { BladeInstanceConstructor } from "@shared/components/blade-navigation/types";
+import type { BladeInstanceConstructor } from "@shared/components/blade-navigation/types";
 import { kebabToPascal, createLogger } from "@core/utilities";
-import { addMenuItem, useMenuService, useNotifications } from "@core/composables";
+import { addMenuItem, useMenuService } from "@core/composables/useMenuService";
+import { useNotifications } from "@core/composables/useNotifications";
 import * as _ from "lodash-es";
 import { notification } from "@shared/components/notifications/core";
 import { BladeRegistryKey, IBladeRegistrationData, IBladeRegistryInstance } from "@core/composables/useBladeRegistry";

package/core/plugins/modularity/loader.ts

@@ -1,6 +1,6 @@
-import { App, Plugin } from "vue";
+import { App, Plugin, ref } from "vue";
 import { Router } from "vue-router";
-import { DynamicModulesKey } from "@framework/injection-keys";
+import { DynamicModulesKey, ModulesReadyKey, ModulesLoadErrorKey } from "@framework/injection-keys";
 import * as semver from "semver";
 import { notification } from "@shared/components/notifications/core";
 import { createLogger } from "@core/utilities";
@@ -46,6 +46,7 @@ interface Apps {
       id: string;
       url: string;
       version?: string;
+      hash?: string;
     }[];
   };
 }
@@ -107,9 +108,9 @@ function loadCSS(url: string): Promise<void> {
   });
 }
 
-async function loadVersionInfo(url: string): Promise<VersionInfo | null> {
+async function loadVersionInfo(url: string, options?: RequestInit): Promise<VersionInfo | null> {
   try {
-    const response = await fetch(url);
+    const response = await fetch(url, options);
     if (!response.ok) {
       logger.warn(`Failed to load version info: ${response.statusText}`);
       return null;
@@ -121,12 +122,37 @@ async function loadVersionInfo(url: string): Promise<VersionInfo | null> {
   }
 }
 
+function sanitizeFileToken(value: string): string {
+  const safeValue = value.replace(/[^a-zA-Z0-9._-]/g, "_");
+  return safeValue || "unknown";
+}
+
+function appendQueryParam(url: string, key: string, value: string): string {
+  const separator = url.includes("?") ? "&" : "?";
+  return `${url}${separator}${key}=${encodeURIComponent(value)}`;
+}
+
+function hashString(value: string): string {
+  // Fast deterministic hash for cache keys in browser runtime.
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16);
+}
+
+function normalizeModuleUrl(url: string): string {
+  return url.replace(/^([^/])/, "/$1").replace(/([^/])$/, "$1/");
+}
+
 interface ModuleConfig {
   baseUrl: string;
   manifestFileName: string;
   entryPointKey: string;
   frameworkVersion: string;
   skipVersionCheck?: boolean;
+  forceFreshAssets?: boolean;
 }
 
 const DEFAULT_CONFIG: Partial<ModuleConfig> = {
@@ -134,6 +160,7 @@ const DEFAULT_CONFIG: Partial<ModuleConfig> = {
   entryPointKey: "isEntry",
   skipVersionCheck: false,
   frameworkVersion: "1.1.0",
+  forceFreshAssets: true,
 };
 
 function checkVersionCompatibility(
@@ -244,10 +271,24 @@ export function useDynamicModules(
   const loadedModules = new Set<string>();
   const loadedModulesWithVersions = new Map<string, string>();
 
+  // Progressive loading state — provided before mount so descendants can inject during setup
+  const modulesReady = ref(false);
+  const modulesLoadError = ref(false);
+  app.provide(ModulesReadyKey, modulesReady);
+  app.provide(ModulesLoadErrorKey, modulesLoadError);
+
   async function load() {
+    performance.mark("vc:modules-start");
+    let loadFailed = false;
     try {
-      const appsUrl = finalConfig.baseUrl + "apps.json";
-      const modules: Apps[] = await fetch(appsUrl).then((res) => res.json());
+      const shouldForceFreshAssets = finalConfig.forceFreshAssets !== false;
+      const requestTimestamp = Date.now().toString();
+      const fetchOptions: RequestInit | undefined = shouldForceFreshAssets ? { cache: "no-store" } : undefined;
+      const withCacheBust = (url: string, cacheKey?: string) =>
+        shouldForceFreshAssets ? appendQueryParam(url, "v", cacheKey ?? requestTimestamp) : url;
+
+      const appsUrl = withCacheBust(finalConfig.baseUrl + "apps.json");
+      const modules: Apps[] = await fetch(appsUrl, fetchOptions).then((res) => res.json());
 
       const module = modules.find((module) => module[appName]);
 
@@ -262,17 +303,44 @@ export function useDynamicModules(
             return null;
           }
 
-          const moduleUrl = module.url.replace(/^([^/])/, "/$1").replace(/([^/])$/, "$1/");
+          const moduleUrl = normalizeModuleUrl(module.url);
+          const manifestRequestCacheKey = module.hash || module.version || requestTimestamp;
+          const manifestCandidates = [
+            ...(module.hash ? [`manifest.${sanitizeFileToken(module.hash)}.json`] : []),
+            ...(module.version ? [`manifest.${sanitizeFileToken(module.version)}.json`] : []),
+            finalConfig.manifestFileName,
+          ];
           try {
-            const response = await fetch(moduleUrl + finalConfig.manifestFileName);
-            if (!response.ok) {
-              throw new Error(`Failed to load manifest for module '{ ${module.id} }': ${response.statusText}`);
+            let manifest: Manifest | null = null;
+            let moduleCacheKey = manifestRequestCacheKey;
+
+            for (const manifestFileName of manifestCandidates) {
+              const manifestUrl = withCacheBust(moduleUrl + manifestFileName, manifestRequestCacheKey);
+              const response = await fetch(manifestUrl, fetchOptions);
+              if (response.ok) {
+                const manifestText = await response.text();
+                manifest = JSON.parse(manifestText) as Manifest;
+                moduleCacheKey = module.hash || hashString(manifestText) || requestTimestamp;
+                break;
+              }
+
+              if (response.status !== 404) {
+                logger.warn(
+                  `Failed to load manifest '${manifestFileName}' for module '{ ${module.id} }': ${response.statusText}`,
+                );
+              }
             }
+
+            if (!manifest) {
+              throw new Error(`Failed to load manifest for module '{ ${module.id} }'`);
+            }
+
             return {
               moduleId: module.id,
               moduleUrl,
               moduleVersion: module.version,
-              manifest: (await response.json()) as Manifest,
+              moduleCacheKey,
+              manifest,
             };
           } catch (error) {
             logger.error("Error loading module manifest:", error);
@@ -286,56 +354,60 @@ export function useDynamicModules(
         );
 
         // Parallel loading of all modules
-        const moduleLoadPromises = validManifests.map(async ({ moduleId, moduleUrl, manifest, moduleVersion }) => {
-          try {
-            const entry = Object.values(manifest).find((file) => (file as ModuleManifest).isEntry);
-            if (!entry) {
-              throw new Error(`Entry file not found for module ${moduleId}`);
-            }
-
-            const versionFile = Object.values(manifest).find((file) => (file as VersionManifest).isVersionInfo) as
-              | VersionManifest
-              | undefined;
-
-            // Load version info and CSS in parallel
-            const [versionInfoFromFile] = await Promise.all([
-              versionFile ? loadVersionInfo(moduleUrl + versionFile.file) : Promise.resolve(null),
-              // Load CSS files in parallel
-              Promise.all(
-                Object.values(manifest)
-                  .filter((file) => file.file.endsWith(".css"))
-                  .map((file) => loadCSS(moduleUrl + file.file)),
-              ).catch((error) => {
-                logger.error(`Failed to load styles for module ${moduleId}:`, error);
-              }),
-            ]);
-
-            if (versionInfoFromFile) {
-              logger.info(`Loaded version info for module ${moduleId}: v${versionInfoFromFile.version}`);
-            }
+        const moduleLoadPromises = validManifests.map(
+          async ({ moduleId, moduleUrl, manifest, moduleVersion, moduleCacheKey }) => {
+            try {
+              const entry = Object.values(manifest).find((file) => (file as ModuleManifest).isEntry);
+              if (!entry) {
+                throw new Error(`Entry file not found for module ${moduleId}`);
+              }
 
-            // Import module
-            await import(/* @vite-ignore */ moduleUrl + entry.file);
+              const versionFile = Object.values(manifest).find((file) => (file as VersionManifest).isVersionInfo) as
+                | VersionManifest
+                | undefined;
+
+              // Load version info and CSS in parallel
+              const [versionInfoFromFile] = await Promise.all([
+                versionFile
+                  ? loadVersionInfo(withCacheBust(moduleUrl + versionFile.file, moduleCacheKey), fetchOptions)
+                  : Promise.resolve(null),
+                // Load CSS files in parallel
+                Promise.all(
+                  Object.values(manifest)
+                    .filter((file) => file.file.endsWith(".css"))
+                    .map((file) => loadCSS(withCacheBust(moduleUrl + file.file, moduleCacheKey))),
+                ).catch((error) => {
+                  logger.error(`Failed to load styles for module ${moduleId}:`, error);
+                }),
+              ]);
+
+              if (versionInfoFromFile) {
+                logger.info(`Loaded version info for module ${moduleId}: v${versionInfoFromFile.version}`);
+              }
 
-            return {
-              moduleId,
-              moduleUrl,
-              moduleVersion,
-              versionInfoFromFile,
-              success: true,
-            };
-          } catch (error) {
-            logger.error(`Failed to load module ${moduleId}:`, error);
-            return {
-              moduleId,
-              moduleUrl,
-              moduleVersion,
-              versionInfoFromFile: null,
-              success: false,
-              error,
-            };
-          }
-        });
+              // Import module
+              await import(/* @vite-ignore */ withCacheBust(moduleUrl + entry.file, moduleCacheKey));
+
+              return {
+                moduleId,
+                moduleUrl,
+                moduleVersion,
+                versionInfoFromFile,
+                success: true,
+              };
+            } catch (error) {
+              logger.error(`Failed to load module ${moduleId}:`, error);
+              return {
+                moduleId,
+                moduleUrl,
+                moduleVersion,
+                versionInfoFromFile: null,
+                success: false,
+                error,
+              };
+            }
+          },
+        );
 
         // Wait for all modules to be loaded
         const moduleLoadResults = await Promise.all(moduleLoadPromises);
@@ -531,6 +603,7 @@ export function useDynamicModules(
       }
     } catch (error) {
       logger.error("Failed to load modules:", error);
+      loadFailed = true;
     }
 
     app.config.globalProperties.$dynamicModules = {
@@ -538,6 +611,17 @@ export function useDynamicModules(
       ...window.VcShellDynamicModules,
     };
     app.provide(DynamicModulesKey, app.config.globalProperties.$dynamicModules);
+    performance.mark("vc:modules-done");
+
+    // Signal completion to the component tree
+    modulesReady.value = true;
+    if (loadFailed) {
+      modulesLoadError.value = true;
+    } else {
+      // Re-resolve the current route now that module routes/blades are registered
+      router.replace(router.currentRoute.value.fullPath);
+    }
+    performance.mark("vc:modules-installed");
   }
 
   return {

package/core/plugins/permissions/index.ts

@@ -1,4 +1,4 @@
-import { usePermissions } from "@core/composables";
+import { usePermissions } from "@core/composables/usePermissions";
 import { App } from "vue";
 
 export const permissions = {

package/core/plugins/signalR/index.ts

@@ -11,6 +11,10 @@ const logger = createLogger("signalR");
 const { addNotification } = useNotifications();
 const currentCreator = ref<string | undefined>();
 
+let mountComplete = false;
+let pendingStart = false;
+let _startFn: (() => void) | null = null;
+
 export const updateSignalRCreatorSymbol: InjectionKey<(creator: string | undefined) => void> =
   Symbol("updateSignalRCreator");
 
@@ -48,6 +52,10 @@ export const signalR = {
         .build();
 
     const start = () => {
+      if (!mountComplete) {
+        pendingStart = true;
+        return;
+      }
       connection
         .start()
         .then(() => {
@@ -60,6 +68,8 @@ export const signalR = {
         });
     };
 
+    _startFn = start;
+
     async function stop() {
       await connection.stop();
     }
@@ -91,6 +101,7 @@ export const signalR = {
           start();
         } else {
           reconnect = false;
+          pendingStart = false; // Cancel any pending deferred start
           await stop();
         }
       },
@@ -105,3 +116,11 @@ export const signalR = {
     });
   },
 };
+
+export function notifyMountComplete(): void {
+  mountComplete = true;
+  if (pendingStart && _startFn) {
+    pendingStart = false;
+    _startFn();
+  }
+}

package/core/services/app-bar-mobile-buttons-service.ts

@@ -9,6 +9,7 @@ export interface AppBarButtonContent {
   order?: number;
   onClose?: () => void;
   isVisible?: MaybeRef<boolean> | ComputedRef<boolean>;
+  badge?: MaybeRef<boolean> | ComputedRef<boolean>;
 }
 
 export interface IAppBarMobileButtonsService {