@almadar/ui 4.11.0 → 4.12.0

package/dist/avl/index.cjs

@@ -4492,6 +4492,16 @@ function useUISlotManager() {
     },
     []
   );
+  const updateTraitContent = React128.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,
@@ -4503,7 +4513,8 @@ function useUISlotManager() {
     hasContent,
     getContent,
     getTraitContent,
-    subscribeTrait
+    subscribeTrait,
+    updateTraitContent
   };
 }
 var DEFAULT_SOURCE_KEY, MULTI_SOURCE_STACK_TRAIT, ALL_SLOTS, DEFAULT_SLOTS, DEFAULT_SOURCES, idCounter;
@@ -51542,6 +51553,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();
@@ -52516,32 +52597,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();
@@ -52557,9 +52655,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 = React128.useRef(false);
@@ -52599,10 +52697,10 @@ 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, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
@@ -52708,6 +52806,9 @@ function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavi
     }
     return map;
   }, [schema]);
+  const embeddedTraits = React128.useMemo(() => {
+    return collectEmbeddedTraits(schema);
+  }, [schema]);
   const inner = /* @__PURE__ */ jsxRuntime.jsx(VerificationProvider, { enabled: true, children: /* @__PURE__ */ jsxRuntime.jsx(SlotsProvider, { children: /* @__PURE__ */ jsxRuntime.jsxs(
     EntitySchemaProvider,
     {
@@ -52722,6 +52823,7 @@ function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavi
             orbitalNames: serverUrl || transport ? pageOrbitalNames : void 0,
             traitConfigsByName,
             orbitalsByTrait,
+            embeddedTraits,
             onNavigate,
             onLocalFallback,
             persistence

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();
@@ -52470,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();
@@ -52511,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);
@@ -52553,10 +52651,10 @@ 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, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
@@ -52662,6 +52760,9 @@ function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavi
     }
     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,
     {
@@ -52676,6 +52777,7 @@ function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavi
             orbitalNames: serverUrl || transport ? pageOrbitalNames : void 0,
             traitConfigsByName,
             orbitalsByTrait,
+            embeddedTraits,
             onNavigate,
             onLocalFallback,
             persistence

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/embedded-traits.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Embed-aware slot routing — static analysis pass.
+ *
+ * Walks every trait's `transitions[].effects` looking for `render-ui`
+ * patterns whose tree contains `@trait.<Name>` string literals. Returns
+ * the flat set of trait names that are referenced this way by some
+ * sibling layout.
+ *
+ * Used by `<OrbPreview>` to route `applyServerEffects` — when an
+ * embedded trait's render-ui effect arrives, the runtime updates that
+ * trait's per-trait sidecar (`traitIndexRef`) only and skips the slot
+ * write. The sibling layout owns the slot and embeds the trait's frame
+ * via `<TraitFrame>`. Mirrors the compiled-path codegen which inlines
+ * the atom views as JSX inside the layout's pattern, never having them
+ * write a shared slot.
+ *
+ * The walker is a structural twin of
+ * `packages/almadar-runtime/src/resolver/reference-resolver.ts`'s
+ * `renameEventsInRenderUiConfig` — same recursive pattern shape, just
+ * collecting `@trait.X` substrings instead of renaming events.
+ *
+ * @packageDocumentation
+ */
+import type { OrbitalSchema } from '@almadar/core';
+/**
+ * Build the flat set of trait names that are referenced via `@trait.X`
+ * by at least one trait's render-ui in the resolved schema.
+ *
+ * Safe to call on the resolved (post-inline) schema. Memoize by
+ * reference at the call site.
+ */
+export declare function collectEmbeddedTraits(schema: OrbitalSchema | undefined | null): ReadonlySet<string>;

package/dist/runtime/index.cjs

@@ -38974,6 +38974,78 @@ init_Box();
 init_Typography();
 init_UISlotRenderer();
 init_useEventBus();
+
+// 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;
+}
+
+// runtime/OrbPreview.tsx
 init_SlotsContext();
 init_EntitySchemaContext();
 
@@ -39297,32 +39369,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 = context.useUISlots();
@@ -39338,9 +39427,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 = React115.useRef(false);
@@ -39380,10 +39469,10 @@ 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, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
@@ -39489,6 +39578,9 @@ function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavi
     }
     return map;
   }, [schema]);
+  const embeddedTraits = React115.useMemo(() => {
+    return collectEmbeddedTraits(schema);
+  }, [schema]);
   const inner = /* @__PURE__ */ jsxRuntime.jsx(providers.VerificationProvider, { enabled: true, children: /* @__PURE__ */ jsxRuntime.jsx(SlotsProvider, { children: /* @__PURE__ */ jsxRuntime.jsxs(
     EntitySchemaProvider,
     {
@@ -39503,6 +39595,7 @@ function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavi
             orbitalNames: serverUrl || transport ? pageOrbitalNames : void 0,
             traitConfigsByName,
             orbitalsByTrait,
+            embeddedTraits,
             onNavigate,
             onLocalFallback,
             persistence

package/dist/runtime/index.js

@@ -38929,6 +38929,78 @@ init_Box();
 init_Typography();
 init_UISlotRenderer();
 init_useEventBus();
+
+// 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;
+}
+
+// runtime/OrbPreview.tsx
 init_SlotsContext();
 init_EntitySchemaContext();
 
@@ -39252,32 +39324,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();
@@ -39293,9 +39382,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);
@@ -39335,10 +39424,10 @@ 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, transport, mockData, pageName, onNavigate, onLocalFallback, persistence }) {
@@ -39444,6 +39533,9 @@ function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavi
     }
     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,
     {
@@ -39458,6 +39550,7 @@ function SchemaRunner({ schema, serverUrl, transport, mockData, pageName, onNavi
             orbitalNames: serverUrl || transport ? pageOrbitalNames : void 0,
             traitConfigsByName,
             orbitalsByTrait,
+            embeddedTraits,
             onNavigate,
             onLocalFallback,
             persistence

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "4.11.0",
+  "version": "4.12.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",