@almadar/ui 4.10.7 → 4.12.0

package/dist/avl/index.js

@@ -4446,6 +4446,16 @@ function useUISlotManager() {
     },
     []
   );
+  const updateTraitContent = useCallback(
+    (traitName, content) => {
+      const id = generateId();
+      const fullContent = { ...content, id, sourceTrait: traitName };
+      indexTraitRender(traitName, fullContent);
+      notifyTraitSubscribers(traitName, fullContent);
+      return id;
+    },
+    [indexTraitRender, notifyTraitSubscribers]
+  );
   return {
     slots,
     render,
@@ -4457,7 +4467,8 @@ function useUISlotManager() {
     hasContent,
     getContent,
     getTraitContent,
-    subscribeTrait
+    subscribeTrait,
+    updateTraitContent
   };
 }
 var DEFAULT_SOURCE_KEY, MULTI_SOURCE_STACK_TRAIT, ALL_SLOTS, DEFAULT_SLOTS, DEFAULT_SOURCES, idCounter;
@@ -51496,6 +51507,76 @@ function useResolvedSchema(schema, pageName) {
   return result;
 }
 
+// runtime/embedded-traits.ts
+var TRAIT_BINDING_PREFIX = "@trait.";
+function collectTraitRefsFromValue(value, into) {
+  if (value === null || value === void 0) return;
+  if (typeof value === "string") {
+    if (value.startsWith(TRAIT_BINDING_PREFIX)) {
+      const rest = value.slice(TRAIT_BINDING_PREFIX.length);
+      const dot = rest.indexOf(".");
+      const traitName = dot === -1 ? rest : rest.slice(0, dot);
+      if (traitName.length > 0) into.add(traitName);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectTraitRefsFromValue(item, into);
+    return;
+  }
+  if (typeof value === "object") {
+    for (const v of Object.values(value)) {
+      collectTraitRefsFromValue(v, into);
+    }
+  }
+}
+function collectTraitRefsFromEffects(effects, into) {
+  if (!effects) return;
+  for (const effect of effects) {
+    if (!Array.isArray(effect)) continue;
+    if (effect[0] === "render-ui" && effect.length >= 3) {
+      collectTraitRefsFromValue(effect[2], into);
+      continue;
+    }
+    for (let i = 1; i < effect.length; i++) {
+      const arg = effect[i];
+      if (Array.isArray(arg)) collectTraitRefsFromEffects([arg], into);
+      else collectTraitRefsFromValue(arg, into);
+    }
+  }
+}
+function collectEmbeddedTraits(schema) {
+  const out = /* @__PURE__ */ new Set();
+  if (!schema?.orbitals) return out;
+  for (const orbital of schema.orbitals) {
+    if (!orbital || typeof orbital !== "object") continue;
+    const traits2 = orbital.traits;
+    if (!Array.isArray(traits2)) continue;
+    for (const trait of traits2) {
+      if (!trait || typeof trait !== "object") continue;
+      const resolved = trait._resolved;
+      const target = resolved && typeof resolved === "object" ? resolved : trait;
+      const stateMachine = target.stateMachine;
+      const transitions = stateMachine?.transitions;
+      if (!Array.isArray(transitions)) continue;
+      for (const t of transitions) {
+        if (!t || typeof t !== "object") continue;
+        const effects = t.effects;
+        collectTraitRefsFromEffects(effects, out);
+      }
+      const initialEffects = target.initialEffects;
+      collectTraitRefsFromEffects(initialEffects, out);
+      const ticks2 = target.ticks;
+      if (Array.isArray(ticks2)) {
+        for (const tick of ticks2) {
+          collectTraitRefsFromEffects(tick?.effects, out);
+        }
+      }
+    }
+  }
+  return out;
+}
+
 // hooks/index.ts
 init_useEventBus();
 init_useUISlots();
@@ -52154,6 +52235,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 +52279,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 +52364,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;
@@ -52444,32 +52551,49 @@ function SlotBridge() {
   }, [slots, render, clear]);
   return null;
 }
-function applyServerEffects(effects, uiSlots, onNavigate) {
+function applyServerEffects(effects, uiSlots, onNavigate, embeddedTraits) {
   for (const eff of effects) {
     if (eff.type === "render-ui" && eff.slot && eff.pattern) {
       const patternRecord = eff.pattern;
       const { type: patternType, children, ...inlineProps } = patternRecord;
       const normalizedChildren = Array.isArray(children) ? children.map((c) => normalizeChild(c)) : children;
-      xOrbitalLog3.info("slot-write", {
-        slot: eff.slot,
-        sourceTrait: eff.traitName ?? "server",
-        patternType: typeof patternType === "string" ? patternType : void 0
-      });
-      uiSlots.render({
-        target: eff.slot,
-        pattern: patternType,
-        props: {
-          ...inlineProps,
-          ...normalizedChildren !== void 0 ? { children: normalizedChildren } : {}
-        },
-        sourceTrait: eff.traitName ?? "server"
-      });
+      const sourceTrait = eff.traitName ?? "server";
+      const isEmbedded = embeddedTraits?.has(sourceTrait) ?? false;
+      const props = {
+        ...inlineProps,
+        ...normalizedChildren !== void 0 ? { children: normalizedChildren } : {}
+      };
+      if (isEmbedded) {
+        xOrbitalLog3.info("slot:embed-routed", {
+          sourceTrait,
+          slot: eff.slot,
+          patternType: typeof patternType === "string" ? patternType : void 0
+        });
+        uiSlots.updateTraitContent(sourceTrait, {
+          pattern: patternType,
+          props,
+          priority: 0,
+          animation: "fade"
+        });
+      } else {
+        xOrbitalLog3.info("slot-write", {
+          slot: eff.slot,
+          sourceTrait,
+          patternType: typeof patternType === "string" ? patternType : void 0
+        });
+        uiSlots.render({
+          target: eff.slot,
+          pattern: patternType,
+          props,
+          sourceTrait
+        });
+      }
     } else if (eff.type === "navigate" && eff.route && onNavigate) {
       onNavigate(eff.route, eff.params);
     }
   }
 }
-function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback, persistence, traitConfigsByName, orbitalsByTrait }) {
+function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFallback, persistence, traitConfigsByName, orbitalsByTrait, embeddedTraits }) {
   const slotsActions = useSlotsActions();
   const bridge = useServerBridge();
   const uiSlots = useUISlots();
@@ -52485,9 +52609,9 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
     for (const name of targets) {
       const { effects, meta } = await bridge.sendEvent(name, event, payload);
       recordServerResponse(name, event, meta);
-      applyServerEffects(effects, uiSlots, onNavigate);
+      applyServerEffects(effects, uiSlots, onNavigate, embeddedTraits);
     }
-  }, [bridge.connected, bridge.sendEvent, orbitalNames, uiSlots, onNavigate]);
+  }, [bridge.connected, bridge.sendEvent, orbitalNames, uiSlots, onNavigate, embeddedTraits]);
   const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate, traitConfigsByName, orbitalsByTrait } : { navigate: onNavigate, persistence, traitConfigsByName, orbitalsByTrait };
   const { sendEvent } = useTraitStateMachine(traits2, slotsActions, opts);
   const initSentRef = useRef(false);
@@ -52527,13 +52651,13 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
           effects: effectTraces,
           timestamp: Date.now()
         });
-        applyServerEffects(effects, uiSlots, onNavigate);
+        applyServerEffects(effects, uiSlots, onNavigate, embeddedTraits);
       }
     })();
-  }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate]);
+  }, [bridge.connected, orbitalNames, bridge.sendEvent, uiSlots, onNavigate, embeddedTraits]);
   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;
@@ -52636,6 +52760,9 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
     }
     return map;
   }, [schema]);
+  const embeddedTraits = useMemo(() => {
+    return collectEmbeddedTraits(schema);
+  }, [schema]);
   const inner = /* @__PURE__ */ jsx(VerificationProvider, { enabled: true, children: /* @__PURE__ */ jsx(SlotsProvider, { children: /* @__PURE__ */ jsxs(
     EntitySchemaProvider,
     {
@@ -52647,9 +52774,10 @@ function SchemaRunner({ schema, serverUrl, mockData, pageName, onNavigate, onLoc
           TraitInitializer,
           {
             traits: allPageTraits,
-            orbitalNames: serverUrl ? pageOrbitalNames : void 0,
+            orbitalNames: serverUrl || transport ? pageOrbitalNames : void 0,
             traitConfigsByName,
             orbitalsByTrait,
+            embeddedTraits,
             onNavigate,
             onLocalFallback,
             persistence
@@ -52660,8 +52788,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 +52800,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 +52827,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 +52903,7 @@ function OrbPreview({
           {
             schema: parsedSchema,
             serverUrl,
+            transport,
             mockData: effectiveMockData,
             pageName: currentPage,
             onNavigate: handleNavigate,

package/dist/components/index.cjs

@@ -41153,6 +41153,16 @@ function useUISlotManager() {
     },
     []
   );
+  const updateTraitContent = React111.useCallback(
+    (traitName, content) => {
+      const id = generateId();
+      const fullContent = { ...content, id, sourceTrait: traitName };
+      indexTraitRender(traitName, fullContent);
+      notifyTraitSubscribers(traitName, fullContent);
+      return id;
+    },
+    [indexTraitRender, notifyTraitSubscribers]
+  );
   return {
     slots,
     render,
@@ -41164,7 +41174,8 @@ function useUISlotManager() {
     hasContent,
     getContent,
     getTraitContent,
-    subscribeTrait
+    subscribeTrait,
+    updateTraitContent
   };
 }
 

package/dist/components/index.js

@@ -41108,6 +41108,16 @@ function useUISlotManager() {
     },
     []
   );
+  const updateTraitContent = useCallback(
+    (traitName, content) => {
+      const id = generateId();
+      const fullContent = { ...content, id, sourceTrait: traitName };
+      indexTraitRender(traitName, fullContent);
+      notifyTraitSubscribers(traitName, fullContent);
+      return id;
+    },
+    [indexTraitRender, notifyTraitSubscribers]
+  );
   return {
     slots,
     render,
@@ -41119,7 +41129,8 @@ function useUISlotManager() {
     hasContent,
     getContent,
     getTraitContent,
-    subscribeTrait
+    subscribeTrait,
+    updateTraitContent
   };
 }
 

package/dist/context/index.cjs

@@ -305,6 +305,16 @@ function useUISlotManager() {
     },
     []
   );
+  const updateTraitContent = react.useCallback(
+    (traitName, content) => {
+      const id = generateId();
+      const fullContent = { ...content, id, sourceTrait: traitName };
+      indexTraitRender(traitName, fullContent);
+      notifyTraitSubscribers(traitName, fullContent);
+      return id;
+    },
+    [indexTraitRender, notifyTraitSubscribers]
+  );
   return {
     slots,
     render,
@@ -316,7 +326,8 @@ function useUISlotManager() {
     hasContent,
     getContent,
     getTraitContent,
-    subscribeTrait
+    subscribeTrait,
+    updateTraitContent
   };
 }
 var UISlotContext = react.createContext(null);

package/dist/context/index.js

@@ -303,6 +303,16 @@ function useUISlotManager() {
     },
     []
   );
+  const updateTraitContent = useCallback(
+    (traitName, content) => {
+      const id = generateId();
+      const fullContent = { ...content, id, sourceTrait: traitName };
+      indexTraitRender(traitName, fullContent);
+      notifyTraitSubscribers(traitName, fullContent);
+      return id;
+    },
+    [indexTraitRender, notifyTraitSubscribers]
+  );
   return {
     slots,
     render,
@@ -314,7 +324,8 @@ function useUISlotManager() {
     hasContent,
     getContent,
     getTraitContent,
-    subscribeTrait
+    subscribeTrait,
+    updateTraitContent
   };
 }
 var UISlotContext = createContext(null);

package/dist/hooks/index.cjs

@@ -1348,6 +1348,16 @@ function useUISlotManager() {
     },
     []
   );
+  const updateTraitContent = react.useCallback(
+    (traitName, content) => {
+      const id = generateId();
+      const fullContent = { ...content, id, sourceTrait: traitName };
+      indexTraitRender(traitName, fullContent);
+      notifyTraitSubscribers(traitName, fullContent);
+      return id;
+    },
+    [indexTraitRender, notifyTraitSubscribers]
+  );
   return {
     slots,
     render,
@@ -1359,7 +1369,8 @@ function useUISlotManager() {
     hasContent,
     getContent,
     getTraitContent,
-    subscribeTrait
+    subscribeTrait,
+    updateTraitContent
   };
 }
 var UI_PREFIX = "UI:";

package/dist/hooks/index.js

@@ -1346,6 +1346,16 @@ function useUISlotManager() {
     },
     []
   );
+  const updateTraitContent = useCallback(
+    (traitName, content) => {
+      const id = generateId();
+      const fullContent = { ...content, id, sourceTrait: traitName };
+      indexTraitRender(traitName, fullContent);
+      notifyTraitSubscribers(traitName, fullContent);
+      return id;
+    },
+    [indexTraitRender, notifyTraitSubscribers]
+  );
   return {
     slots,
     render,
@@ -1357,7 +1367,8 @@ function useUISlotManager() {
     hasContent,
     getContent,
     getTraitContent,
-    subscribeTrait
+    subscribeTrait,
+    updateTraitContent
   };
 }
 var UI_PREFIX = "UI:";

package/dist/hooks/useUISlots.d.ts

@@ -119,6 +119,20 @@ export interface UISlotManager {
      * the trait they embed actually changes — not on every slot update.
      */
     subscribeTrait: (traitName: string, callback: TraitChangeCallback) => () => void;
+    /**
+     * Update only the per-trait sidecar without writing to any slot.
+     *
+     * Used for embed-aware slot routing: when a trait is referenced via
+     * `@trait.X` by a sibling layout's render-ui, its render output should
+     * not stack into the same slot the layout writes — the layout owns the
+     * slot and embeds the trait's frame via `<TraitFrame>`. This method
+     * keeps the per-trait sidecar (`traitIndexRef`) up-to-date so
+     * `<TraitFrame>` re-renders, while leaving `slots[target]` untouched.
+     *
+     * Mirrors what the compiled-path codegen does structurally — atoms
+     * inlined as JSX inside the layout's pattern, not writing slots.
+     */
+    updateTraitContent: (traitName: string, content: Omit<SlotContent, 'id' | 'sourceTrait'>) => string;
 }
 declare const DEFAULT_SLOTS: Record<UISlot, SlotContent | null>;
 /**

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;
 }