@almadar/ui 6.6.0 → 6.7.0

package/dist/runtime/index.js

@@ -50993,7 +50993,9 @@ function UISlotComponentInner({
   className,
   children,
   pattern,
-  sourceTrait
+  sourceTrait,
+  fallback,
+  mode = "replace"
 }) {
   const { slots, clear } = useUISlots();
   const eventBus = useEventBus();
@@ -51045,12 +51047,26 @@ function UISlotComponentInner({
     );
   }
   if (!content) {
+    if (fallback !== void 0) {
+      return /* @__PURE__ */ jsx(
+        Box,
+        {
+          id: `slot-${slot}`,
+          className: cn("ui-slot", `ui-slot-${slot}`, className),
+          "data-testid": `ui-slot-${slot}`,
+          "data-slot-mode": "fallback",
+          children: fallback
+        }
+      );
+    }
     if (!portal) {
       return /* @__PURE__ */ jsx(
         Box,
         {
           id: `slot-${slot}`,
-          className: cn("ui-slot", `ui-slot-${slot}`, className)
+          className: cn("ui-slot", `ui-slot-${slot}`, className),
+          "data-testid": `ui-slot-${slot}`,
+          "data-slot-mode": "empty"
         }
       );
     }
@@ -51067,29 +51083,51 @@ function UISlotComponentInner({
     clear(slot);
   };
   if (portal) {
-    if (contained) {
-      return renderContainedPortal(t, slot, content, handleDismiss);
-    }
-    return /* @__PURE__ */ jsx(
-      SlotPortal,
+    const inlineFallback = mode === "append" && fallback !== void 0 ? /* @__PURE__ */ jsx(
+      Box,
       {
-        slot,
-        content,
-        position,
-        onDismiss: handleDismiss
+        id: `slot-${slot}-fallback`,
+        className: cn("ui-slot", `ui-slot-${slot}-fallback`, className),
+        "data-testid": `ui-slot-${slot}-fallback`,
+        "data-slot-mode": "append",
+        children: fallback
       }
-    );
+    ) : null;
+    if (contained) {
+      return /* @__PURE__ */ jsxs(Fragment, { children: [
+        inlineFallback,
+        renderContainedPortal(t, slot, content, handleDismiss)
+      ] });
+    }
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      inlineFallback,
+      /* @__PURE__ */ jsx(
+        SlotPortal,
+        {
+          slot,
+          content,
+          position,
+          onDismiss: handleDismiss
+        }
+      )
+    ] });
   }
   const slotContent = /* @__PURE__ */ jsx(SlotContentRenderer, { content, onDismiss: handleDismiss });
   const wrappedContent = suspenseConfig.enabled ? /* @__PURE__ */ jsx(ErrorBoundary, { children: /* @__PURE__ */ jsx(Suspense, { fallback: getSlotFallback(slot, suspenseConfig), children: slotContent }) }) : /* @__PURE__ */ jsx(ErrorBoundary, { children: slotContent });
-  return /* @__PURE__ */ jsx(
+  const showFallback = mode === "append" && fallback !== void 0;
+  return /* @__PURE__ */ jsxs(
     Box,
     {
       id: `slot-${slot}`,
       className: cn("ui-slot", `ui-slot-${slot}`, className),
       "data-pattern": content.pattern,
       "data-source-trait": content.sourceTrait,
-      children: /* @__PURE__ */ jsx(MaybeTraitScope, { sourceTrait: content.sourceTrait, children: wrappedContent })
+      "data-testid": `ui-slot-${slot}`,
+      "data-slot-mode": showFallback ? "append" : "content",
+      children: [
+        showFallback ? fallback : null,
+        /* @__PURE__ */ jsx(MaybeTraitScope, { sourceTrait: content.sourceTrait, children: wrappedContent })
+      ]
     }
   );
 }
@@ -54169,17 +54207,22 @@ function PluginRuntimeMount({
     () => new Set(plugin.schema.orbitals.map((o) => o.name)),
     [plugin.schema]
   );
+  const snapshotAllStates = useCallback(() => {
+    const states = [];
+    if (!mockRuntime) return states;
+    for (const orbital of plugin.schema.orbitals) {
+      for (const traitName of traitNamesOf(orbital)) {
+        const raw = mockRuntime.getState(orbital.name, traitName);
+        if (isTraitState(raw)) states.push([orbital.name, traitName, raw]);
+      }
+    }
+    return states;
+  }, [mockRuntime, plugin.schema]);
   useEffect(() => {
     let cancelled = false;
     void registrationReady.then(() => {
       if (cancelled || !mockRuntime) return;
-      const states = [];
-      for (const orbital of plugin.schema.orbitals) {
-        for (const traitName of traitNamesOf(orbital)) {
-          const raw = mockRuntime.getState(orbital.name, traitName);
-          if (isTraitState(raw)) states.push([orbital.name, traitName, raw]);
-        }
-      }
+      const states = snapshotAllStates();
       if (states.length > 0) onDispatched(plugin.id, null, states);
     }).catch((err) => {
       if (!cancelled) onError(plugin.id, err instanceof Error ? err.message : String(err));
@@ -54187,7 +54230,24 @@ function PluginRuntimeMount({
     return () => {
       cancelled = true;
     };
-  }, [registrationReady, mockRuntime, plugin, onDispatched, onError]);
+  }, [registrationReady, mockRuntime, plugin, onDispatched, onError, snapshotAllStates]);
+  useEffect(() => {
+    if (!mockRuntime) return;
+    let timer = null;
+    const scheduleResync = () => {
+      if (timer !== null) return;
+      timer = setTimeout(() => {
+        timer = null;
+        const states = snapshotAllStates();
+        if (states.length > 0) onDispatched(plugin.id, null, states);
+      }, 0);
+    };
+    const unsub = mockRuntime.getEventBus().onAny(scheduleResync);
+    return () => {
+      unsub();
+      if (timer !== null) clearTimeout(timer);
+    };
+  }, [mockRuntime, plugin.id, onDispatched, snapshotAllStates]);
   const dispatch = useCallback(
     async (row, payload) => {
       await registrationReady;
@@ -54304,7 +54364,21 @@ function OrbitalPluginHost({
   ] });
 }
 
+// types/slot-host.ts
+function assertUniqueSlotsPerHost(manifest) {
+  const seenBySlot = /* @__PURE__ */ new Map();
+  for (const [regionId, region] of Object.entries(manifest.regions)) {
+    const existingRegionId = seenBySlot.get(region.slot);
+    if (existingRegionId !== void 0) {
+      throw new Error(
+        `assertUniqueSlotsPerHost: regions "${existingRegionId}" and "${regionId}" both bind slot "${region.slot}" \u2014 a slot may be mounted by only one region per host.`
+      );
+    }
+    seenBySlot.set(region.slot, regionId);
+  }
+}
+
 // runtime/index.ts
 init_perf();
 
-export { BrowserPlayground, OrbPreview, OrbitalPluginHost, clearSchemaCache, createClientEffectHandlers, profilerOnRender, useDeclaredCaptureTable, useOrbitalPluginHost, usePerfBuffer, useResolvedSchema, useTraitStateMachine };
+export { BrowserPlayground, OrbPreview, OrbitalPluginHost, assertUniqueSlotsPerHost, clearSchemaCache, createClientEffectHandlers, profilerOnRender, useDeclaredCaptureTable, useOrbitalPluginHost, usePerfBuffer, useResolvedSchema, useTraitStateMachine };

package/dist/slot-host-Czc2JAxo.d.cts

@@ -0,0 +1,47 @@
+import { UISlot } from '@almadar/core';
+
+/**
+ * Slot-host manifest types (Studio V4 §14, Part I1/I2).
+ *
+ * A "slot-host" is any shell that lays out named regions and mounts each
+ * one through `UISlotComponent` — e.g. a persona workspace declaring
+ * `sidebar`/`main`/`drawer`/... A manifest is the declarative region → slot
+ * binding for such a host: which compiler `UISlot` each region mounts, and
+ * whether the host's own stock content is replaced by slot content or the
+ * two are shown together (`UISlotComponent`'s `mode` prop). Substrate
+ * (lives in `@almadar/ui`, re-exported by `@almadar/sdk`) so any host — the
+ * studio's three persona shells or an embedding app — describes its
+ * regions the same way.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * One host region's binding to a compiler slot. Mirrors `UISlotComponent`'s
+ * `mode` prop exactly — a manifest is just that prop's value, keyed by
+ * region, declared as data instead of scattered across JSX call sites.
+ */
+interface SlotHostRegion {
+    slot: UISlot;
+    mode: "replace" | "append";
+}
+/**
+ * A host's full region map, keyed by the host's own region ids (e.g. a
+ * persona shell's `activityBar`/`sidebar`/`main`/...). `RegionId` is left
+ * generic so each host supplies its own literal union.
+ */
+interface SlotHostManifest<RegionId extends string = string> {
+    regions: Record<RegionId, SlotHostRegion>;
+}
+/**
+ * Guards the invariant a slot-host manifest depends on: each `UISlot` may
+ * be mounted by at most one region. Two regions sharing a slot would mount
+ * `UISlotComponent` twice for the same slot — the second mount clears/reads
+ * the same context entry the first one owns, so one of the two regions
+ * silently loses its content (or, for a portal slot, double-portals it).
+ * Throws naming the two offending regions so the host can find the
+ * conflict without re-deriving it from the manifest.
+ */
+declare function assertUniqueSlotsPerHost<RegionId extends string>(manifest: SlotHostManifest<RegionId>): void;
+
+export { type SlotHostManifest as S, type SlotHostRegion as a, assertUniqueSlotsPerHost as b };

package/dist/slot-host-Czc2JAxo.d.ts

@@ -0,0 +1,47 @@
+import { UISlot } from '@almadar/core';
+
+/**
+ * Slot-host manifest types (Studio V4 §14, Part I1/I2).
+ *
+ * A "slot-host" is any shell that lays out named regions and mounts each
+ * one through `UISlotComponent` — e.g. a persona workspace declaring
+ * `sidebar`/`main`/`drawer`/... A manifest is the declarative region → slot
+ * binding for such a host: which compiler `UISlot` each region mounts, and
+ * whether the host's own stock content is replaced by slot content or the
+ * two are shown together (`UISlotComponent`'s `mode` prop). Substrate
+ * (lives in `@almadar/ui`, re-exported by `@almadar/sdk`) so any host — the
+ * studio's three persona shells or an embedding app — describes its
+ * regions the same way.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * One host region's binding to a compiler slot. Mirrors `UISlotComponent`'s
+ * `mode` prop exactly — a manifest is just that prop's value, keyed by
+ * region, declared as data instead of scattered across JSX call sites.
+ */
+interface SlotHostRegion {
+    slot: UISlot;
+    mode: "replace" | "append";
+}
+/**
+ * A host's full region map, keyed by the host's own region ids (e.g. a
+ * persona shell's `activityBar`/`sidebar`/`main`/...). `RegionId` is left
+ * generic so each host supplies its own literal union.
+ */
+interface SlotHostManifest<RegionId extends string = string> {
+    regions: Record<RegionId, SlotHostRegion>;
+}
+/**
+ * Guards the invariant a slot-host manifest depends on: each `UISlot` may
+ * be mounted by at most one region. Two regions sharing a slot would mount
+ * `UISlotComponent` twice for the same slot — the second mount clears/reads
+ * the same context entry the first one owns, so one of the two regions
+ * silently loses its content (or, for a portal slot, double-portals it).
+ * Throws naming the two offending regions so the host can find the
+ * conflict without re-deriving it from the manifest.
+ */
+declare function assertUniqueSlotsPerHost<RegionId extends string>(manifest: SlotHostManifest<RegionId>): void;
+
+export { type SlotHostManifest as S, type SlotHostRegion as a, assertUniqueSlotsPerHost as b };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "6.6.0",
+  "version": "6.7.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "sideEffects": [
@@ -118,11 +118,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": "^10.83.0",
+    "@almadar/core": "^10.84.0",
     "@almadar/evaluator": "^2.44.0",
     "@almadar/logger": "^1.12.0",
-    "@almadar/runtime": "^6.70.0",
-    "@almadar/std": "^16.203.0",
+    "@almadar/runtime": "^6.71.0",
+    "@almadar/std": "^16.204.0",
     "@almadar/syntax": "^1.16.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",