@almadar/ui 1.0.30 → 1.0.32

package/dist/providers/index.d.ts

@@ -1,7 +1,7 @@
 import React__default, { ReactNode } from 'react';
-import { b as ThemeDefinition } from '../ThemeContext-lI5bo85E.js';
+import { b as ThemeDefinition } from '../ThemeContext-D9xUORq5.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { E as EventBusContextType } from '../event-bus-types-8-cjyMxw.js';
+import { E as EventBusContextType } from '../event-bus-types-CjJduURa.js';
 import { U as UseOfflineExecutorResult, a as UseOfflineExecutorOptions } from '../offline-executor-CHr4uAhf.js';
 
 /**
@@ -247,10 +247,27 @@ interface OrbitalProviderProps {
     defaultTheme?: string;
     /** Default color mode */
     defaultMode?: 'light' | 'dark' | 'system';
+    /** Optional target element ref for scoped theme application */
+    targetRef?: React__default.RefObject<HTMLElement>;
+    /** Skip ThemeProvider (use when already inside a themed container like shadow DOM) */
+    skipTheme?: boolean;
     /** Enable debug logging for all providers */
     debug?: boolean;
     /** Initial fetched data */
     initialData?: Record<string, unknown[]>;
+    /**
+     * Enable Suspense mode. When true, UISlotRenderer wraps each slot in
+     * `<ErrorBoundary><Suspense>` with Skeleton fallbacks.
+     * Opt-in — existing isLoading prop pattern still works when false/absent.
+     */
+    suspense?: boolean;
+    /**
+     * Enable verification wiring for visual testing.
+     * When true, lifecycle events are recorded and exposed via
+     * `window.__orbitalVerification` for Playwright/automation.
+     * Default: true in development, false in production.
+     */
+    verification?: boolean;
 }
 /**
  * OrbitalProvider - Unified context provider for Orbital applications
@@ -299,11 +316,74 @@ interface OrbitalProviderProps {
  * }
  * ```
  */
-declare function OrbitalProvider({ children, themes, defaultTheme, defaultMode, debug, initialData, }: OrbitalProviderProps): React__default.ReactElement;
+declare function OrbitalProvider({ children, themes, defaultTheme, defaultMode, targetRef, skipTheme, debug, initialData, suspense, verification, }: OrbitalProviderProps): React__default.ReactElement;
 declare namespace OrbitalProvider {
     var displayName: string;
 }
 
+/**
+ * VerificationProvider
+ *
+ * Wires the verification registry to both compiled and runtime execution paths.
+ *
+ * **Compiled apps**: Intercepts event bus lifecycle events
+ *   (`{traitName}:DISPATCH`, `{traitName}:{event}:SUCCESS`, `{traitName}:{event}:ERROR`)
+ *   emitted by `useOrbitalBridge` and records transitions via `recordTransition()`.
+ *
+ * **Runtime apps**: Accepts an optional `StateMachineManager` and wires its
+ *   `TransitionObserver` to `recordTransition()`.
+ *
+ * **Both**: Calls `bindEventBus()` and `bindTraitStateGetter()` to populate
+ *   `window.__orbitalVerification` for Playwright/automation.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Observer interface compatible with `StateMachineManager.setObserver()`.
+ * Defined locally to avoid hard dependency on `@almadar/runtime`.
+ */
+interface TransitionObserver {
+    onTransition(trace: {
+        traitName: string;
+        from: string;
+        to: string;
+        event: string;
+        guardResult?: boolean;
+        effects: Array<{
+            type: string;
+            args: unknown[];
+            status: 'executed' | 'failed' | 'skipped';
+            error?: string;
+            durationMs?: number;
+        }>;
+    }): void;
+}
+/**
+ * Minimal interface for StateMachineManager — avoids importing the full runtime.
+ */
+interface StateMachineManagerLike {
+    setObserver(observer: TransitionObserver): void;
+    getState?(traitName: string): string | undefined;
+}
+interface VerificationProviderProps {
+    children: ReactNode;
+    /** Enable verification wiring (default: true in dev, false in prod) */
+    enabled?: boolean;
+    /** Optional runtime StateMachineManager for interpreted mode */
+    runtimeManager?: StateMachineManagerLike;
+    /** Optional trait state getter for compiled apps (maps traitName → currentState) */
+    traitStateGetter?: (traitName: string) => string | undefined;
+}
+/**
+ * VerificationProvider — wires the verification registry to the event bus
+ * and optional runtime manager. Renders children unchanged.
+ */
+declare function VerificationProvider({ children, enabled, runtimeManager, traitStateGetter, }: VerificationProviderProps): React__default.ReactElement;
+declare namespace VerificationProvider {
+    var displayName: string;
+}
+
 /**
  * OfflineModeProvider
  *
@@ -382,4 +462,4 @@ declare function useOfflineMode(): OfflineModeContextValue;
  */
 declare function useOptionalOfflineMode(): OfflineModeContextValue | null;
 
-export { type EntityRecord, EventBusContext, EventBusProvider, FetchedDataContext, type FetchedDataContextValue, FetchedDataProvider, type FetchedDataProviderProps, type FetchedDataState, type OfflineModeContextValue, OfflineModeProvider, type OfflineModeProviderProps, OrbitalProvider, type OrbitalProviderProps, SelectionContext, type SelectionContextType, SelectionProvider, ThemeDefinition, useFetchedData, useFetchedDataContext, useFetchedEntity, useOfflineMode, useOptionalOfflineMode, useSelection, useSelectionOptional };
+export { type EntityRecord, EventBusContext, EventBusProvider, FetchedDataContext, type FetchedDataContextValue, FetchedDataProvider, type FetchedDataProviderProps, type FetchedDataState, type OfflineModeContextValue, OfflineModeProvider, type OfflineModeProviderProps, OrbitalProvider, type OrbitalProviderProps, SelectionContext, type SelectionContextType, SelectionProvider, ThemeDefinition, VerificationProvider, type VerificationProviderProps, useFetchedData, useFetchedDataContext, useFetchedEntity, useOfflineMode, useOptionalOfflineMode, useSelection, useSelectionOptional };

package/dist/providers/index.js

@@ -1,10 +1,16 @@
-import { ThemeProvider } from '../chunk-4UFNDD6B.js';
-import { EventBusProvider, SelectionProvider, EntityDataProvider } from '../chunk-HY5EFCOK.js';
-export { EventBusContext, EventBusProvider, SelectionContext, SelectionProvider, useSelection, useSelectionOptional } from '../chunk-HY5EFCOK.js';
+import { SuspenseConfigProvider } from '../chunk-UCXZS2YJ.js';
+import { ThemeProvider } from '../chunk-BTXQJGFB.js';
+import { SelectionProvider, EntityDataProvider } from '../chunk-PE2H3NAW.js';
+export { SelectionContext, SelectionProvider, useSelection, useSelectionOptional } from '../chunk-PE2H3NAW.js';
+import '../chunk-7NEWMNNU.js';
+import { recordTransition, registerCheck, bindEventBus, bindTraitStateGetter } from '../chunk-45CTDYBT.js';
+import '../chunk-KKCVDUK7.js';
 import { useOfflineExecutor } from '../chunk-PL7MD6GF.js';
+import { useEventBus, EventBusProvider } from '../chunk-YXZM3WCF.js';
+export { EventBusContext, EventBusProvider } from '../chunk-YXZM3WCF.js';
 import '../chunk-PKBMQBKP.js';
-import { createContext, useState, useCallback, useMemo, useContext } from 'react';
-import { jsx } from 'react/jsx-runtime';
+import { createContext, useState, useCallback, useMemo, useContext, useRef, useEffect } from 'react';
+import { jsx, Fragment } from 'react/jsx-runtime';
 
 var FetchedDataContext = createContext(null);
 function FetchedDataProvider({
@@ -161,6 +167,144 @@ function useFetchedEntity(entityName) {
     error: context.error
   };
 }
+var DISPATCH_SUFFIX = ":DISPATCH";
+var SUCCESS_SUFFIX = ":SUCCESS";
+var ERROR_SUFFIX = ":ERROR";
+function parseLifecycleEvent(type) {
+  if (type.endsWith(DISPATCH_SUFFIX)) {
+    const traitName = type.slice(0, -DISPATCH_SUFFIX.length);
+    if (traitName) return { kind: "dispatch", traitName };
+  } else if (type.endsWith(SUCCESS_SUFFIX)) {
+    const rest = type.slice(0, -SUCCESS_SUFFIX.length);
+    const colonIdx = rest.indexOf(":");
+    if (colonIdx > 0) {
+      return {
+        kind: "success",
+        traitName: rest.slice(0, colonIdx),
+        event: rest.slice(colonIdx + 1)
+      };
+    }
+  } else if (type.endsWith(ERROR_SUFFIX)) {
+    const rest = type.slice(0, -ERROR_SUFFIX.length);
+    const colonIdx = rest.indexOf(":");
+    if (colonIdx > 0) {
+      return {
+        kind: "error",
+        traitName: rest.slice(0, colonIdx),
+        event: rest.slice(colonIdx + 1)
+      };
+    }
+  }
+  return null;
+}
+function VerificationProvider({
+  children,
+  enabled,
+  runtimeManager,
+  traitStateGetter
+}) {
+  const isEnabled = enabled ?? (typeof process !== "undefined" && process.env?.NODE_ENV !== "production");
+  const eventBus = useEventBus();
+  const pendingRef = useRef(/* @__PURE__ */ new Map());
+  useEffect(() => {
+    if (!isEnabled) return;
+    if (!eventBus.onAny) return;
+    const unsub = eventBus.onAny((evt) => {
+      const parsed = parseLifecycleEvent(evt.type);
+      if (!parsed) return;
+      const payload = evt.payload ?? {};
+      if (parsed.kind === "dispatch") {
+        const key = `${parsed.traitName}:${String(payload["event"] ?? "")}`;
+        pendingRef.current.set(key, {
+          traitName: parsed.traitName,
+          event: String(payload["event"] ?? ""),
+          from: payload["currentState"],
+          timestamp: evt.timestamp
+        });
+      } else if (parsed.kind === "success" && parsed.event) {
+        const key = `${parsed.traitName}:${parsed.event}`;
+        const pending = pendingRef.current.get(key);
+        pendingRef.current.delete(key);
+        const newState = payload["newState"] ?? payload["state"] ?? "unknown";
+        const effects = Array.isArray(payload["clientEffects"]) ? payload["clientEffects"].map((e) => ({
+          type: String(e["type"] ?? "unknown"),
+          args: Array.isArray(e["args"]) ? e["args"] : [],
+          status: "executed"
+        })) : [];
+        recordTransition({
+          traitName: parsed.traitName,
+          from: pending?.from ?? "unknown",
+          to: newState,
+          event: parsed.event,
+          effects,
+          timestamp: Date.now()
+        });
+      } else if (parsed.kind === "error" && parsed.event) {
+        const key = `${parsed.traitName}:${parsed.event}`;
+        const pending = pendingRef.current.get(key);
+        pendingRef.current.delete(key);
+        const errorMsg = payload["error"] ?? "Unknown error";
+        recordTransition({
+          traitName: parsed.traitName,
+          from: pending?.from ?? "unknown",
+          to: pending?.from ?? "unknown",
+          // state didn't change on error
+          event: parsed.event,
+          effects: [{
+            type: "server-call",
+            args: [],
+            status: "failed",
+            error: errorMsg
+          }],
+          timestamp: Date.now()
+        });
+      }
+    });
+    registerCheck(
+      "verification-provider",
+      "VerificationProvider active (compiled path)",
+      "pass"
+    );
+    return unsub;
+  }, [isEnabled, eventBus]);
+  useEffect(() => {
+    if (!isEnabled) return;
+    if (!runtimeManager) return;
+    runtimeManager.setObserver({
+      onTransition(trace) {
+        recordTransition({
+          traitName: trace.traitName,
+          from: trace.from,
+          to: trace.to,
+          event: trace.event,
+          guardResult: trace.guardResult,
+          effects: trace.effects,
+          timestamp: Date.now()
+        });
+      }
+    });
+    registerCheck(
+      "verification-provider",
+      "VerificationProvider active (runtime path)",
+      "pass"
+    );
+  }, [isEnabled, runtimeManager]);
+  useEffect(() => {
+    if (!isEnabled) return;
+    bindEventBus(eventBus);
+  }, [isEnabled, eventBus]);
+  useEffect(() => {
+    if (!isEnabled) return;
+    if (traitStateGetter) {
+      bindTraitStateGetter(traitStateGetter);
+    } else if (runtimeManager?.getState) {
+      const mgr = runtimeManager;
+      bindTraitStateGetter((traitName) => mgr.getState(traitName));
+    }
+  }, [isEnabled, traitStateGetter, runtimeManager]);
+  return /* @__PURE__ */ jsx(Fragment, { children });
+}
+VerificationProvider.displayName = "VerificationProvider";
 function FetchedDataBridge({ children }) {
   const fetchedData = useFetchedData();
   const adapter = useMemo(() => ({
@@ -176,16 +320,29 @@ function OrbitalProvider({
   themes,
   defaultTheme = "wireframe",
   defaultMode = "system",
+  targetRef,
+  skipTheme = false,
   debug = false,
-  initialData
+  initialData,
+  suspense = false,
+  verification
 }) {
+  const suspenseConfig = useMemo(
+    () => ({ enabled: suspense }),
+    [suspense]
+  );
+  const inner = /* @__PURE__ */ jsx(FetchedDataProvider, { initialData, children: /* @__PURE__ */ jsx(FetchedDataBridge, { children: /* @__PURE__ */ jsx(EventBusProvider, { debug, children: /* @__PURE__ */ jsx(VerificationProvider, { enabled: verification, children: /* @__PURE__ */ jsx(SelectionProvider, { debug, children: /* @__PURE__ */ jsx(SuspenseConfigProvider, { config: suspenseConfig, children }) }) }) }) }) });
+  if (skipTheme) {
+    return inner;
+  }
   return /* @__PURE__ */ jsx(
     ThemeProvider,
     {
       themes,
       defaultTheme,
       defaultMode,
-      children: /* @__PURE__ */ jsx(FetchedDataProvider, { initialData, children: /* @__PURE__ */ jsx(FetchedDataBridge, { children: /* @__PURE__ */ jsx(EventBusProvider, { debug, children: /* @__PURE__ */ jsx(SelectionProvider, { debug, children }) }) }) })
+      targetRef,
+      children: inner
     }
   );
 }
@@ -220,4 +377,4 @@ function useOptionalOfflineMode() {
   return useContext(OfflineModeContext);
 }
 
-export { FetchedDataContext, FetchedDataProvider, OfflineModeProvider, OrbitalProvider, useFetchedData, useFetchedDataContext, useFetchedEntity, useOfflineMode, useOptionalOfflineMode };
+export { FetchedDataContext, FetchedDataProvider, OfflineModeProvider, OrbitalProvider, VerificationProvider, useFetchedData, useFetchedDataContext, useFetchedEntity, useOfflineMode, useOptionalOfflineMode };

package/dist/{useUISlots-mnggE9X9.d.ts → useUISlots-D0mttBSP.d.ts}

@@ -1,23 +1,3 @@
-/**
- * useUISlots Hook
- *
- * Core hook for managing UI slot rendering in the trait-driven architecture.
- * Traits use render_ui effects to dynamically render content into slots.
- *
- * Slots:
- * - main: Primary content area
- * - sidebar: Left/right sidebar
- * - modal: Modal overlay
- * - drawer: Slide-in drawer
- * - overlay: Full-screen overlay
- * - center: Centered popup
- * - toast: Toast notifications
- * - hud-top: Game HUD top bar
- * - hud-bottom: Game HUD bottom bar
- * - floating: Draggable floating panel
- *
- * @packageDocumentation
- */
 /**
  * Valid UI slot names
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",
@@ -39,6 +39,18 @@
       "import": "./dist/lib/index.js",
       "types": "./dist/lib/index.d.ts"
     },
+    "./components/organisms/game/three": {
+      "import": "./dist/components/organisms/game/three/index.js",
+      "types": "./dist/components/organisms/game/three/index.d.ts"
+    },
+    "./components/organisms/game/TraitStateViewer": {
+      "import": "./components/organisms/game/TraitStateViewer.tsx",
+      "types": "./components/organisms/game/TraitStateViewer.tsx"
+    },
+    "./components/organisms/game/TraitSlot": {
+      "import": "./components/organisms/game/TraitSlot.tsx",
+      "types": "./components/organisms/game/TraitSlot.tsx"
+    },
     "./templates": {
       "import": "./templates/index.ts",
       "types": "./templates/index.ts"
@@ -57,13 +69,18 @@
     "clsx": "^2.1.0",
     "tailwind-merge": "^2.2.0",
     "lucide-react": "^0.344.0",
-    "@almadar/core": "1.0.17",
-    "@almadar/evaluator": "1.0.15",
-    "@almadar/patterns": "1.1.1"
+    "react-markdown": "^9.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-math": "^6.0.0",
+    "rehype-katex": "^7.0.0",
+    "react-syntax-highlighter": "^15.6.1",
+    "@almadar/core": "1.0.18",
+    "@almadar/patterns": "1.1.1",
+    "@almadar/evaluator": "1.0.16"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
     "react-router-dom": "^7.0.0",
     "@tanstack/react-query": "^5.0.0",
     "three": "^0.160.0",
@@ -71,12 +88,12 @@
     "@react-three/drei": "^9.92.0"
   },
   "devDependencies": {
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "react-router-dom": "^7.13.0",
     "@tanstack/react-query": "^5.0.0",
-    "@types/react": "^18.3.0",
-    "@types/react-dom": "^18.3.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "@types/three": "^0.160.0",
     "@storybook/addon-links": "^10.2.6",
     "@storybook/addon-themes": "^10.2.6",
@@ -84,6 +101,8 @@
     "@storybook/react-vite": "^10.2.6",
     "storybook": "^10.2.6",
     "@vitejs/plugin-react": "^4.2.0",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "react-compiler-runtime": "^1.0.0",
     "autoprefixer": "^10.4.0",
     "postcss": "^8.4.35",
     "tailwindcss": "^3.4.0",
@@ -96,7 +115,9 @@
     "@testing-library/jest-dom": "^6.4.0",
     "@vitest/ui": "^1.4.0",
     "jsdom": "^24.0.0",
-    "@storybook/addon-docs": "^10.2.6"
+    "@storybook/addon-docs": "^10.2.6",
+    "@types/react-syntax-highlighter": "^15.5.0",
+    "katex": "^0.16.0"
   },
   "repository": {
     "type": "git",