@almadar/ui 4.10.7 → 4.11.0

package/dist/avl/index.cjs

@@ -52200,6 +52200,38 @@ init_EntitySchemaContext();
 init_useEventBus();
 init_logger();
 var xOrbitalLog2 = createLogger("almadar:runtime:cross-orbital");
+function createHttpTransport(serverUrl) {
+  return {
+    register: async (schema) => {
+      try {
+        const res = await fetch(`${serverUrl}/register`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ schema })
+        });
+        const result = await res.json();
+        return !!result.success;
+      } catch (err) {
+        console.error("[ServerBridge] Registration failed:", err);
+        return false;
+      }
+    },
+    unregister: async () => {
+      try {
+        await fetch(`${serverUrl}/unregister`, { method: "DELETE" });
+      } catch {
+      }
+    },
+    sendEvent: async (orbitalName, event, payload) => {
+      const res = await fetch(`${serverUrl}/${orbitalName}/events`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ event, payload })
+      });
+      return res.json();
+    }
+  };
+}
 var ServerBridgeContext = React128.createContext(null);
 function useServerBridge() {
   const ctx = React128.useContext(ServerBridgeContext);
@@ -52212,40 +52244,34 @@ function useServerBridge() {
 function ServerBridgeProvider({
   schema,
   serverUrl,
+  transport: customTransport,
   children
 }) {
+  if (!serverUrl && !customTransport) {
+    throw new Error("ServerBridgeProvider requires either serverUrl or transport");
+  }
+  if (serverUrl && customTransport) {
+    throw new Error("ServerBridgeProvider accepts serverUrl OR transport, not both");
+  }
   const eventBus = useEventBus();
   const [connected, setConnected] = React128.useState(false);
-  const registerSchema = React128.useCallback(async () => {
-    try {
-      const res = await fetch(`${serverUrl}/register`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ schema })
-      });
-      const result = await res.json();
-      return !!result.success;
-    } catch (err) {
-      console.error("[ServerBridge] Registration failed:", err);
-      return false;
-    }
-  }, [schema, serverUrl]);
-  const unregisterSchema = React128.useCallback(async () => {
-    try {
-      await fetch(`${serverUrl}/unregister`, { method: "DELETE" });
-    } catch {
-    }
-  }, [serverUrl]);
+  const transport = React128.useMemo(
+    () => customTransport ?? createHttpTransport(serverUrl),
+    [serverUrl, customTransport]
+  );
+  const registerSchema = React128.useCallback(
+    async () => transport.register(schema),
+    [schema, transport]
+  );
+  const unregisterSchema = React128.useCallback(
+    async () => transport.unregister(),
+    [transport]
+  );
   const sendEvent = React128.useCallback(async (orbitalName, event, payload) => {
     const emptyMeta = { success: false, clientEffects: 0, dataEntities: {}, emittedEvents: [] };
     if (!connected) return { effects: [], meta: emptyMeta };
     try {
-      const res = await fetch(`${serverUrl}/${orbitalName}/events`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ event, payload })
-      });
-      const result = await res.json();
+      const result = await transport.sendEvent(orbitalName, event, payload);
       const effects = [];
       const responseData = result.data || {};
       const dataEntities = {};
@@ -52303,7 +52329,7 @@ function ServerBridgeProvider({
       console.error("[ServerBridge] Event send failed:", err);
       return { effects: [], meta: { ...emptyMeta, error: err instanceof Error ? err.message : String(err) } };
     }
-  }, [connected, serverUrl, eventBus]);
+  }, [connected, transport, eventBus]);
   React128.useEffect(() => {
     if (!schema) return;
     let cancelled = false;
@@ -52579,7 +52605,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate]);
   return null;
 }
-function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
+function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
   const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = React128.useMemo(() => {
     if (pageName && traits2.length > 0) return traits2;
@@ -52693,7 +52719,7 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
           TraitInitializer,
           {
             traits: allPageTraits,
-            orbitalNames: serverUrl ? pageOrbitalNames : void 0,
+            orbitalNames: serverUrl || transport ? pageOrbitalNames : void 0,
             traitConfigsByName,
             orbitalsByTrait,
             onNavigate,
@@ -52706,8 +52732,8 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
       ]
     }
   ) }) });
-  if (serverUrl) {
-    return /* @__PURE__ */ jsxRuntime.jsx(ServerBridgeProvider, { schema, serverUrl, children: inner });
+  if (serverUrl || transport) {
+    return /* @__PURE__ */ jsxRuntime.jsx(ServerBridgeProvider, { schema, serverUrl, transport, children: inner });
   }
   return inner;
 }
@@ -52718,8 +52744,12 @@ function OrbPreview({
   height = "400px",
   className,
   serverUrl,
+  transport,
   initialPagePath
 }) {
+  if (serverUrl && transport) {
+    throw new Error("OrbPreview accepts serverUrl OR transport, not both");
+  }
   const [localFallback, setLocalFallback] = React128.useState(false);
   const eventBus = useEventBus();
   const handleLocalFallback = React128.useCallback(() => {
@@ -52741,21 +52771,21 @@ function OrbPreview({
     } else {
       parsed = schema;
     }
-    if (autoMock && !serverUrl) {
+    if (autoMock && !serverUrl && !transport) {
       const prepared = prepareSchemaForPreview(parsed);
       return { ok: true, schema: prepared.schema, mockData: prepared.mockData };
     }
     return { ok: true, schema: parsed, mockData: mockData ?? {} };
-  }, [schema, autoMock, serverUrl, mockData]);
+  }, [schema, autoMock, serverUrl, transport, mockData]);
   const parsedSchema = parseResult.ok ? parseResult.schema : null;
   const effectiveMockData = parseResult.ok ? parseResult.mockData : {};
   const persistence = React128.useMemo(() => {
-    if (!parsedSchema || serverUrl) return void 0;
+    if (!parsedSchema || serverUrl || transport) return void 0;
     if (!autoMock) return void 0;
     const adapter = new runtime.InMemoryPersistence();
     adapter.seed(effectiveMockData);
     return adapter;
-  }, [parsedSchema, serverUrl, autoMock, effectiveMockData]);
+  }, [parsedSchema, serverUrl, transport, autoMock, effectiveMockData]);
   const pages = React128.useMemo(() => {
     if (!parsedSchema) return [];
     try {
@@ -52817,6 +52847,7 @@ function OrbPreview({
           {
             schema: parsedSchema,
             serverUrl,
+            transport,
             mockData: effectiveMockData,
             pageName: currentPage,
             onNavigate: handleNavigate,

package/dist/avl/index.js

@@ -52154,6 +52154,38 @@ init_EntitySchemaContext();
 init_useEventBus();
 init_logger();
 var xOrbitalLog2 = createLogger("almadar:runtime:cross-orbital");
+function createHttpTransport(serverUrl) {
+  return {
+    register: async (schema) => {
+      try {
+        const res = await fetch(`${serverUrl}/register`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ schema })
+        });
+        const result = await res.json();
+        return !!result.success;
+      } catch (err) {
+        console.error("[ServerBridge] Registration failed:", err);
+        return false;
+      }
+    },
+    unregister: async () => {
+      try {
+        await fetch(`${serverUrl}/unregister`, { method: "DELETE" });
+      } catch {
+      }
+    },
+    sendEvent: async (orbitalName, event, payload) => {
+      const res = await fetch(`${serverUrl}/${orbitalName}/events`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ event, payload })
+      });
+      return res.json();
+    }
+  };
+}
 var ServerBridgeContext = createContext(null);
 function useServerBridge() {
   const ctx = useContext(ServerBridgeContext);
@@ -52166,40 +52198,34 @@ function useServerBridge() {
 function ServerBridgeProvider({
   schema,
   serverUrl,
+  transport: customTransport,
   children
 }) {
+  if (!serverUrl && !customTransport) {
+    throw new Error("ServerBridgeProvider requires either serverUrl or transport");
+  }
+  if (serverUrl && customTransport) {
+    throw new Error("ServerBridgeProvider accepts serverUrl OR transport, not both");
+  }
   const eventBus = useEventBus();
   const [connected, setConnected] = useState(false);
-  const registerSchema = useCallback(async () => {
-    try {
-      const res = await fetch(`${serverUrl}/register`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ schema })
-      });
-      const result = await res.json();
-      return !!result.success;
-    } catch (err) {
-      console.error("[ServerBridge] Registration failed:", err);
-      return false;
-    }
-  }, [schema, serverUrl]);
-  const unregisterSchema = useCallback(async () => {
-    try {
-      await fetch(`${serverUrl}/unregister`, { method: "DELETE" });
-    } catch {
-    }
-  }, [serverUrl]);
+  const transport = useMemo(
+    () => customTransport ?? createHttpTransport(serverUrl),
+    [serverUrl, customTransport]
+  );
+  const registerSchema = useCallback(
+    async () => transport.register(schema),
+    [schema, transport]
+  );
+  const unregisterSchema = useCallback(
+    async () => transport.unregister(),
+    [transport]
+  );
   const sendEvent = useCallback(async (orbitalName, event, payload) => {
     const emptyMeta = { success: false, clientEffects: 0, dataEntities: {}, emittedEvents: [] };
     if (!connected) return { effects: [], meta: emptyMeta };
     try {
-      const res = await fetch(`${serverUrl}/${orbitalName}/events`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ event, payload })
-      });
-      const result = await res.json();
+      const result = await transport.sendEvent(orbitalName, event, payload);
       const effects = [];
       const responseData = result.data || {};
       const dataEntities = {};
@@ -52257,7 +52283,7 @@ function ServerBridgeProvider({
       console.error("[ServerBridge] Event send failed:", err);
       return { effects: [], meta: { ...emptyMeta, error: err instanceof Error ? err.message : String(err) } };
     }
-  }, [connected, serverUrl, eventBus]);
+  }, [connected, transport, eventBus]);
   useEffect(() => {
     if (!schema) return;
     let cancelled = false;
@@ -52533,7 +52559,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate]);
   return null;
 }
-function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
+function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
   const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = useMemo(() => {
     if (pageName && traits2.length > 0) return traits2;
@@ -52647,7 +52673,7 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
           TraitInitializer,
           {
             traits: allPageTraits,
-            orbitalNames: serverUrl ? pageOrbitalNames : void 0,
+            orbitalNames: serverUrl || transport ? pageOrbitalNames : void 0,
             traitConfigsByName,
             orbitalsByTrait,
             onNavigate,
@@ -52660,8 +52686,8 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
       ]
     }
   ) }) });
-  if (serverUrl) {
-    return /* @__PURE__ */ jsx(ServerBridgeProvider, { schema, serverUrl, children: inner });
+  if (serverUrl || transport) {
+    return /* @__PURE__ */ jsx(ServerBridgeProvider, { schema, serverUrl, transport, children: inner });
   }
   return inner;
 }
@@ -52672,8 +52698,12 @@ function OrbPreview({
   height = "400px",
   className,
   serverUrl,
+  transport,
   initialPagePath
 }) {
+  if (serverUrl && transport) {
+    throw new Error("OrbPreview accepts serverUrl OR transport, not both");
+  }
   const [localFallback, setLocalFallback] = useState(false);
   const eventBus = useEventBus();
   const handleLocalFallback = useCallback(() => {
@@ -52695,21 +52725,21 @@ function OrbPreview({
     } else {
       parsed = schema;
     }
-    if (autoMock && !serverUrl) {
+    if (autoMock && !serverUrl && !transport) {
       const prepared = prepareSchemaForPreview(parsed);
       return { ok: true, schema: prepared.schema, mockData: prepared.mockData };
     }
     return { ok: true, schema: parsed, mockData: mockData ?? {} };
-  }, [schema, autoMock, serverUrl, mockData]);
+  }, [schema, autoMock, serverUrl, transport, mockData]);
   const parsedSchema = parseResult.ok ? parseResult.schema : null;
   const effectiveMockData = parseResult.ok ? parseResult.mockData : {};
   const persistence = useMemo(() => {
-    if (!parsedSchema || serverUrl) return void 0;
+    if (!parsedSchema || serverUrl || transport) return void 0;
     if (!autoMock) return void 0;
     const adapter = new InMemoryPersistence();
     adapter.seed(effectiveMockData);
     return adapter;
-  }, [parsedSchema, serverUrl, autoMock, effectiveMockData]);
+  }, [parsedSchema, serverUrl, transport, autoMock, effectiveMockData]);
   const pages = useMemo(() => {
     if (!parsedSchema) return [];
     try {
@@ -52771,6 +52801,7 @@ function OrbPreview({
           {
             schema: parsedSchema,
             serverUrl,
+            transport,
             mockData: effectiveMockData,
             pageName: currentPage,
             onNavigate: handleNavigate,

package/dist/runtime/BrowserPlayground.d.ts

@@ -0,0 +1,34 @@
+/**
+ * BrowserPlayground — in-browser Almadar runtime mount.
+ *
+ * Runs `OrbitalServerRuntime` (mock mode) in-process and threads it through
+ * `<OrbPreview>` via the `ServerBridgeTransport` adapter. Equivalent to
+ * canonical playground-runtime's server-mode mount, but without Express,
+ * fork, or HTTP — invokes `runtime.processOrbitalEvent` directly.
+ *
+ * Same React tree as `runtime-verify` (and apps/builder server-mode) speak,
+ * so any `@almadar/runtime` fix flows in through one bump cycle.
+ *
+ * @example
+ * ```tsx
+ * <BrowserPlayground schema={schema} mode="mock" height="100%" />
+ * ```
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { OrbitalSchema } from '@almadar/core';
+export interface BrowserPlaygroundProps {
+    /** OrbitalSchema to render. */
+    schema: OrbitalSchema;
+    /** Persistence mode for the in-process runtime. Default: 'mock' (Faker-seeded MockPersistenceAdapter). */
+    mode?: 'mock';
+    /** Initial page path to render (forwarded to OrbPreview). */
+    initialPagePath?: string;
+    /** Preview container height. Default: '400px'. */
+    height?: string;
+    /** CSS class for the outer container. */
+    className?: string;
+}
+export declare function BrowserPlayground({ schema, mode, initialPagePath, height, className, }: BrowserPlaygroundProps): React.ReactElement;
+export default BrowserPlayground;

package/dist/runtime/OrbPreview.d.ts

@@ -13,6 +13,7 @@
  */
 import React from 'react';
 import type { OrbitalSchema, EntityData } from '@almadar/core';
+import { type ServerBridgeTransport } from './ServerBridge';
 export interface OrbPreviewProps {
     /**
      * The orbital schema. Accepts a JSON string or an `OrbitalSchema` object
@@ -42,6 +43,12 @@ export interface OrbPreviewProps {
     className?: string;
     /** Server URL for dual execution (e.g. "/api/orbitals"). When set, events are forwarded to the server. */
     serverUrl?: string;
+    /**
+     * Custom transport for in-process execution. Mutually exclusive with
+     * `serverUrl`. Used by `<BrowserPlayground>` to invoke
+     * `OrbitalServerRuntime.processOrbitalEvent` directly without HTTP.
+     */
+    transport?: ServerBridgeTransport;
     /**
      * Initial page path to render (e.g. `/deals`). Resolves against the
      * schema's `pages[]` to seed `currentPage` so the right orbital's traits
@@ -64,7 +71,7 @@ export interface OrbPreviewProps {
  * <OrbPreview schema={schema} serverUrl="/api/orbitals" />
  * ```
  */
-export declare function OrbPreview({ schema, mockData, autoMock, height, className, serverUrl, initialPagePath, }: OrbPreviewProps): React.ReactElement;
+export declare function OrbPreview({ schema, mockData, autoMock, height, className, serverUrl, transport, initialPagePath, }: OrbPreviewProps): React.ReactElement;
 export declare namespace OrbPreview {
     var displayName: string;
 }

package/dist/runtime/ServerBridge.d.ts

@@ -1,4 +1,33 @@
 import type { ReactNode } from 'react';
+import type { BusEventSource, EventPayload } from '@almadar/core';
+interface OrbitalEventResponse {
+    success: boolean;
+    transitioned: boolean;
+    states: Record<string, string>;
+    /**
+     * Server-cascade events carried back in the response. Each entry has a
+     * `source: BusEventSource` stamped by the compiled handler (`emit ...
+     * { source: __ORBITAL_SOURCE }`) so the client can re-broadcast on the
+     * qualified `UI:Orbital.Trait.EVENT` bus key (gap #13).
+     */
+    emittedEvents?: Array<{
+        event: string;
+        payload?: EventPayload;
+        source?: BusEventSource;
+    }>;
+    data?: Record<string, unknown[]>;
+    clientEffects?: unknown[];
+    /**
+     * Same effects as `clientEffects`, paired with the trait that produced
+     * each one. When present, prefer this for trait attribution. Falls back
+     * to legacy `clientEffects` parsing on older servers.
+     */
+    clientEffectsByTrait?: Array<{
+        traitName: string;
+        effect: unknown[];
+    }>;
+    error?: string;
+}
 export interface ServerClientEffect {
     type: 'render-ui' | 'navigate' | 'notify';
     slot?: string;
@@ -31,13 +60,40 @@ export interface ServerBridgeContextValue {
     connected: boolean;
     sendEvent: (orbitalName: string, event: string, payload?: Record<string, unknown>) => Promise<SendEventResult>;
 }
+/**
+ * Transport adapter for ServerBridgeProvider. Decouples the bridge's
+ * cascade-rebroadcast / effect-parsing logic from its wire format.
+ *
+ * - The `serverUrl` mode (default) uses an HTTP transport that POSTs to
+ *   `/register`, `/unregister`, `/:orbital/events`. This is what canonical
+ *   playground-runtime (`tools/runtime-verify`) and apps/builder-server
+ *   speak.
+ * - The `transport` mode lets a consumer plug in a direct function-call
+ *   adapter — used by `<BrowserPlayground>` to invoke
+ *   `OrbitalServerRuntime.processOrbitalEvent` in-process, no HTTP, no
+ *   server. Both modes return the same `OrbitalEventResponse` shape so the
+ *   cascade-rebroadcast logic is identical downstream.
+ */
+export interface ServerBridgeTransport {
+    register: (schema: unknown) => Promise<boolean>;
+    unregister: () => Promise<void>;
+    sendEvent: (orbitalName: string, event: string, payload?: Record<string, unknown>) => Promise<OrbitalEventResponse>;
+}
 /**
  * Access the server bridge. Returns a no-op stub when outside the provider.
  */
 export declare function useServerBridge(): ServerBridgeContextValue;
 export interface ServerBridgeProviderProps {
     schema: unknown;
-    serverUrl: string;
+    /** HTTP server URL (canonical playground-runtime / apps/builder-server). */
+    serverUrl?: string;
+    /**
+     * Custom transport adapter. Use this for in-process execution (e.g.
+     * `<BrowserPlayground>` invokes `OrbitalServerRuntime.processOrbitalEvent`
+     * directly). Mutually exclusive with `serverUrl`.
+     */
+    transport?: ServerBridgeTransport;
     children: ReactNode;
 }
-export declare function ServerBridgeProvider({ schema, serverUrl, children, }: ServerBridgeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ServerBridgeProvider({ schema, serverUrl, transport: customTransport, children, }: ServerBridgeProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/runtime/index.cjs

@@ -37,6 +37,7 @@ var langGraphql = require('react-syntax-highlighter/dist/esm/languages/prism/gra
 var core = require('@almadar/core');
 require('@tanstack/react-query');
 var runtime = require('@almadar/runtime');
+var OrbitalServerRuntime = require('@almadar/runtime/OrbitalServerRuntime');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -8229,13 +8230,13 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect68, useRef: useRef65, useCallback: useCallback110, useState: useState102 } = React115__namespace.default;
+      const { useEffect: useEffect69, useRef: useRef65, useCallback: useCallback110, useState: useState103 } = React115__namespace.default;
       const { Typography: Typography2 } = await Promise.resolve().then(() => (init_Typography(), Typography_exports));
       const { useEventBus: useEventBus2 } = await Promise.resolve().then(() => (init_useEventBus(), useEventBus_exports));
       function MapUpdater({ centerLat, centerLng, zoom }) {
         const map = useMap();
         const prevRef = useRef65({ centerLat, centerLng, zoom });
-        useEffect68(() => {
+        useEffect69(() => {
           const prev = prevRef.current;
           if (prev.centerLat !== centerLat || prev.centerLng !== centerLng || prev.zoom !== zoom) {
             map.setView([centerLat, centerLng], zoom);
@@ -8246,7 +8247,7 @@ var init_MapView = __esm({
       }
       function MapClickHandler({ onMapClick }) {
         const map = useMap();
-        useEffect68(() => {
+        useEffect69(() => {
           if (!onMapClick) return;
           const handler = (e) => {
             onMapClick(e.latlng.lat, e.latlng.lng);
@@ -8273,7 +8274,7 @@ var init_MapView = __esm({
         showAttribution = true
       }) {
         const eventBus = useEventBus2();
-        const [clickedPosition, setClickedPosition] = useState102(null);
+        const [clickedPosition, setClickedPosition] = useState103(null);
         const handleMapClick = useCallback110((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
@@ -38980,6 +38981,38 @@ init_EntitySchemaContext();
 init_useEventBus();
 init_logger();
 var xOrbitalLog2 = createLogger("almadar:runtime:cross-orbital");
+function createHttpTransport(serverUrl) {
+  return {
+    register: async (schema) => {
+      try {
+        const res = await fetch(`${serverUrl}/register`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ schema })
+        });
+        const result = await res.json();
+        return !!result.success;
+      } catch (err) {
+        console.error("[ServerBridge] Registration failed:", err);
+        return false;
+      }
+    },
+    unregister: async () => {
+      try {
+        await fetch(`${serverUrl}/unregister`, { method: "DELETE" });
+      } catch {
+      }
+    },
+    sendEvent: async (orbitalName, event, payload) => {
+      const res = await fetch(`${serverUrl}/${orbitalName}/events`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ event, payload })
+      });
+      return res.json();
+    }
+  };
+}
 var ServerBridgeContext = React115.createContext(null);
 function useServerBridge() {
   const ctx = React115.useContext(ServerBridgeContext);
@@ -38992,40 +39025,34 @@ function useServerBridge() {
 function ServerBridgeProvider({
   schema,
   serverUrl,
+  transport: customTransport,
   children
 }) {
+  if (!serverUrl && !customTransport) {
+    throw new Error("ServerBridgeProvider requires either serverUrl or transport");
+  }
+  if (serverUrl && customTransport) {
+    throw new Error("ServerBridgeProvider accepts serverUrl OR transport, not both");
+  }
   const eventBus = useEventBus();
   const [connected, setConnected] = React115.useState(false);
-  const registerSchema = React115.useCallback(async () => {
-    try {
-      const res = await fetch(`${serverUrl}/register`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ schema })
-      });
-      const result = await res.json();
-      return !!result.success;
-    } catch (err) {
-      console.error("[ServerBridge] Registration failed:", err);
-      return false;
-    }
-  }, [schema, serverUrl]);
-  const unregisterSchema = React115.useCallback(async () => {
-    try {
-      await fetch(`${serverUrl}/unregister`, { method: "DELETE" });
-    } catch {
-    }
-  }, [serverUrl]);
+  const transport = React115.useMemo(
+    () => customTransport ?? createHttpTransport(serverUrl),
+    [serverUrl, customTransport]
+  );
+  const registerSchema = React115.useCallback(
+    async () => transport.register(schema),
+    [schema, transport]
+  );
+  const unregisterSchema = React115.useCallback(
+    async () => transport.unregister(),
+    [transport]
+  );
   const sendEvent = React115.useCallback(async (orbitalName, event, payload) => {
     const emptyMeta = { success: false, clientEffects: 0, dataEntities: {}, emittedEvents: [] };
     if (!connected) return { effects: [], meta: emptyMeta };
     try {
-      const res = await fetch(`${serverUrl}/${orbitalName}/events`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ event, payload })
-      });
-      const result = await res.json();
+      const result = await transport.sendEvent(orbitalName, event, payload);
       const effects = [];
       const responseData = result.data || {};
       const dataEntities = {};
@@ -39083,7 +39110,7 @@ function ServerBridgeProvider({
       console.error("[ServerBridge] Event send failed:", err);
       return { effects: [], meta: { ...emptyMeta, error: err instanceof Error ? err.message : String(err) } };
     }
-  }, [connected, serverUrl, eventBus]);
+  }, [connected, transport, eventBus]);
   React115.useEffect(() => {
     if (!schema) return;
     let cancelled = false;
@@ -39359,7 +39386,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate]);
   return null;
 }
-function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
+function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
   const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = React115.useMemo(() => {
     if (pageName && traits2.length > 0) return traits2;
@@ -39473,7 +39500,7 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
           TraitInitializer,
           {
             traits: allPageTraits,
-            orbitalNames: serverUrl ? pageOrbitalNames : void 0,
+            orbitalNames: serverUrl || transport ? pageOrbitalNames : void 0,
             traitConfigsByName,
             orbitalsByTrait,
             onNavigate,
@@ -39486,8 +39513,8 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
       ]
     }
   ) }) });
-  if (serverUrl) {
-    return /* @__PURE__ */ jsxRuntime.jsx(ServerBridgeProvider, { schema, serverUrl, children: inner });
+  if (serverUrl || transport) {
+    return /* @__PURE__ */ jsxRuntime.jsx(ServerBridgeProvider, { schema, serverUrl, transport, children: inner });
   }
   return inner;
 }
@@ -39498,8 +39525,12 @@ function OrbPreview({
   height = "400px",
   className,
   serverUrl,
+  transport,
   initialPagePath
 }) {
+  if (serverUrl && transport) {
+    throw new Error("OrbPreview accepts serverUrl OR transport, not both");
+  }
   const [localFallback, setLocalFallback] = React115.useState(false);
   const eventBus = useEventBus();
   const handleLocalFallback = React115.useCallback(() => {
@@ -39521,21 +39552,21 @@ function OrbPreview({
     } else {
       parsed = schema;
     }
-    if (autoMock && !serverUrl) {
+    if (autoMock && !serverUrl && !transport) {
       const prepared = prepareSchemaForPreview(parsed);
       return { ok: true, schema: prepared.schema, mockData: prepared.mockData };
     }
     return { ok: true, schema: parsed, mockData: mockData ?? {} };
-  }, [schema, autoMock, serverUrl, mockData]);
+  }, [schema, autoMock, serverUrl, transport, mockData]);
   const parsedSchema = parseResult.ok ? parseResult.schema : null;
   const effectiveMockData = parseResult.ok ? parseResult.mockData : {};
   const persistence = React115.useMemo(() => {
-    if (!parsedSchema || serverUrl) return void 0;
+    if (!parsedSchema || serverUrl || transport) return void 0;
     if (!autoMock) return void 0;
     const adapter = new runtime.InMemoryPersistence();
     adapter.seed(effectiveMockData);
     return adapter;
-  }, [parsedSchema, serverUrl, autoMock, effectiveMockData]);
+  }, [parsedSchema, serverUrl, transport, autoMock, effectiveMockData]);
   const pages = React115.useMemo(() => {
     if (!parsedSchema) return [];
     try {
@@ -39597,6 +39628,7 @@ function OrbPreview({
           {
             schema: parsedSchema,
             serverUrl,
+            transport,
             mockData: effectiveMockData,
             pageName: currentPage,
             onNavigate: handleNavigate,
@@ -39609,7 +39641,50 @@ function OrbPreview({
   );
 }
 OrbPreview.displayName = "OrbPreview";
+function BrowserPlayground({
+  schema,
+  mode = "mock",
+  initialPagePath,
+  height,
+  className
+}) {
+  const [runtime] = React115.useState(
+    () => new OrbitalServerRuntime.OrbitalServerRuntime({ mode, debug: false })
+  );
+  React115.useEffect(() => {
+    void runtime.register(schema);
+    return () => {
+      runtime.unregisterAll();
+    };
+  }, [runtime, schema]);
+  const transport = React115.useMemo(() => ({
+    register: async (s) => {
+      await runtime.register(s);
+      return true;
+    },
+    unregister: async () => {
+      runtime.unregisterAll();
+    },
+    sendEvent: async (orbitalName, event, payload) => {
+      return runtime.processOrbitalEvent(orbitalName, {
+        event,
+        payload
+      });
+    }
+  }), [runtime]);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    OrbPreview,
+    {
+      schema,
+      transport,
+      initialPagePath,
+      height,
+      className
+    }
+  );
+}
 
+exports.BrowserPlayground = BrowserPlayground;
 exports.EntitySchemaProvider = EntitySchemaProvider;
 exports.OrbPreview = OrbPreview;
 exports.ServerBridgeProvider = ServerBridgeProvider;

package/dist/runtime/index.d.ts

@@ -13,6 +13,7 @@ export { TraitProvider, TraitContext, useTraitContext, useTrait, type TraitConte
 export { SlotsProvider, useSlots, useSlotContent, useSlotsActions, type SlotsState, type SlotState, type SlotPatternEntry, type SlotSource, type SlotsActions, type SlotsProviderProps, } from './ui/SlotsContext';
 export { createClientEffectHandlers, type ClientEventBus, type SlotSetter, type CreateClientEffectHandlersOptions, } from './createClientEffectHandlers';
 export { OrbPreview, type OrbPreviewProps } from './OrbPreview';
+export { BrowserPlayground, type BrowserPlaygroundProps } from './BrowserPlayground';
 export { prepareSchemaForPreview, buildMockData, adjustSchemaForMockData, type PreparedPreviewSchema, } from './prepareSchemaForPreview';
-export { ServerBridgeProvider, useServerBridge, type ServerBridgeContextValue, type ServerClientEffect } from './ServerBridge';
+export { ServerBridgeProvider, useServerBridge, type ServerBridgeContextValue, type ServerBridgeTransport, type ServerClientEffect } from './ServerBridge';
 export type { ResolvedTraitBinding, ResolvedTrait, ResolvedEntity, ResolvedPage, ResolvedIR, } from './types';

package/dist/runtime/index.js

@@ -37,6 +37,7 @@ import langGraphql from 'react-syntax-highlighter/dist/esm/languages/prism/graph
 import { isCircuitEvent, schemaToIR, getPage, clearSchemaCache as clearSchemaCache$1, isEntityCall, isInlineTrait } from '@almadar/core';
 import '@tanstack/react-query';
 import { StateMachineManager, createContextFromBindings, interpolateValue, createServerEffectHandlers, EffectExecutor, InMemoryPersistence } from '@almadar/runtime';
+import { OrbitalServerRuntime } from '@almadar/runtime/OrbitalServerRuntime';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -8184,13 +8185,13 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect68, useRef: useRef65, useCallback: useCallback110, useState: useState102 } = React115__default;
+      const { useEffect: useEffect69, useRef: useRef65, useCallback: useCallback110, useState: useState103 } = React115__default;
       const { Typography: Typography2 } = await Promise.resolve().then(() => (init_Typography(), Typography_exports));
       const { useEventBus: useEventBus2 } = await Promise.resolve().then(() => (init_useEventBus(), useEventBus_exports));
       function MapUpdater({ centerLat, centerLng, zoom }) {
         const map = useMap();
         const prevRef = useRef65({ centerLat, centerLng, zoom });
-        useEffect68(() => {
+        useEffect69(() => {
           const prev = prevRef.current;
           if (prev.centerLat !== centerLat || prev.centerLng !== centerLng || prev.zoom !== zoom) {
             map.setView([centerLat, centerLng], zoom);
@@ -8201,7 +8202,7 @@ var init_MapView = __esm({
       }
       function MapClickHandler({ onMapClick }) {
         const map = useMap();
-        useEffect68(() => {
+        useEffect69(() => {
           if (!onMapClick) return;
           const handler = (e) => {
             onMapClick(e.latlng.lat, e.latlng.lng);
@@ -8228,7 +8229,7 @@ var init_MapView = __esm({
         showAttribution = true
       }) {
         const eventBus = useEventBus2();
-        const [clickedPosition, setClickedPosition] = useState102(null);
+        const [clickedPosition, setClickedPosition] = useState103(null);
         const handleMapClick = useCallback110((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
@@ -38935,6 +38936,38 @@ init_EntitySchemaContext();
 init_useEventBus();
 init_logger();
 var xOrbitalLog2 = createLogger("almadar:runtime:cross-orbital");
+function createHttpTransport(serverUrl) {
+  return {
+    register: async (schema) => {
+      try {
+        const res = await fetch(`${serverUrl}/register`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ schema })
+        });
+        const result = await res.json();
+        return !!result.success;
+      } catch (err) {
+        console.error("[ServerBridge] Registration failed:", err);
+        return false;
+      }
+    },
+    unregister: async () => {
+      try {
+        await fetch(`${serverUrl}/unregister`, { method: "DELETE" });
+      } catch {
+      }
+    },
+    sendEvent: async (orbitalName, event, payload) => {
+      const res = await fetch(`${serverUrl}/${orbitalName}/events`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ event, payload })
+      });
+      return res.json();
+    }
+  };
+}
 var ServerBridgeContext = createContext(null);
 function useServerBridge() {
   const ctx = useContext(ServerBridgeContext);
@@ -38947,40 +38980,34 @@ function useServerBridge() {
 function ServerBridgeProvider({
   schema,
   serverUrl,
+  transport: customTransport,
   children
 }) {
+  if (!serverUrl && !customTransport) {
+    throw new Error("ServerBridgeProvider requires either serverUrl or transport");
+  }
+  if (serverUrl && customTransport) {
+    throw new Error("ServerBridgeProvider accepts serverUrl OR transport, not both");
+  }
   const eventBus = useEventBus();
   const [connected, setConnected] = useState(false);
-  const registerSchema = useCallback(async () => {
-    try {
-      const res = await fetch(`${serverUrl}/register`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ schema })
-      });
-      const result = await res.json();
-      return !!result.success;
-    } catch (err) {
-      console.error("[ServerBridge] Registration failed:", err);
-      return false;
-    }
-  }, [schema, serverUrl]);
-  const unregisterSchema = useCallback(async () => {
-    try {
-      await fetch(`${serverUrl}/unregister`, { method: "DELETE" });
-    } catch {
-    }
-  }, [serverUrl]);
+  const transport = useMemo(
+    () => customTransport ?? createHttpTransport(serverUrl),
+    [serverUrl, customTransport]
+  );
+  const registerSchema = useCallback(
+    async () => transport.register(schema),
+    [schema, transport]
+  );
+  const unregisterSchema = useCallback(
+    async () => transport.unregister(),
+    [transport]
+  );
   const sendEvent = useCallback(async (orbitalName, event, payload) => {
     const emptyMeta = { success: false, clientEffects: 0, dataEntities: {}, emittedEvents: [] };
     if (!connected) return { effects: [], meta: emptyMeta };
     try {
-      const res = await fetch(`${serverUrl}/${orbitalName}/events`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ event, payload })
-      });
-      const result = await res.json();
+      const result = await transport.sendEvent(orbitalName, event, payload);
       const effects = [];
       const responseData = result.data || {};
       const dataEntities = {};
@@ -39038,7 +39065,7 @@ function ServerBridgeProvider({
       console.error("[ServerBridge] Event send failed:", err);
       return { effects: [], meta: { ...emptyMeta, error: err instanceof Error ? err.message : String(err) } };
     }
-  }, [connected, serverUrl, eventBus]);
+  }, [connected, transport, eventBus]);
   useEffect(() => {
     if (!schema) return;
     let cancelled = false;
@@ -39314,7 +39341,7 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate]);
   return null;
 }
-function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
+function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
   const { traits: traits2, allEntities, ir } = useResolvedSchema(schema, pageName);
   const allPageTraits = useMemo(() => {
     if (pageName && traits2.length > 0) return traits2;
@@ -39428,7 +39455,7 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
           TraitInitializer,
           {
             traits: allPageTraits,
-            orbitalNames: serverUrl ? pageOrbitalNames : void 0,
+            orbitalNames: serverUrl || transport ? pageOrbitalNames : void 0,
             traitConfigsByName,
             orbitalsByTrait,
             onNavigate,
@@ -39441,8 +39468,8 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
       ]
     }
   ) }) });
-  if (serverUrl) {
-    return /* @__PURE__ */ jsx(ServerBridgeProvider, { schema, serverUrl, children: inner });
+  if (serverUrl || transport) {
+    return /* @__PURE__ */ jsx(ServerBridgeProvider, { schema, serverUrl, transport, children: inner });
   }
   return inner;
 }
@@ -39453,8 +39480,12 @@ function OrbPreview({
   height = "400px",
   className,
   serverUrl,
+  transport,
   initialPagePath
 }) {
+  if (serverUrl && transport) {
+    throw new Error("OrbPreview accepts serverUrl OR transport, not both");
+  }
   const [localFallback, setLocalFallback] = useState(false);
   const eventBus = useEventBus();
   const handleLocalFallback = useCallback(() => {
@@ -39476,21 +39507,21 @@ function OrbPreview({
     } else {
       parsed = schema;
     }
-    if (autoMock && !serverUrl) {
+    if (autoMock && !serverUrl && !transport) {
       const prepared = prepareSchemaForPreview(parsed);
       return { ok: true, schema: prepared.schema, mockData: prepared.mockData };
     }
     return { ok: true, schema: parsed, mockData: mockData ?? {} };
-  }, [schema, autoMock, serverUrl, mockData]);
+  }, [schema, autoMock, serverUrl, transport, mockData]);
   const parsedSchema = parseResult.ok ? parseResult.schema : null;
   const effectiveMockData = parseResult.ok ? parseResult.mockData : {};
   const persistence = useMemo(() => {
-    if (!parsedSchema || serverUrl) return void 0;
+    if (!parsedSchema || serverUrl || transport) return void 0;
     if (!autoMock) return void 0;
     const adapter = new InMemoryPersistence();
     adapter.seed(effectiveMockData);
     return adapter;
-  }, [parsedSchema, serverUrl, autoMock, effectiveMockData]);
+  }, [parsedSchema, serverUrl, transport, autoMock, effectiveMockData]);
   const pages = useMemo(() => {
     if (!parsedSchema) return [];
     try {
@@ -39552,6 +39583,7 @@ function OrbPreview({
           {
             schema: parsedSchema,
             serverUrl,
+            transport,
             mockData: effectiveMockData,
             pageName: currentPage,
             onNavigate: handleNavigate,
@@ -39564,5 +39596,47 @@ function OrbPreview({
   );
 }
 OrbPreview.displayName = "OrbPreview";
+function BrowserPlayground({
+  schema,
+  mode = "mock",
+  initialPagePath,
+  height,
+  className
+}) {
+  const [runtime] = useState(
+    () => new OrbitalServerRuntime({ mode, debug: false })
+  );
+  useEffect(() => {
+    void runtime.register(schema);
+    return () => {
+      runtime.unregisterAll();
+    };
+  }, [runtime, schema]);
+  const transport = useMemo(() => ({
+    register: async (s) => {
+      await runtime.register(s);
+      return true;
+    },
+    unregister: async () => {
+      runtime.unregisterAll();
+    },
+    sendEvent: async (orbitalName, event, payload) => {
+      return runtime.processOrbitalEvent(orbitalName, {
+        event,
+        payload
+      });
+    }
+  }), [runtime]);
+  return /* @__PURE__ */ jsx(
+    OrbPreview,
+    {
+      schema,
+      transport,
+      initialPagePath,
+      height,
+      className
+    }
+  );
+}
 
-export { EntitySchemaProvider, OrbPreview, ServerBridgeProvider, SlotsProvider, TraitContext, TraitProvider, adjustSchemaForMockData, buildMockData, clearSchemaCache, createClientEffectHandlers, prepareSchemaForPreview, useEntityDefinition, useEntitySchema, useEntitySchemaOptional, useResolvedSchema, useServerBridge, useSlotContent, useSlots, useSlotsActions, useTrait, useTraitContext, useTraitStateMachine };
+export { BrowserPlayground, EntitySchemaProvider, OrbPreview, ServerBridgeProvider, SlotsProvider, TraitContext, TraitProvider, adjustSchemaForMockData, buildMockData, clearSchemaCache, createClientEffectHandlers, prepareSchemaForPreview, useEntityDefinition, useEntitySchema, useEntitySchemaOptional, useResolvedSchema, useServerBridge, useSlotContent, useSlots, useSlotsActions, useTrait, useTraitContext, useTraitStateMachine };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "4.10.7",
+  "version": "4.11.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",
@@ -121,7 +121,7 @@
     "@almadar/core": "^7.0.0",
     "@almadar/evaluator": ">=2.9.2",
     "@almadar/patterns": ">=2.17.1",
-    "@almadar/runtime": "^5.5.0",
+    "@almadar/runtime": "^5.7.0",
     "@almadar/std": ">=6.4.1",
     "@almadar/syntax": ">=1.3.1",
     "@xyflow/react": "12.10.1",