@raclettejs/core 0.1.40 → 0.1.42

package/services/frontend/src/orchestrator/composables/useWidgetLifecycle.ts

@@ -2,21 +2,29 @@ import { ref, type Ref } from "vue"
 import { isDevelopmentMode } from "@racletteCore/helpers/devMode"
 import log from "@racletteCore/lib/logger"
 import { scheduleAfterPaint } from "@racletteCore/lib/scheduleTask"
+import { hasWidgetSlotContent } from "@racletteOrchestrator/helpers/widgetSlotHelper"
 
 export type OnAllWidgetsReady = (callback: () => void) => void
 
-interface WidgetLifecycleHooks {
+export interface WidgetLifecycleHooks {
   onAllWidgetsReady: OnAllWidgetsReady
-  onWidgetRendered: (element: HTMLElement) => void
+  onWidgetContainerMounted: (element: HTMLElement) => void
   onWidgetUnmounted: () => void
 }
 
-interface WidgetLifecycleManager {
+export interface WidgetLifecycleManager {
   createLifecycleHooks: (widgetId: string) => WidgetLifecycleHooks
   allWidgetsReady: Ref<boolean>
   reset: () => void
 }
 
+/**
+ * Tracks widget slot readiness for page navigation, modal overlays, and other
+ * `WidgetsLayoutLoader` instances with `trackReadiness`.
+ *
+ * Observes each widget slot container in `WidgetsLayoutLoader` and waits until
+ * plugin content appears in the DOM. Plugin developers do not interact with this.
+ */
 export function createWidgetLifecycleManager(
   totalWidgets: number,
 ): WidgetLifecycleManager {
@@ -24,6 +32,7 @@ export function createWidgetLifecycleManager(
   const allWidgetsReady = ref(false)
   const readyCallbacks = new Set<() => void>()
   const observers = new Map<string, MutationObserver>()
+  const observedContainers = new Map<string, HTMLElement>()
 
   const DEV_MODE = isDevelopmentMode()
 
@@ -34,91 +43,75 @@ export function createWidgetLifecycleManager(
   }
 
   const checkAllReady = () => {
-    if (renderedWidgets.value.size === totalWidgets && !allWidgetsReady.value) {
-      allWidgetsReady.value = true
-
-      if (DEV_MODE) {
-        log.widgets(
-          "useWidgetLifecycle",
-          `✅ All ${totalWidgets} widgets are fully rendered`,
-        )
-      }
-
-      readyCallbacks.forEach((callback) => callback())
-      readyCallbacks.clear()
+    if (renderedWidgets.value.size !== totalWidgets || allWidgetsReady.value) {
+      return
     }
-  }
 
-  const hasVisibleContent = (element: HTMLElement): boolean => {
-    if (element.childNodes.length === 0) {
-      return false
-    }
+    allWidgetsReady.value = true
 
-    const text = element.textContent?.trim()
-    if (text?.length) {
-      return true
+    if (DEV_MODE) {
+      log.widgets(
+        "useWidgetLifecycle",
+        `All ${totalWidgets} widgets are fully rendered`,
+      )
     }
 
-    // DOM-only checks — avoid getBoundingClientRect / offset* (forced reflow).
-    return (
-      element.children.length > 0 ||
-      element.querySelector(
-        "table, img, canvas, svg, video, iframe, input, button, select, textarea, [role='row']",
-      ) !== null
-    )
+    readyCallbacks.forEach((callback) => callback())
+    readyCallbacks.clear()
+  }
+
+  const disconnectObserver = (id: string) => {
+    observers.get(id)?.disconnect()
+    observers.delete(id)
+    observedContainers.delete(id)
   }
 
-  const scheduleContentCheck = (
-    element: HTMLElement,
+  const scheduleContainerCheck = (
+    container: HTMLElement,
     onReady: () => void,
   ): (() => void) => {
     let scheduled = false
 
     const runCheck = () => {
       scheduled = false
-      if (hasVisibleContent(element)) {
+      if (hasWidgetSlotContent(container)) {
         onReady()
       }
     }
 
-    const scheduleCheck = () => {
+    return () => {
       if (scheduled) {
         return
       }
       scheduled = true
       scheduleAfterPaint(runCheck)
     }
-
-    return scheduleCheck
   }
 
-  const registerWidgetAsRendered = (id: string) => {
-    if (!renderedWidgets.value.has(id)) {
-      renderedWidgets.value.add(id)
+  const registerWidgetAsReady = (id: string) => {
+    if (renderedWidgets.value.has(id)) {
+      return
+    }
 
-      if (DEV_MODE) {
-        log.widgets(
-          "useWidgetLifecycle",
-          `📦 Widget rendered: ${id} (${renderedWidgets.value.size}/${totalWidgets})`,
-        )
-      }
+    renderedWidgets.value.add(id)
+    disconnectObserver(id)
 
-      checkAllReady()
+    if (DEV_MODE) {
+      log.widgets(
+        "useWidgetLifecycle",
+        `Widget ready: ${id} (${renderedWidgets.value.size}/${totalWidgets})`,
+      )
     }
+
+    checkAllReady()
   }
 
   const unregisterWidget = (id: string) => {
     if (DEV_MODE) {
-      log.widgets("useWidgetLifecycle", `📤 Widget unregistered: ${id}`)
-    }
-
-    // Clean up observer
-    const observer = observers.get(id)
-    if (observer) {
-      observer.disconnect()
-      observers.delete(id)
+      log.widgets("useWidgetLifecycle", `Widget unregistered: ${id}`)
     }
 
+    disconnectObserver(id)
     renderedWidgets.value.delete(id)
 
     if (renderedWidgets.value.size < totalWidgets) {
@@ -126,33 +119,30 @@ export function createWidgetLifecycleManager(
     }
   }
 
-  const observeWidgetRendering = (id: string, element: HTMLElement) => {
-    let observer: MutationObserver | null = null
+  const observeWidgetContainer = (id: string, container: HTMLElement) => {
+    if (renderedWidgets.value.has(id)) {
+      return
+    }
 
-    const markReady = () => {
-      observer?.disconnect()
-      observer = null
-      observers.delete(id)
-      registerWidgetAsRendered(id)
+    if (observedContainers.get(id) === container) {
+      return
     }
 
-    const scheduleCheck = scheduleContentCheck(element, markReady)
+    disconnectObserver(id)
+    observedContainers.set(id, container)
 
-    observer = new MutationObserver(scheduleCheck)
-    observer.observe(element, {
+    const scheduleCheck = scheduleContainerCheck(container, () =>
+      registerWidgetAsReady(id),
+    )
+
+    const observer = new MutationObserver(scheduleCheck)
+    observer.observe(container, {
       childList: true,
       subtree: true,
       characterData: true,
     })
     observers.set(id, observer)
     scheduleCheck()
-
-    if (DEV_MODE) {
-      log.widgets(
-        "useWidgetLifecycle",
-        `👀 Observing widget for content: ${id}`,
-      )
-    }
   }
 
   const createLifecycleHooks = (widgetId: string): WidgetLifecycleHooks => ({
@@ -163,24 +153,23 @@ export function createWidgetLifecycleManager(
         readyCallbacks.add(callback)
       }
     },
-    onWidgetRendered: (element: HTMLElement) => {
-      observeWidgetRendering(widgetId, element)
+    onWidgetContainerMounted: (element: HTMLElement) => {
+      observeWidgetContainer(widgetId, element)
     },
     onWidgetUnmounted: () => unregisterWidget(widgetId),
   })
 
   const reset = () => {
-    // Disconnect all observers
     observers.forEach((observer) => observer.disconnect())
     observers.clear()
+    observedContainers.clear()
     renderedWidgets.value.clear()
     allWidgetsReady.value = false
     readyCallbacks.clear()
-
     markReadyIfNoWidgets()
 
     if (DEV_MODE) {
-      log.widgets("useWidgetLifecycle", "🔄 Widget lifecycle manager reset")
+      log.widgets("useWidgetLifecycle", "Widget lifecycle manager reset")
     }
   }
 

package/services/frontend/src/orchestrator/composables/useWidgets/helperFunctions.ts

@@ -6,7 +6,10 @@ import { forEachObjIndexed } from "ramda"
 import type { ConfigurableParameters, WidgetConf } from "@racletteOrchestrator"
 import { generatePluginKey } from "@shared/helper/pluginHelper"
 import type { PluginMetadata } from "@core"
-import type { RegisteredWidgetDeclaration, WidgetDeclaration } from "@racletteOrchestrator"
+import type {
+  RegisteredWidgetDeclaration,
+  WidgetDeclaration,
+} from "@racletteOrchestrator"
 import { normalizeWidgetVisuals } from "@racletteOrchestrator/helpers"
 
 // Plugin metadata files (unchanged)
@@ -134,9 +137,8 @@ export const getWidgetDeclacations = () => {
         }
 
         // Extract details and config (handle both default export and named exports)
-        const details = (setupModule.details || setupModule.default?.details) as
-          | WidgetDeclaration
-          | undefined
+        const details = (setupModule.details ||
+          setupModule.default?.details) as WidgetDeclaration | undefined
         const config = setupModule.config || setupModule.default?.config
 
         if (!details) {
@@ -150,6 +152,7 @@ export const getWidgetDeclacations = () => {
         const registeredWidget: RegisteredWidgetDeclaration = {
           ...details,
           ...normalizedVisuals,
+          description: details.description?.trim() ?? "",
           pluginKey,
           author: pluginMetadata.author,
           name: widgetName,

package/services/frontend/src/orchestrator/constants/index.ts

@@ -0,0 +1,2 @@
+export * from "./widgetSlotType"
+export * from "./widgetSlot"

package/services/frontend/src/orchestrator/constants/widgetSlot.ts

@@ -0,0 +1,7 @@
+/**
+ * Internal marker on {@link LoadingWidgetState} while a widget JS chunk loads.
+ * Not used in plugin widgets — only the orchestrator loading placeholder.
+ */
+export const WIDGET_CHUNK_LOADING_ATTR = "data-raclette-widget-chunk-loading"
+
+export const WIDGET_CHUNK_LOADING_SELECTOR = `[${WIDGET_CHUNK_LOADING_ATTR}]`

package/services/frontend/src/orchestrator/exports.ts

@@ -4,3 +4,4 @@ export * from "@racletteOrchestrator/helpers"
 export * from "@racletteOrchestrator/setup/i18n"
 export type * from "./types"
 export * from "./components"
+export * from "./constants"

package/services/frontend/src/orchestrator/helpers/staticWidgetRegistry.ts

@@ -1,8 +1,8 @@
 import type { Component } from "vue"
-import { h } from "vue"
 import type { WidgetDeclaration } from "@racletteOrchestrator"
 import { registeredPlugins } from "@racletteCore/setup/plugin-system"
 import logger from "@racletteCore/lib/logger"
+import { createEnhancedError } from "@racletteOrchestrator/helpers/widgetUtils"
 
 export type WidgetInfo = {
   widgetName: string
@@ -177,23 +177,12 @@ const initializeWidgetDiscovery = () => {
 // =====================================================
 
 const loadWidget = async (widgetInfo: WidgetInfo) => {
-  try {
-    const componentModule = await widgetInfo.componentLoader()
-    const component = componentModule.default || componentModule
-
-    const setup = await loadWidgetSetup(widgetInfo)
+  const componentModule = await widgetInfo.componentLoader()
+  const component = componentModule.default || componentModule
 
-    return { component, ...setup }
-  } catch (error) {
-    logger.widgets("Failed to load widget", {
-      widgetName: widgetInfo.widgetName,
-      error: error instanceof Error ? error.message : String(error),
-    })
+  const setup = await loadWidgetSetup(widgetInfo)
 
-    return {
-      component: createErrorComponent(widgetInfo.widgetName),
-    }
-  }
+  return { component, ...setup }
 }
 
 const loadWidgetSetup = async (widgetInfo: WidgetInfo) => {
@@ -216,16 +205,6 @@ const loadWidgetSetup = async (widgetInfo: WidgetInfo) => {
   }
 }
 
-const createErrorComponent = (widgetName: string): Component => ({
-  name: `${widgetName}Error`,
-  setup: () => () =>
-    h(
-      "div",
-      { class: "p-4 text-red-500 border border-red-300 rounded" },
-      `Failed to load widget: ${widgetName}`,
-    ),
-})
-
 // =====================================================
 // PATH RESOLUTION HELPERS
 // =====================================================
@@ -318,7 +297,10 @@ export const loadWidgetComponent = async (
     }
     return component
   } catch (error) {
-    const enhancedError = createEnhancedLoadError(error, pluginKey, widgetName)
+    const enhancedError = createEnhancedError(error, {
+      pluginKey,
+      name: widgetName,
+    })
     logger.widgets("Widget component load failed", {
       pluginKey,
       widgetName,
@@ -328,22 +310,5 @@ export const loadWidgetComponent = async (
   }
 }
 
-const createEnhancedLoadError = (
-  error: unknown,
-  pluginKey: string,
-  widgetName: string,
-) => {
-  if (error instanceof Error) {
-    const enhancedError = new Error(
-      `Failed to load widget component ${pluginKey}/${widgetName}: ${error.message}`,
-    )
-    enhancedError.stack = error.stack
-    return enhancedError
-  }
-  return new Error(
-    `Failed to load widget component ${pluginKey}/${widgetName}: ${String(error)}`,
-  )
-}
-
 // Initialize on module load
 initializeWidgetDiscovery()

package/services/frontend/src/orchestrator/helpers/widgetLayoutHelper.ts

@@ -0,0 +1,37 @@
+import type { Composition } from "@shared/types/core/Composition.types"
+import { isDefined } from "@vueuse/core"
+import { chain, filter, join, length, map, pipe, pickBy } from "ramda"
+
+type WidgetsLayout = Composition["widgetsLayout"]
+
+/** Count slots that reference a widget instance. */
+export const countWidgetsInLayout = (layout: WidgetsLayout): number =>
+  pipe(
+    chain((column) => column),
+    filter((slot) => Boolean(slot.widget)),
+    length,
+  )(layout)
+
+/**
+ * Stable signature of widget UUIDs in layout order.
+ * Used to detect structural layout changes without deep-reacting to mutations.
+ */
+export const getWidgetsLayoutSignature = (layout: WidgetsLayout): string =>
+  pipe(
+    chain((column) => map((slot) => slot.widget?.uuid ?? "", column)),
+    join("|"),
+  )(layout)
+
+/** Drop undefined route param values before passing them to widgets. */
+export const cleanRouteParams = (
+  params: Record<string, string | undefined> | undefined,
+): Record<string, string> => {
+  if (!params) {
+    return {}
+  }
+
+  return pickBy(
+    (value) => isDefined(value) && value !== "undefined",
+    params,
+  ) as Record<string, string>
+}

package/services/frontend/src/orchestrator/helpers/widgetLoader.ts

@@ -38,7 +38,6 @@ export const widgetLoader = (
     loader: async () => {
       try {
         validateWidget(widget)
-
         const originalComponent = await loadWidgetComponent(
           widget.pluginKey!,
           widget.name!,

package/services/frontend/src/orchestrator/helpers/widgetSlotHelper.ts

@@ -0,0 +1,20 @@
+import { WIDGET_CHUNK_LOADING_SELECTOR } from "@racletteOrchestrator/constants/widgetSlot"
+
+/**
+ * True when a widget slot container has rendered plugin content.
+ *
+ * Ignores the orchestrator's async chunk loader (`LoadingWidgetState`).
+ * Widget-owned loading UI (skeletons, spinners) inside the slot counts as content.
+ */
+export const hasWidgetSlotContent = (container: HTMLElement): boolean => {
+  if (container.querySelector(WIDGET_CHUNK_LOADING_SELECTOR)) {
+    return false
+  }
+
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT)
+  if (walker.nextNode()) {
+    return true
+  }
+
+  return Boolean(container.textContent?.trim())
+}

package/services/frontend/src/orchestrator/helpers/widgetVisuals.ts

@@ -1,9 +1,9 @@
-export type WidgetVisualInput = {
-  title?: string
-  color?: string
-  icon?: string
-  images?: string[]
-}
+import type { WidgetDeclaration } from "@racletteOrchestrator/types/Widgets"
+
+export type WidgetVisualInput = Pick<
+  WidgetDeclaration,
+  "title" | "color" | "icon" | "images"
+>
 
 export type WidgetVisuals = {
   color: string
@@ -27,10 +27,7 @@ export const generateColorFromName = (name: string): string => {
 }
 
 export const getWidgetInitials = (name: string): string => {
-  const parts = name
-    .trim()
-    .split(/\s+/)
-    .filter(Boolean)
+  const parts = name.trim().split(/\s+/).filter(Boolean)
 
   if (parts.length === 0) {
     return "W"
@@ -59,8 +56,10 @@ export const normalizeWidgetVisuals = (
       : ""
 
   const normalizedImages = Array.isArray(details.images)
-    // Ignore invalid/empty entries to keep consumers simple.
-    ? details.images.filter((image) => typeof image === "string" && image.trim())
+    ? // Ignore invalid/empty entries to keep consumers simple.
+      details.images.filter(
+        (image) => typeof image === "string" && image.trim(),
+      )
     : []
 
   return {

package/services/frontend/src/orchestrator/helpers/wrapWidgetWithLifecycle.ts

@@ -0,0 +1,32 @@
+import type { WidgetBase } from "@racletteCore/store/types"
+import type {
+  OnAllWidgetsReady,
+  WidgetLifecycleManager,
+} from "@racletteOrchestrator/composables/useWidgetLifecycle"
+import { h, type Component } from "vue"
+
+const noopAllWidgetsReady: OnAllWidgetsReady = () => {}
+
+/** Injects `onAllWidgetsReady` into loaded widget components. */
+export const wrapWidgetWithLifecycle = (
+  widget: WidgetBase,
+  originalComponent: Component,
+  getLifecycleManager: () => WidgetLifecycleManager | null,
+): Component => ({
+  name: `${originalComponent.name || "Widget"}Wrapper`,
+  setup(props, context) {
+    const onAllWidgetsReady =
+      getLifecycleManager()?.createLifecycleHooks(widget.uuid)
+        .onAllWidgetsReady ?? noopAllWidgetsReady
+
+    return () =>
+      h(
+        originalComponent,
+        {
+          ...props,
+          onAllWidgetsReady,
+        },
+        context.slots,
+      )
+  },
+})

package/services/frontend/src/orchestrator/router/routerHooks/afterEach.ts

@@ -1,31 +1,6 @@
-import { loadingHold } from "@racletteCore/store/state"
-import { $store } from "@racletteCore"
-import { scheduleAfterPaint } from "@racletteCore/lib/scheduleTask"
 import type { RouteLocationNormalized } from "vue-router"
-import { handleRouteChange } from "../routeStore"
 
-/**
- * afterEachHook
- * @param { object } store, mini-rx store instance
- *
- * removeLoading Animation
- */
-export default (to: RouteLocationNormalized, from: RouteLocationNormalized) => {
-  scheduleAfterPaint(() => {
-    handleRouteChange(to, from)
-  })
-
-  const loading = $store.getState(["ui", "loading"])
-  if (loading) {
-    setTimeout(() => {
-      scheduleAfterPaint(() => {
-        if ($store.getState(["ui", "loading"])) {
-          $store.dispatch({
-            type: "ui/update",
-            payload: { loading: false },
-          })
-        }
-      })
-    }, loadingHold)
-  }
-}
+export default (
+  _to: RouteLocationNormalized,
+  _from: RouteLocationNormalized,
+) => {}

package/services/frontend/src/orchestrator/router/routerHooks/beforeEach.ts

@@ -1,6 +1,6 @@
 import { $store } from "@racletteCore"
 import type { RouteLocationNormalized } from "vue-router"
-import { checkForDefaultSlotChange } from "../routeStore"
+import { checkForDefaultSlotChange, handleRouteChange } from "../routeStore"
 
 export default async (
   to: RouteLocationNormalized,
@@ -16,6 +16,9 @@ export default async (
     }
   }
 
+  // Apply target composition slots before the loading gate remounts page widgets.
+  handleRouteChange(to, from)
+
   // show loading animation only, if the default slot's value changes
   if (checkForDefaultSlotChange(to, from)) {
     $store.dispatch({

package/services/frontend/src/orchestrator/types/Widgets.ts

@@ -38,22 +38,28 @@ export type ConfigurableParameters = Record<
   EditorSettings & { defaultValue: any }
 >
 
+/** Catalog entry after registration (workbench picker, APIs). All fields are required. */
 export type RegisteredWidgetDeclaration = {
   pluginKey: string
   author: string
+  name: string
   title: string
+  description: string
   color: string
   icon: string
   images: string[]
-  description: string
   configurableParameters?: ConfigurableParameters
-  name: string
 }
 
-export type WidgetDeclaration = Omit<
-  RegisteredWidgetDeclaration,
-  "pluginKey" | "author" | "name" // name will be extracted via filename, cannot be overwritten
-> & {
+/**
+ * Plugin-authored `details` in `frontend/widgets/<WidgetFolder>/setup.ts`.
+ *
+ * `pluginKey`, `author`, and `name` are added by the framework (from plugin metadata
+ * and the `*Widget.vue` filename). Optional visual fields may be omitted or left
+ * empty — `normalizeWidgetVisuals` fills defaults before producing a
+ * `RegisteredWidgetDeclaration`.
+ */
+export type WidgetDeclaration = {
   title: string
   description?: string
   color?: string

package/src/types.ts

@@ -21,9 +21,15 @@ export type RacletteConfig = {
       port: number
       name?: string
       volume?: string
+      /** Default Valkey DB index for all roles when role-specific value is unset (default: 0). */
       db?: number
+      /** Per-stack Valkey DB overrides (app / workbench / core). */
+      dbs?: {
+        app?: number
+        workbench?: number
+        core?: number
+      }
       volumes?: VolumeDefinition[] // Add custom volumes property
-    
     }
     workbench?: {
       enabled: boolean