@almadar/ui 4.23.0 → 4.25.0

package/dist/hooks/useUISlots.d.ts

@@ -1,4 +1,36 @@
-import type { EventPayload } from '@almadar/core';
+/**
+ * useUISlots Hook
+ *
+ * Core hook for managing UI slot rendering in the trait-driven architecture.
+ * Traits use render_ui effects to dynamically render content into slots.
+ *
+ * Slots:
+ * - main: Primary content area
+ * - sidebar: Left/right sidebar
+ * - modal: Modal overlay
+ * - drawer: Slide-in drawer
+ * - overlay: Full-screen overlay
+ * - center: Centered popup
+ * - toast: Toast notifications
+ * - hud-top: Game HUD top bar
+ * - hud-bottom: Game HUD bottom bar
+ * - floating: Draggable floating panel
+ *
+ * Multi-source model (2026-04-24):
+ * A slot can receive renders from multiple source traits across independent
+ * batches (e.g. in the playground, ProbeCreate renders "main" on INIT, then
+ * later ProbePersistor cascades a render into "main" too). Prior code stored
+ * a single SlotContent per slot and last-writer-wins silently dropped
+ * earlier traits' frames. Internally the manager now holds a
+ * `Record<UISlot, Record<sourceKey, SlotContent>>` map and consumers see an
+ * aggregated view: a single SlotContent for single-source slots, or a
+ * synthetic `stack` wrapper when 2+ sources are active simultaneously.
+ * This mirrors the compiled-path page layout's VStack-of-trait-views.
+ *
+ * @packageDocumentation
+ */
+import type React from 'react';
+import type { EventPayloadValue, RenderItemLambda } from '@almadar/core';
 /**
  * Valid UI slot names
  */
@@ -8,13 +40,39 @@ export type UISlot = 'main' | 'sidebar' | 'modal' | 'drawer' | 'overlay' | 'cent
  */
 export type SlotAnimation = 'fade' | 'slide' | 'scale' | 'none';
 /**
- * Pattern-specific props carried by a rendered slot. Pattern authors decide
- * the concrete shape; the slot manager treats this as an opaque record of
- * field-like values sourced from the event-bus payload vocabulary so the
- * same types round-trip through render-ui → useUISlots → UISlotRenderer
- * without a private re-coercion boundary.
+ * Render-prop callback after fn-form-lambda conversion or
+ * `wrapCallbackForEvent` wrapping. Pattern components consume these as
+ * `renderItem` / `onTabChange` / `onClick` / etc. The arg list is
+ * contravariant (`never[]` accepts any caller shape — event handlers,
+ * 2-arg `(item, index)` render-props, etc.); the return is the union of
+ * shapes seen at this layer. Pattern-level prop types narrow the
+ * signature for each consumer downstream.
+ */
+export type SlotCallback = (...args: never[]) => void | React.ReactNode | EventPayloadValue;
+/**
+ * Render-ui prop value: any leaf flowing from a `(render-ui slot {...})`
+ * effect into a React pattern component. The union enumerates every
+ * shape the renderer can receive — no `unknown` escape hatch.
+ *
+ * - JSON primitives (`string`, `number`, `boolean`, `Date`, `null`,
+ *   `undefined`) come through `BindingResolver`.
+ * - `RenderItemLambda` is the unconverted tuple form `["fn", arg, body]`;
+ *   `SlotCallback` is the post-conversion callable form.
+ * - `React.ReactNode` covers substituted `<TraitFrame>` elements.
+ * - The recursive array + object branches mirror the `EventPayloadValue`
+ *   shape but with `SlotPropValue` leaves so functions and React nodes
+ *   can appear at any depth (e.g. `tabs[].content: "@trait.X"` surviving
+ *   substitution into a `ReactElement`).
+ */
+export type SlotPropValue = string | number | boolean | Date | null | undefined | RenderItemLambda | SlotCallback | React.ReactElement | ReadonlyArray<SlotPropValue> | {
+    readonly [key: string]: SlotPropValue;
+};
+/**
+ * Pattern-specific props carried by a rendered slot. The slot manager
+ * routes these from `(render-ui slot {...})` effects to React pattern
+ * components without coercion.
  */
-export type SlotProps = Record<string, EventPayload[string] | unknown>;
+export type SlotProps = Record<string, SlotPropValue>;
 /**
  * Content rendered in a slot
  */

package/dist/providers/index.cjs

@@ -38289,7 +38289,8 @@ function renderPatternChildren(children, onDismiss, parentId = "root", parentPat
     if (!child || typeof child !== "object") return null;
     const childId = `${parentId}-${index}`;
     const childPath = parentPath === "root" ? `root.children.${index}` : `${parentPath}.children.${index}`;
-    const { type: _childType, props: nestedProps, _id: _childNodeId, children: _childChildren, ...flatProps } = child;
+    const childAsRecord = child;
+    const { type: _childType, props: nestedProps, _id: _childNodeId, children: _childChildren, ...flatProps } = childAsRecord;
     const resolvedProps = nestedProps !== void 0 ? nestedProps : flatProps;
     if (_childChildren !== void 0 && nestedProps === void 0) {
       resolvedProps.children = _childChildren;
@@ -38317,7 +38318,46 @@ function renderPatternChildren(children, onDismiss, parentId = "root", parentPat
   });
 }
 function isPatternConfig(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) && "type" in value && typeof value.type === "string";
+  if (value === null || value === void 0) return false;
+  if (typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+  if (React115__namespace.default.isValidElement(value)) return false;
+  if (value instanceof Date) return false;
+  if (typeof value === "function") return false;
+  const record = value;
+  return "type" in record && typeof record.type === "string";
+}
+function isPlainConfigObject(value) {
+  if (React115__namespace.default.isValidElement(value)) return false;
+  if (value instanceof Date) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function substituteTraitRefsDeep(value, pathKey) {
+  if (typeof value === "string") {
+    const match = TRAIT_BINDING_RE.exec(value);
+    if (match) {
+      const traitName = match[1];
+      return /* @__PURE__ */ jsxRuntime.jsx(TraitFrame, { traitName }, `${pathKey}:${traitName}`);
+    }
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || value === null || value === void 0 || typeof value === "function") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (item, i) => substituteTraitRefsDeep(item, `${pathKey}[${i}]`)
+    );
+  }
+  if (typeof value === "object" && isPlainConfigObject(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = substituteTraitRefsDeep(v, `${pathKey}.${k}`);
+    }
+    return out;
+  }
+  return value;
 }
 function renderPatternProps(props, onDismiss) {
   const rendered = {};
@@ -38325,17 +38365,19 @@ function renderPatternProps(props, onDismiss) {
     if (key === "children") {
       rendered[key] = value;
     } else if (isPatternConfig(value)) {
+      const nestedProps = {};
+      for (const [k, v] of Object.entries(value)) {
+        if (k !== "type") nestedProps[k] = v;
+      }
       const childContent = {
         id: `prop-${key}`,
         pattern: value.type,
-        props: Object.fromEntries(
-          Object.entries(value).filter(([k]) => k !== "type")
-        ),
+        props: nestedProps,
         priority: 0
       };
       rendered[key] = /* @__PURE__ */ jsxRuntime.jsx(SlotContentRenderer, { content: childContent, onDismiss });
     } else {
-      rendered[key] = value;
+      rendered[key] = substituteTraitRefsDeep(value, `prop:${key}`);
     }
   }
   return rendered;

package/dist/providers/index.js

@@ -38244,7 +38244,8 @@ function renderPatternChildren(children, onDismiss, parentId = "root", parentPat
     if (!child || typeof child !== "object") return null;
     const childId = `${parentId}-${index}`;
     const childPath = parentPath === "root" ? `root.children.${index}` : `${parentPath}.children.${index}`;
-    const { type: _childType, props: nestedProps, _id: _childNodeId, children: _childChildren, ...flatProps } = child;
+    const childAsRecord = child;
+    const { type: _childType, props: nestedProps, _id: _childNodeId, children: _childChildren, ...flatProps } = childAsRecord;
     const resolvedProps = nestedProps !== void 0 ? nestedProps : flatProps;
     if (_childChildren !== void 0 && nestedProps === void 0) {
       resolvedProps.children = _childChildren;
@@ -38272,7 +38273,46 @@ function renderPatternChildren(children, onDismiss, parentId = "root", parentPat
   });
 }
 function isPatternConfig(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) && "type" in value && typeof value.type === "string";
+  if (value === null || value === void 0) return false;
+  if (typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+  if (React115__default.isValidElement(value)) return false;
+  if (value instanceof Date) return false;
+  if (typeof value === "function") return false;
+  const record = value;
+  return "type" in record && typeof record.type === "string";
+}
+function isPlainConfigObject(value) {
+  if (React115__default.isValidElement(value)) return false;
+  if (value instanceof Date) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function substituteTraitRefsDeep(value, pathKey) {
+  if (typeof value === "string") {
+    const match = TRAIT_BINDING_RE.exec(value);
+    if (match) {
+      const traitName = match[1];
+      return /* @__PURE__ */ jsx(TraitFrame, { traitName }, `${pathKey}:${traitName}`);
+    }
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || value === null || value === void 0 || typeof value === "function") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (item, i) => substituteTraitRefsDeep(item, `${pathKey}[${i}]`)
+    );
+  }
+  if (typeof value === "object" && isPlainConfigObject(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = substituteTraitRefsDeep(v, `${pathKey}.${k}`);
+    }
+    return out;
+  }
+  return value;
 }
 function renderPatternProps(props, onDismiss) {
   const rendered = {};
@@ -38280,17 +38320,19 @@ function renderPatternProps(props, onDismiss) {
     if (key === "children") {
       rendered[key] = value;
     } else if (isPatternConfig(value)) {
+      const nestedProps = {};
+      for (const [k, v] of Object.entries(value)) {
+        if (k !== "type") nestedProps[k] = v;
+      }
       const childContent = {
         id: `prop-${key}`,
         pattern: value.type,
-        props: Object.fromEntries(
-          Object.entries(value).filter(([k]) => k !== "type")
-        ),
+        props: nestedProps,
         priority: 0
       };
       rendered[key] = /* @__PURE__ */ jsx(SlotContentRenderer, { content: childContent, onDismiss });
     } else {
-      rendered[key] = value;
+      rendered[key] = substituteTraitRefsDeep(value, `prop:${key}`);
     }
   }
   return rendered;

package/dist/runtime/fn-form-lambda.d.ts

@@ -10,17 +10,18 @@
  * @packageDocumentation
  */
 import type { EntityRow, RenderItemLambda } from "@almadar/core";
-export declare function isFnFormLambda(value: unknown): value is RenderItemLambda;
+import type { SlotProps, SlotPropValue } from "../hooks/useUISlots";
+export declare function isFnFormLambda(value: SlotPropValue): value is RenderItemLambda;
 /**
  * Walk a pattern body replacing every `@<argName>.path` string with the
  * value at `path` of `arg`. Mirrors the compiler's inline substitution
  * for `renderItem` lambda bodies.
  */
-export declare function resolveLambdaBindings(body: unknown, argName: string, arg: EntityRow): unknown;
+export declare function resolveLambdaBindings(body: SlotPropValue, argName: string, arg: EntityRow): SlotPropValue;
 /**
  * Walk a pattern's props (and recursively their nested children),
  * converting every fn-form lambda value into a React render-prop
  * function. Pure on inputs without lambdas: returns the props object
  * unchanged by reference.
  */
-export declare function convertFnFormLambdasInProps(props: Record<string, unknown>): Record<string, unknown>;
+export declare function convertFnFormLambdasInProps(props: SlotProps): SlotProps;

package/dist/runtime/index.cjs

@@ -37882,7 +37882,8 @@ function renderPatternChildren(children, onDismiss, parentId = "root", parentPat
     if (!child || typeof child !== "object") return null;
     const childId = `${parentId}-${index}`;
     const childPath = parentPath === "root" ? `root.children.${index}` : `${parentPath}.children.${index}`;
-    const { type: _childType, props: nestedProps, _id: _childNodeId, children: _childChildren, ...flatProps } = child;
+    const childAsRecord = child;
+    const { type: _childType, props: nestedProps, _id: _childNodeId, children: _childChildren, ...flatProps } = childAsRecord;
     const resolvedProps = nestedProps !== void 0 ? nestedProps : flatProps;
     if (_childChildren !== void 0 && nestedProps === void 0) {
       resolvedProps.children = _childChildren;
@@ -37910,7 +37911,46 @@ function renderPatternChildren(children, onDismiss, parentId = "root", parentPat
   });
 }
 function isPatternConfig(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) && "type" in value && typeof value.type === "string";
+  if (value === null || value === void 0) return false;
+  if (typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+  if (React113__namespace.default.isValidElement(value)) return false;
+  if (value instanceof Date) return false;
+  if (typeof value === "function") return false;
+  const record = value;
+  return "type" in record && typeof record.type === "string";
+}
+function isPlainConfigObject(value) {
+  if (React113__namespace.default.isValidElement(value)) return false;
+  if (value instanceof Date) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function substituteTraitRefsDeep(value, pathKey) {
+  if (typeof value === "string") {
+    const match = TRAIT_BINDING_RE.exec(value);
+    if (match) {
+      const traitName = match[1];
+      return /* @__PURE__ */ jsxRuntime.jsx(TraitFrame, { traitName }, `${pathKey}:${traitName}`);
+    }
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || value === null || value === void 0 || typeof value === "function") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (item, i) => substituteTraitRefsDeep(item, `${pathKey}[${i}]`)
+    );
+  }
+  if (typeof value === "object" && isPlainConfigObject(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = substituteTraitRefsDeep(v, `${pathKey}.${k}`);
+    }
+    return out;
+  }
+  return value;
 }
 function renderPatternProps(props, onDismiss) {
   const rendered = {};
@@ -37918,17 +37958,19 @@ function renderPatternProps(props, onDismiss) {
     if (key === "children") {
       rendered[key] = value;
     } else if (isPatternConfig(value)) {
+      const nestedProps = {};
+      for (const [k, v] of Object.entries(value)) {
+        if (k !== "type") nestedProps[k] = v;
+      }
       const childContent = {
         id: `prop-${key}`,
         pattern: value.type,
-        props: Object.fromEntries(
-          Object.entries(value).filter(([k]) => k !== "type")
-        ),
+        props: nestedProps,
         priority: 0
       };
       rendered[key] = /* @__PURE__ */ jsxRuntime.jsx(SlotContentRenderer, { content: childContent, onDismiss });
     } else {
-      rendered[key] = value;
+      rendered[key] = substituteTraitRefsDeep(value, `prop:${key}`);
     }
   }
   return rendered;
@@ -38271,7 +38313,7 @@ function resolveLambdaBindings(body, argName, arg) {
     let cur = arg;
     for (const seg of path.split(".")) {
       if (cur === null || cur === void 0) return void 0;
-      if (typeof cur !== "object") return void 0;
+      if (typeof cur !== "object" || Array.isArray(cur)) return void 0;
       cur = cur[seg];
     }
     return cur;
@@ -38287,7 +38329,7 @@ function resolveLambdaBindings(body, argName, arg) {
   if (Array.isArray(body)) {
     return body.map((b) => resolveLambdaBindings(b, argName, arg));
   }
-  if (body !== null && typeof body === "object") {
+  if (body !== null && typeof body === "object" && !React113__namespace.default.isValidElement(body) && !(body instanceof Date) && typeof body !== "function") {
     const out = {};
     for (const [k, v] of Object.entries(body)) {
       out[k] = resolveLambdaBindings(v, argName, arg);
@@ -38306,7 +38348,7 @@ function getSlotContentRenderer2() {
 function makeLambdaFn(argName, lambdaBody, callerKey) {
   return (item, index) => {
     const resolvedBody = resolveLambdaBindings(lambdaBody, argName, item);
-    if (resolvedBody === null || typeof resolvedBody !== "object" || Array.isArray(resolvedBody)) {
+    if (resolvedBody === null || typeof resolvedBody !== "object" || Array.isArray(resolvedBody) || typeof resolvedBody === "function" || React113__namespace.default.isValidElement(resolvedBody) || resolvedBody instanceof Date) {
       return null;
     }
     const record = resolvedBody;
@@ -38314,12 +38356,14 @@ function makeLambdaFn(argName, lambdaBody, callerKey) {
       return null;
     }
     const SlotContentRenderer2 = getSlotContentRenderer2();
+    const childProps = {};
+    for (const [k, v] of Object.entries(record)) {
+      if (k !== "type") childProps[k] = v;
+    }
     const childContent = {
       id: `lambda-${callerKey}-${index}`,
       pattern: record.type,
-      props: Object.fromEntries(
-        Object.entries(record).filter(([k]) => k !== "type")
-      ),
+      props: childProps,
       priority: 0
     };
     return React113__namespace.default.createElement(SlotContentRenderer2, { content: childContent });
@@ -38332,15 +38376,16 @@ function convertNode(node, callerKey) {
       const [, argName, body] = node;
       return makeLambdaFn(argName, body, callerKey);
     }
+    const arr = node;
     let anyChanged = false;
-    const mapped = node.map((item, i) => {
+    const mapped = arr.map((item, i) => {
       const next = convertNode(item, `${callerKey}[${i}]`);
       if (next !== item) anyChanged = true;
       return next;
     });
     return anyChanged ? mapped : node;
   }
-  if (typeof node === "object") {
+  if (typeof node === "object" && !React113__namespace.default.isValidElement(node) && !(node instanceof Date)) {
     return convertObjectProps(node);
   }
   return node;
@@ -39531,6 +39576,7 @@ function prepareSchemaForPreview(input) {
 // runtime/OrbPreview.tsx
 init_logger();
 var xOrbitalLog2 = createLogger("almadar:runtime:cross-orbital");
+var navLog = createLogger("almadar:runtime:navigation");
 function normalizeChild(child) {
   if (typeof child === "string") return child;
   if (child === null || typeof child !== "object" || Array.isArray(child)) {
@@ -39606,6 +39652,19 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
   }, [bridge.connected, bridge.sendEvent, orbitalNames, uiSlots, onNavigate, embeddedTraits]);
   const opts = orbitalNames ? { onEventProcessed, navigate: onNavigate, traitConfigsByName, orbitalsByTrait, embeddedTraits } : { navigate: onNavigate, persistence, traitConfigsByName, orbitalsByTrait, embeddedTraits };
   const { sendEvent } = useTraitStateMachine(traits2, uiSlots, opts);
+  const prevTraitNamesRef = React113.useRef("");
+  React113.useEffect(() => {
+    const traitNames = traits2.map((b) => b.trait?.name ?? "").filter(Boolean).sort().join(",");
+    if (prevTraitNamesRef.current && prevTraitNamesRef.current !== traitNames) {
+      navLog.info("page:trait-set-changed", {
+        from: prevTraitNamesRef.current,
+        to: traitNames,
+        action: "clearAll-slots"
+      });
+      uiSlots.clearAll();
+    }
+    prevTraitNamesRef.current = traitNames;
+  }, [traits2, uiSlots]);
   const initSentRef = React113.useRef(false);
   React113.useEffect(() => {
     if (!orbitalNames?.length) {
@@ -39620,6 +39679,10 @@ function TraitInitializer({ traits: traits2, orbitalNames, onNavigate, onLocalFa
     }, 5e3);
     return () => clearTimeout(fallback);
   }, [traits2, orbitalNames, sendEvent, onLocalFallback]);
+  const orbitalsKey = (orbitalNames ?? []).slice().sort().join(",");
+  React113.useEffect(() => {
+    initSentRef.current = false;
+  }, [orbitalsKey]);
   React113.useEffect(() => {
     if (!bridge.connected || !orbitalNames?.length || initSentRef.current) return;
     initSentRef.current = true;
@@ -39860,8 +39923,19 @@ function OrbPreview({
   }, [initialPageName, currentPage]);
   const handleNavigate = React113.useCallback((path) => {
     const match = pages.find(({ page }) => page.path === path);
+    navLog.info("handleNavigate", {
+      path,
+      matched: match?.page.name ?? null,
+      availablePaths: pages.map((p2) => p2.page.path)
+    });
     if (match) {
       setCurrentPage(match.page.name);
+      if (typeof window !== "undefined") {
+        const url = new URL(window.location.href);
+        url.searchParams.set("page", path);
+        window.history.pushState({}, "", url.toString());
+        window.dispatchEvent(new PopStateEvent("popstate"));
+      }
     }
   }, [pages]);
   if (!parseResult.ok) {
@@ -39873,18 +39947,30 @@ function OrbPreview({
   const containerRef = React113.useRef(null);
   React113.useEffect(() => {
     const el = containerRef.current;
-    if (!el || pages.length <= 1) return;
+    if (!el) return;
+    if (pages.length <= 1) {
+      navLog.info("interceptor:skipped", { reason: "single-page schema", pageCount: pages.length });
+      return;
+    }
     const handler = (e) => {
       const anchor = e.target.closest("a");
       if (!anchor) return;
       const href = anchor.getAttribute("href") ?? anchor.getAttribute("to") ?? "";
-      if (!href || href.startsWith("http") || href.startsWith("mailto:") || href.startsWith("#")) return;
+      navLog.info("click:intercepted", {
+        href,
+        anchorText: anchor.textContent?.trim().slice(0, 40)
+      });
+      if (!href || href.startsWith("http") || href.startsWith("mailto:") || href.startsWith("#")) {
+        navLog.info("click:skipped", { href, reason: "external/empty/hash" });
+        return;
+      }
       e.preventDefault();
       e.stopPropagation();
       e.stopImmediatePropagation();
       handleNavigate(href);
     };
     el.addEventListener("click", handler, true);
+    navLog.info("interceptor:installed", { pageCount: pages.length, paths: pages.map((p2) => p2.page.path) });
     return () => el.removeEventListener("click", handler, true);
   }, [pages, handleNavigate]);
   return /* @__PURE__ */ jsxRuntime.jsxs(