@almadar/ui 6.6.0 → 6.8.0

package/dist/runtime/index.d.ts

@@ -9,6 +9,7 @@ import { a as EntityBindingSource, h as ServerBridgeTransport } from '../EntityB
 export { b as EntitySchemaContextValue, c as EntitySchemaProvider, d as EntitySchemaProviderProps, e as ServerBridgeContextValue, f as ServerBridgeProvider, i as ServerClientEffect, T as TraitContext, k as TraitContextValue, l as TraitInstance, m as TraitProvider, n as TraitProviderProps, o as useEntitySchema, p as useEntitySchemaOptional, q as useServerBridge, r as useTrait, s as useTraitContext } from '../EntityBindingContext-Bn3ePJQC.js';
 export { PERF_NAMESPACE, PerfEntry, PreparedPreviewSchema, adjustSchemaForMockData, buildMockData, clearPerf, perfEnd, perfStart, perfTime, prepareSchemaForPreview, wrapCallbackForEvent } from '@almadar/runtime/ui';
 import React__default, { ReactNode } from 'react';
+export { S as SlotHostManifest, a as SlotHostRegion, b as assertUniqueSlotsPerHost } from '../slot-host-Czc2JAxo.js';
 export { p as profilerOnRender, u as usePerfBuffer } from '../perf-DaVdsbU0.js';
 import '../event-bus-types-Bl78kokd.js';
 import '../useUISlots-GNwGLlW2.js';
@@ -326,6 +327,34 @@ declare function BrowserPlayground({ schema, mode, initialPagePath, height, clas
  * preview has (in-memory persist, mock services); `deny` is an opt-in
  * host policy, never a default sandbox.
  *
+ * OUTBOUND = the runtime's internal event bus, not the direct dispatch
+ * response. `response.emittedEvents` (mock mode) reflects only the effects
+ * of the trait `dispatch()` DIRECTLY targeted — a sibling trait that reacts
+ * through the runtime's own cascade (`setupEventListeners`, a SEPARATE
+ * `processOrbitalEvent` call whose response is discarded) never shows up
+ * there, so its emits never reached the ambient bus (verified 2026-09-04:
+ * vim-mode's `Shell` relays `PLUGIN_ENABLED` -> `VimStudioBridge`'s
+ * `ENABLED` arm emits `STATUS` + 2x `REGISTER_COMMAND`, none of which
+ * reached the studio's status bar/palette). Fix: for `mode: 'mock'`, one
+ * `runtime.getEventBus().onAny(...)` subscription per plugin (mounted
+ * alongside the runtime, not per-dispatch) is the ONLY outbound path — it
+ * sees every emit, direct or cascaded, since every `emit` effect passes
+ * through that same bus. `mode: 'server'` has no local bus to subscribe to
+ * (the runtime lives on the remote transport), so it keeps reading
+ * `response.emittedEvents` for outbound — same single-hop-only limitation
+ * this fix removes for mock mode, unaddressed here (no `mode: 'server'`
+ * consumer exists yet; see `docs/Almadar_UI_Gaps.md`).
+ *
+ * RELAY RULE: the plugin's `inbound[]` is its host→plugin vocabulary — one
+ * `UI:<busEvent>` bus event per row, dispatching `trigger` at
+ * `orbital`/`trait`. Anything a plugin emits under one of those SAME
+ * busEvent names (or under an inbound `trigger` name) is a relay for its
+ * own siblings' `listens {}` (the runtime's internal event bus already
+ * carries that fan-out), never a fresh request back to the host, and must
+ * NEVER be re-broadcast — doing so re-fires the very `UI:<busEvent>`
+ * listener that produced it, a synchronous self-feeding loop (verified
+ * 2026-09-04, see `docs/Almadar_UI_Gaps.md`).
+ *
  * @packageDocumentation
  */
 

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,30 @@ function PluginRuntimeMount({
     () => new Set(plugin.schema.orbitals.map((o) => o.name)),
     [plugin.schema]
   );
+  const inboundBusEvents = useMemo(
+    () => new Set(plugin.inbound.map((row) => row.busEvent)),
+    [plugin.inbound]
+  );
+  const inboundTriggerNames = useMemo(
+    () => new Set(plugin.inbound.map((row) => row.trigger)),
+    [plugin.inbound]
+  );
+  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 +54238,39 @@ 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]);
+  useEffect(() => {
+    if (!mockRuntime) return;
+    const rebroadcast = /* @__PURE__ */ new WeakSet();
+    const unsub = mockRuntime.getEventBus().onAny((event) => {
+      if (rebroadcast.has(event)) return;
+      if (inboundBusEvents.has(event.type) || inboundTriggerNames.has(event.type)) return;
+      const sourceOrbital = event.source?.orbital;
+      if (sourceOrbital === void 0 || !ownOrbitals.has(sourceOrbital)) return;
+      rebroadcast.add(event);
+      bus.emit(`UI:${event.type}`, event.payload, event.source);
+    });
+    return () => {
+      unsub();
+    };
+  }, [mockRuntime, bus, ownOrbitals, inboundBusEvents, inboundTriggerNames]);
   const dispatch = useCallback(
     async (row, payload) => {
       await registrationReady;
@@ -54206,11 +54289,14 @@ function PluginRuntimeMount({
       if (!response.success) {
         onError(plugin.id, response.error ?? `${plugin.id}: ${row.trigger} failed`);
       }
-      for (const entry of response.emittedEvents ?? []) {
-        if (entry.event === row.trigger) continue;
-        const sourceOrbital = entry.source?.orbital;
-        if (sourceOrbital !== void 0 && ownOrbitals.has(sourceOrbital)) {
-          bus.emit(`UI:${entry.event}`, entry.payload, entry.source);
+      if (!mockRuntime) {
+        for (const entry of response.emittedEvents ?? []) {
+          if (entry.event === row.trigger) continue;
+          if (inboundBusEvents.has(entry.event)) continue;
+          const sourceOrbital = entry.source?.orbital;
+          if (sourceOrbital !== void 0 && ownOrbitals.has(sourceOrbital)) {
+            bus.emit(`UI:${entry.event}`, entry.payload, entry.source);
+          }
         }
       }
       const states = [];
@@ -54220,7 +54306,7 @@ function PluginRuntimeMount({
       }
       onDispatched(plugin.id, row.trigger, states);
     },
-    [registrationReady, mockRuntime, mode, transport, plugin, bus, ownOrbitals, onError, onTransition, onDispatched]
+    [registrationReady, mockRuntime, mode, transport, plugin, bus, ownOrbitals, inboundBusEvents, onError, onTransition, onDispatched]
   );
   useEffect(() => {
     const unsubs = plugin.inbound.map(
@@ -54304,7 +54390,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.8.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.205.0",
     "@almadar/syntax": "^1.16.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",