@almadar/ui 2.58.0 → 2.59.1

package/dist/context/index.cjs

@@ -25,6 +25,8 @@ function useUISlotManager() {
   const [slots, setSlots] = react.useState(DEFAULT_SLOTS);
   const subscribersRef = react.useRef(/* @__PURE__ */ new Set());
   const timersRef = react.useRef(/* @__PURE__ */ new Map());
+  const traitIndexRef = react.useRef(/* @__PURE__ */ new Map());
+  const traitSubscribersRef = react.useRef(/* @__PURE__ */ new Map());
   react.useEffect(() => {
     return () => {
       timersRef.current.forEach((timer) => clearTimeout(timer));
@@ -40,6 +42,29 @@ function useUISlotManager() {
       }
     });
   }, []);
+  const notifyTraitSubscribers = react.useCallback(
+    (traitName, content) => {
+      const subs = traitSubscribersRef.current.get(traitName);
+      if (!subs) return;
+      subs.forEach((callback) => {
+        try {
+          callback(content);
+        } catch (error) {
+          console.error(`[UISlots] Trait subscriber error (${traitName}):`, error);
+        }
+      });
+    },
+    []
+  );
+  const indexTraitRender = react.useCallback(
+    (traitName, content) => {
+      traitIndexRef.current.set(traitName, content);
+    },
+    []
+  );
+  const unindexTrait = react.useCallback((traitName) => {
+    traitIndexRef.current.delete(traitName);
+  }, []);
   const render = react.useCallback((config) => {
     const id = generateId();
     const content = {
@@ -74,11 +99,15 @@ function useUISlotManager() {
         );
         return prev;
       }
+      if (content.sourceTrait) {
+        indexTraitRender(content.sourceTrait, content);
+        notifyTraitSubscribers(content.sourceTrait, content);
+      }
       notifySubscribers(config.target, content);
       return { ...prev, [config.target]: content };
     });
     return id;
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, indexTraitRender]);
   const clear = react.useCallback((slot) => {
     setSlots((prev) => {
       const content = prev[slot];
@@ -89,11 +118,15 @@ function useUISlotManager() {
           timersRef.current.delete(content.id);
         }
         content.onDismiss?.();
+        if (content.sourceTrait) {
+          unindexTrait(content.sourceTrait);
+          notifyTraitSubscribers(content.sourceTrait, null);
+        }
         notifySubscribers(slot, null);
       }
       return { ...prev, [slot]: null };
     });
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, unindexTrait]);
   const clearById = react.useCallback((id) => {
     setSlots((prev) => {
       const entry = Object.entries(prev).find(([, content]) => content?.id === id);
@@ -105,12 +138,16 @@ function useUISlotManager() {
           timersRef.current.delete(id);
         }
         content.onDismiss?.();
+        if (content.sourceTrait) {
+          unindexTrait(content.sourceTrait);
+          notifyTraitSubscribers(content.sourceTrait, null);
+        }
         notifySubscribers(slot, null);
         return { ...prev, [slot]: null };
       }
       return prev;
     });
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, unindexTrait]);
   const clearAll = react.useCallback(() => {
     timersRef.current.forEach((timer) => clearTimeout(timer));
     timersRef.current.clear();
@@ -118,12 +155,16 @@ function useUISlotManager() {
       Object.entries(prev).forEach(([slot, content]) => {
         if (content) {
           content.onDismiss?.();
+          if (content.sourceTrait) {
+            notifyTraitSubscribers(content.sourceTrait, null);
+          }
           notifySubscribers(slot, null);
         }
       });
       return DEFAULT_SLOTS;
     });
-  }, [notifySubscribers]);
+    traitIndexRef.current.clear();
+  }, [notifySubscribers, notifyTraitSubscribers]);
   const subscribe = react.useCallback((callback) => {
     subscribersRef.current.add(callback);
     return () => {
@@ -136,6 +177,31 @@ function useUISlotManager() {
   const getContent = react.useCallback((slot) => {
     return slots[slot];
   }, [slots]);
+  const getTraitContent = react.useCallback(
+    (traitName) => {
+      return traitIndexRef.current.get(traitName) ?? null;
+    },
+    []
+  );
+  const subscribeTrait = react.useCallback(
+    (traitName, callback) => {
+      let set = traitSubscribersRef.current.get(traitName);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        traitSubscribersRef.current.set(traitName, set);
+      }
+      set.add(callback);
+      return () => {
+        const s = traitSubscribersRef.current.get(traitName);
+        if (!s) return;
+        s.delete(callback);
+        if (s.size === 0) {
+          traitSubscribersRef.current.delete(traitName);
+        }
+      };
+    },
+    []
+  );
   return {
     slots,
     render,
@@ -144,7 +210,9 @@ function useUISlotManager() {
     clearAll,
     subscribe,
     hasContent,
-    getContent
+    getContent,
+    getTraitContent,
+    subscribeTrait
   };
 }
 var UISlotContext = react.createContext(null);

package/dist/context/index.js

@@ -23,6 +23,8 @@ function useUISlotManager() {
   const [slots, setSlots] = useState(DEFAULT_SLOTS);
   const subscribersRef = useRef(/* @__PURE__ */ new Set());
   const timersRef = useRef(/* @__PURE__ */ new Map());
+  const traitIndexRef = useRef(/* @__PURE__ */ new Map());
+  const traitSubscribersRef = useRef(/* @__PURE__ */ new Map());
   useEffect(() => {
     return () => {
       timersRef.current.forEach((timer) => clearTimeout(timer));
@@ -38,6 +40,29 @@ function useUISlotManager() {
       }
     });
   }, []);
+  const notifyTraitSubscribers = useCallback(
+    (traitName, content) => {
+      const subs = traitSubscribersRef.current.get(traitName);
+      if (!subs) return;
+      subs.forEach((callback) => {
+        try {
+          callback(content);
+        } catch (error) {
+          console.error(`[UISlots] Trait subscriber error (${traitName}):`, error);
+        }
+      });
+    },
+    []
+  );
+  const indexTraitRender = useCallback(
+    (traitName, content) => {
+      traitIndexRef.current.set(traitName, content);
+    },
+    []
+  );
+  const unindexTrait = useCallback((traitName) => {
+    traitIndexRef.current.delete(traitName);
+  }, []);
   const render = useCallback((config) => {
     const id = generateId();
     const content = {
@@ -72,11 +97,15 @@ function useUISlotManager() {
         );
         return prev;
       }
+      if (content.sourceTrait) {
+        indexTraitRender(content.sourceTrait, content);
+        notifyTraitSubscribers(content.sourceTrait, content);
+      }
       notifySubscribers(config.target, content);
       return { ...prev, [config.target]: content };
     });
     return id;
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, indexTraitRender]);
   const clear = useCallback((slot) => {
     setSlots((prev) => {
       const content = prev[slot];
@@ -87,11 +116,15 @@ function useUISlotManager() {
           timersRef.current.delete(content.id);
         }
         content.onDismiss?.();
+        if (content.sourceTrait) {
+          unindexTrait(content.sourceTrait);
+          notifyTraitSubscribers(content.sourceTrait, null);
+        }
         notifySubscribers(slot, null);
       }
       return { ...prev, [slot]: null };
     });
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, unindexTrait]);
   const clearById = useCallback((id) => {
     setSlots((prev) => {
       const entry = Object.entries(prev).find(([, content]) => content?.id === id);
@@ -103,12 +136,16 @@ function useUISlotManager() {
           timersRef.current.delete(id);
         }
         content.onDismiss?.();
+        if (content.sourceTrait) {
+          unindexTrait(content.sourceTrait);
+          notifyTraitSubscribers(content.sourceTrait, null);
+        }
         notifySubscribers(slot, null);
         return { ...prev, [slot]: null };
       }
       return prev;
     });
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, unindexTrait]);
   const clearAll = useCallback(() => {
     timersRef.current.forEach((timer) => clearTimeout(timer));
     timersRef.current.clear();
@@ -116,12 +153,16 @@ function useUISlotManager() {
       Object.entries(prev).forEach(([slot, content]) => {
         if (content) {
           content.onDismiss?.();
+          if (content.sourceTrait) {
+            notifyTraitSubscribers(content.sourceTrait, null);
+          }
           notifySubscribers(slot, null);
         }
       });
       return DEFAULT_SLOTS;
     });
-  }, [notifySubscribers]);
+    traitIndexRef.current.clear();
+  }, [notifySubscribers, notifyTraitSubscribers]);
   const subscribe = useCallback((callback) => {
     subscribersRef.current.add(callback);
     return () => {
@@ -134,6 +175,31 @@ function useUISlotManager() {
   const getContent = useCallback((slot) => {
     return slots[slot];
   }, [slots]);
+  const getTraitContent = useCallback(
+    (traitName) => {
+      return traitIndexRef.current.get(traitName) ?? null;
+    },
+    []
+  );
+  const subscribeTrait = useCallback(
+    (traitName, callback) => {
+      let set = traitSubscribersRef.current.get(traitName);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        traitSubscribersRef.current.set(traitName, set);
+      }
+      set.add(callback);
+      return () => {
+        const s = traitSubscribersRef.current.get(traitName);
+        if (!s) return;
+        s.delete(callback);
+        if (s.size === 0) {
+          traitSubscribersRef.current.delete(traitName);
+        }
+      };
+    },
+    []
+  );
   return {
     slots,
     render,
@@ -142,7 +208,9 @@ function useUISlotManager() {
     clearAll,
     subscribe,
     hasContent,
-    getContent
+    getContent,
+    getTraitContent,
+    subscribeTrait
   };
 }
 var UISlotContext = createContext(null);

package/dist/hooks/index.cjs

@@ -1041,6 +1041,8 @@ function useUISlotManager() {
   const [slots, setSlots] = React.useState(DEFAULT_SLOTS);
   const subscribersRef = React.useRef(/* @__PURE__ */ new Set());
   const timersRef = React.useRef(/* @__PURE__ */ new Map());
+  const traitIndexRef = React.useRef(/* @__PURE__ */ new Map());
+  const traitSubscribersRef = React.useRef(/* @__PURE__ */ new Map());
   React.useEffect(() => {
     return () => {
       timersRef.current.forEach((timer) => clearTimeout(timer));
@@ -1056,6 +1058,29 @@ function useUISlotManager() {
       }
     });
   }, []);
+  const notifyTraitSubscribers = React.useCallback(
+    (traitName, content) => {
+      const subs = traitSubscribersRef.current.get(traitName);
+      if (!subs) return;
+      subs.forEach((callback) => {
+        try {
+          callback(content);
+        } catch (error) {
+          console.error(`[UISlots] Trait subscriber error (${traitName}):`, error);
+        }
+      });
+    },
+    []
+  );
+  const indexTraitRender = React.useCallback(
+    (traitName, content) => {
+      traitIndexRef.current.set(traitName, content);
+    },
+    []
+  );
+  const unindexTrait = React.useCallback((traitName) => {
+    traitIndexRef.current.delete(traitName);
+  }, []);
   const render = React.useCallback((config) => {
     const id = generateId();
     const content = {
@@ -1090,11 +1115,15 @@ function useUISlotManager() {
         );
         return prev;
       }
+      if (content.sourceTrait) {
+        indexTraitRender(content.sourceTrait, content);
+        notifyTraitSubscribers(content.sourceTrait, content);
+      }
       notifySubscribers(config.target, content);
       return { ...prev, [config.target]: content };
     });
     return id;
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, indexTraitRender]);
   const clear = React.useCallback((slot) => {
     setSlots((prev) => {
       const content = prev[slot];
@@ -1105,11 +1134,15 @@ function useUISlotManager() {
           timersRef.current.delete(content.id);
         }
         content.onDismiss?.();
+        if (content.sourceTrait) {
+          unindexTrait(content.sourceTrait);
+          notifyTraitSubscribers(content.sourceTrait, null);
+        }
         notifySubscribers(slot, null);
       }
       return { ...prev, [slot]: null };
     });
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, unindexTrait]);
   const clearById = React.useCallback((id) => {
     setSlots((prev) => {
       const entry = Object.entries(prev).find(([, content]) => content?.id === id);
@@ -1121,12 +1154,16 @@ function useUISlotManager() {
           timersRef.current.delete(id);
         }
         content.onDismiss?.();
+        if (content.sourceTrait) {
+          unindexTrait(content.sourceTrait);
+          notifyTraitSubscribers(content.sourceTrait, null);
+        }
         notifySubscribers(slot, null);
         return { ...prev, [slot]: null };
       }
       return prev;
     });
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, unindexTrait]);
   const clearAll = React.useCallback(() => {
     timersRef.current.forEach((timer) => clearTimeout(timer));
     timersRef.current.clear();
@@ -1134,12 +1171,16 @@ function useUISlotManager() {
       Object.entries(prev).forEach(([slot, content]) => {
         if (content) {
           content.onDismiss?.();
+          if (content.sourceTrait) {
+            notifyTraitSubscribers(content.sourceTrait, null);
+          }
           notifySubscribers(slot, null);
         }
       });
       return DEFAULT_SLOTS;
     });
-  }, [notifySubscribers]);
+    traitIndexRef.current.clear();
+  }, [notifySubscribers, notifyTraitSubscribers]);
   const subscribe2 = React.useCallback((callback) => {
     subscribersRef.current.add(callback);
     return () => {
@@ -1152,6 +1193,31 @@ function useUISlotManager() {
   const getContent = React.useCallback((slot) => {
     return slots[slot];
   }, [slots]);
+  const getTraitContent = React.useCallback(
+    (traitName) => {
+      return traitIndexRef.current.get(traitName) ?? null;
+    },
+    []
+  );
+  const subscribeTrait = React.useCallback(
+    (traitName, callback) => {
+      let set = traitSubscribersRef.current.get(traitName);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        traitSubscribersRef.current.set(traitName, set);
+      }
+      set.add(callback);
+      return () => {
+        const s = traitSubscribersRef.current.get(traitName);
+        if (!s) return;
+        s.delete(callback);
+        if (s.size === 0) {
+          traitSubscribersRef.current.delete(traitName);
+        }
+      };
+    },
+    []
+  );
   return {
     slots,
     render,
@@ -1160,7 +1226,9 @@ function useUISlotManager() {
     clearAll,
     subscribe: subscribe2,
     hasContent,
-    getContent
+    getContent,
+    getTraitContent,
+    subscribeTrait
   };
 }
 var UI_PREFIX = "UI:";

package/dist/hooks/index.js

@@ -1035,6 +1035,8 @@ function useUISlotManager() {
   const [slots, setSlots] = useState(DEFAULT_SLOTS);
   const subscribersRef = useRef(/* @__PURE__ */ new Set());
   const timersRef = useRef(/* @__PURE__ */ new Map());
+  const traitIndexRef = useRef(/* @__PURE__ */ new Map());
+  const traitSubscribersRef = useRef(/* @__PURE__ */ new Map());
   useEffect(() => {
     return () => {
       timersRef.current.forEach((timer) => clearTimeout(timer));
@@ -1050,6 +1052,29 @@ function useUISlotManager() {
       }
     });
   }, []);
+  const notifyTraitSubscribers = useCallback(
+    (traitName, content) => {
+      const subs = traitSubscribersRef.current.get(traitName);
+      if (!subs) return;
+      subs.forEach((callback) => {
+        try {
+          callback(content);
+        } catch (error) {
+          console.error(`[UISlots] Trait subscriber error (${traitName}):`, error);
+        }
+      });
+    },
+    []
+  );
+  const indexTraitRender = useCallback(
+    (traitName, content) => {
+      traitIndexRef.current.set(traitName, content);
+    },
+    []
+  );
+  const unindexTrait = useCallback((traitName) => {
+    traitIndexRef.current.delete(traitName);
+  }, []);
   const render = useCallback((config) => {
     const id = generateId();
     const content = {
@@ -1084,11 +1109,15 @@ function useUISlotManager() {
         );
         return prev;
       }
+      if (content.sourceTrait) {
+        indexTraitRender(content.sourceTrait, content);
+        notifyTraitSubscribers(content.sourceTrait, content);
+      }
       notifySubscribers(config.target, content);
       return { ...prev, [config.target]: content };
     });
     return id;
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, indexTraitRender]);
   const clear = useCallback((slot) => {
     setSlots((prev) => {
       const content = prev[slot];
@@ -1099,11 +1128,15 @@ function useUISlotManager() {
           timersRef.current.delete(content.id);
         }
         content.onDismiss?.();
+        if (content.sourceTrait) {
+          unindexTrait(content.sourceTrait);
+          notifyTraitSubscribers(content.sourceTrait, null);
+        }
         notifySubscribers(slot, null);
       }
       return { ...prev, [slot]: null };
     });
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, unindexTrait]);
   const clearById = useCallback((id) => {
     setSlots((prev) => {
       const entry = Object.entries(prev).find(([, content]) => content?.id === id);
@@ -1115,12 +1148,16 @@ function useUISlotManager() {
           timersRef.current.delete(id);
         }
         content.onDismiss?.();
+        if (content.sourceTrait) {
+          unindexTrait(content.sourceTrait);
+          notifyTraitSubscribers(content.sourceTrait, null);
+        }
         notifySubscribers(slot, null);
         return { ...prev, [slot]: null };
       }
       return prev;
     });
-  }, [notifySubscribers]);
+  }, [notifySubscribers, notifyTraitSubscribers, unindexTrait]);
   const clearAll = useCallback(() => {
     timersRef.current.forEach((timer) => clearTimeout(timer));
     timersRef.current.clear();
@@ -1128,12 +1165,16 @@ function useUISlotManager() {
       Object.entries(prev).forEach(([slot, content]) => {
         if (content) {
           content.onDismiss?.();
+          if (content.sourceTrait) {
+            notifyTraitSubscribers(content.sourceTrait, null);
+          }
           notifySubscribers(slot, null);
         }
       });
       return DEFAULT_SLOTS;
     });
-  }, [notifySubscribers]);
+    traitIndexRef.current.clear();
+  }, [notifySubscribers, notifyTraitSubscribers]);
   const subscribe2 = useCallback((callback) => {
     subscribersRef.current.add(callback);
     return () => {
@@ -1146,6 +1187,31 @@ function useUISlotManager() {
   const getContent = useCallback((slot) => {
     return slots[slot];
   }, [slots]);
+  const getTraitContent = useCallback(
+    (traitName) => {
+      return traitIndexRef.current.get(traitName) ?? null;
+    },
+    []
+  );
+  const subscribeTrait = useCallback(
+    (traitName, callback) => {
+      let set = traitSubscribersRef.current.get(traitName);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        traitSubscribersRef.current.set(traitName, set);
+      }
+      set.add(callback);
+      return () => {
+        const s = traitSubscribersRef.current.get(traitName);
+        if (!s) return;
+        s.delete(callback);
+        if (s.size === 0) {
+          traitSubscribersRef.current.delete(traitName);
+        }
+      };
+    },
+    []
+  );
   return {
     slots,
     render,
@@ -1154,7 +1220,9 @@ function useUISlotManager() {
     clearAll,
     subscribe: subscribe2,
     hasContent,
-    getContent
+    getContent,
+    getTraitContent,
+    subscribeTrait
   };
 }
 var UI_PREFIX = "UI:";

package/dist/hooks/useUISlots.d.ts

@@ -54,6 +54,16 @@ export interface RenderUIConfig {
  * Callback for slot changes
  */
 export type SlotChangeCallback = (slot: UISlot, content: SlotContent | null) => void;
+/**
+ * Fires when a specific trait's current render-ui output changes.
+ * Used by `<TraitFrame>` to subscribe only to the trait it embeds,
+ * avoiding wide re-renders when unrelated slots update.
+ *
+ * Per-trait index stores exactly one entry per trait (the most recent
+ * render), so the callback signature carries just the new content —
+ * no per-slot disambiguation needed.
+ */
+export type TraitChangeCallback = (content: SlotContent | null) => void;
 /**
  * UI Slot Manager interface
  */
@@ -74,6 +84,24 @@ export interface UISlotManager {
     hasContent: (slot: UISlot) => boolean;
     /** Get content for a slot */
     getContent: (slot: UISlot) => SlotContent | null;
+    /**
+     * Look up the most recent `render-ui` output a given trait produced,
+     * keyed by `SlotContent.sourceTrait`. Returns `null` when the trait
+     * hasn't rendered yet.
+     *
+     * Backs the `@trait.X` binding's client-side resolution via
+     * `<TraitFrame>`. See `docs/Almadar_Std_Gaps.md` §3.8. The binding is
+     * single-segment — there's intentionally no slot disambiguation.
+     */
+    getTraitContent: (traitName: string) => SlotContent | null;
+    /**
+     * Subscribe to changes in a specific trait's render output. Returns
+     * an unsubscribe function.
+     *
+     * Scoped per-trait so `<TraitFrame>` components only re-render when
+     * the trait they embed actually changes — not on every slot update.
+     */
+    subscribeTrait: (traitName: string, callback: TraitChangeCallback) => () => void;
 }
 declare const DEFAULT_SLOTS: Record<UISlot, SlotContent | null>;
 /**