@almadar/ui 6.6.0 → 6.8.0

package/dist/components/index.js

@@ -52614,7 +52614,9 @@ function UISlotComponentInner({
   className,
   children,
   pattern,
-  sourceTrait
+  sourceTrait,
+  fallback,
+  mode = "replace"
 }) {
   const { slots, clear } = useUISlots();
   const eventBus = useEventBus();
@@ -52666,12 +52668,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"
         }
       );
     }
@@ -52688,29 +52704,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 })
+      ]
     }
   );
 }
@@ -55918,4 +55956,18 @@ function useGitHubBranches(owner, repo, enabled = true) {
   });
 }
 
-export { ALL_PRESETS, ALMADAR_DND_MIME, AR_BOOK_FIELDS, AboutPageTemplate, Accordion, Card2 as ActionCard, ActionPalette, ActionTile, ActivationBlock, Alert, AlgoGraphCanvas, AlgorithmCanvas, AnimatedCounter, AnimatedGraphic, AnimatedReveal, ArticleSection, Aside, AssetPicker, AtlasImage, AtlasPanel, AuthLayout, Avatar, Badge, BehaviorView, BiologyCanvas, BloomQuizBlock, BookChapterView, BookCoverPage, BookNavBar, BookTableOfContents, BookViewer, Box, BranchingLogicBuilder, Breadcrumb, Button, ButtonGroup, CTABanner, CalendarGrid, Canvas, Canvas2D, Card, CardBody, CardContent, CardFooter, CardGrid, CardHeader, CardTitle, Carousel, CaseStudyCard, CaseStudyOrganism, Center, Chart, ChartLegend, ChatBar, Checkbox, ChemistryCanvas, ChoiceButton, Coachmark, CodeBlock, CodeRunnerPanel, CollapsibleSection, CommandPalette, CommunityLinks, ConditionalWrapper, ConfettiEffect, ConfirmDialog, ConnectionBlock, Container, ContentRenderer, ContentSection, ControlButton, ControlGrid, CounterTemplate, DEFAULT_LIKERT_OPTIONS, DEFAULT_MATRIX_COLUMNS, DEFAULT_SLOTS, DIAMOND_TOP_Y, DashboardGrid, DashboardLayout, DataGrid, DataList, DataTable, DateRangePicker, DateRangeSelector, DayCell, DetailPanel, Dialog, DialogueBubble, Divider, DocBreadcrumb, DocPagination, DocSearch, DocSidebar, DocTOC, DockLayout, DocumentDetails, DocumentPanel, DocumentViewer, StateMachineView as DomStateMachineVisualizer, Drawer, DrawerSlot, ELEMENT_SELECTED_EVENT, EdgeDecoration, EditorCheckbox, EditorSelect, EditorSlider, EditorTextInput, EditorToolbar, EmojiPicker, EmptyState, EntityDisplayEvents, ErrorBoundary, ErrorState, FEATURE_COLORS, FEATURE_TYPES, FLOOR_HEIGHT, FeatureCard, FeatureDetailPageTemplate, FeatureGrid, FeatureGridOrganism, FileTree, FilterGroup, FilterPill, Flex, FlipCard, FlipContainer, FloatingActionButton, FloatingToolbar, Form, FormActions, FormField, FormLayout, FormSection, FormSectionHeader, FxOverlay, GameAudioCue, GameAudioToggle, GameHud, GameIcon, GameMenu, GameShell, GenericAppTemplate, GeometricPattern, GradientDivider, GraphCanvas, GraphView, Grid, GridPicker, HStack, Header, HealthBar, HeroOrganism, HeroSection, I18nProvider, IDENTITY_BOOK_FIELDS, Icon, IconPicker, ImportPreviewTree, ImportProgress, ImportSourcePicker, InfiniteScrollSentinel, Input, InputGroup, InstallBox, JazariStateMachine, JsonTreeEditor, Label, LandingPageTemplate, LawReferenceTooltip, LearningCanvas, LearningScene3D, Lightbox, LikertScale, LineChart2 as LineChart, List3 as List, LoadingState, MapView, MarkdownContent, MarketingFooter, MarketingStatCard, MasterDetail, MasterDetailLayout, MathCanvas, MatrixQuestion, MediaGallery, Menu, Meter, Modal, ModalSlot, ModuleCard, Navigation, NodeSlotEditor, NotifyListener, NumberStepper, OnboardingSpotlight, OptionConstraintGroup, StateMachineView as OrbitalStateMachineView, OrbitalVisualization, Overlay, PageHeader, PageTransition, Pagination, PatternTile, PhysicsCanvas, Popover, PositionedCanvas, Presence, PricingCard, PricingGrid, PricingOrganism, PricingPageTemplate, ProgressBar, ProgressDots, PropertyInspector, PullQuote, PullToRefresh, QrScanner, QuizBlock, Radio, RangeSlider, ReflectionBlock, RelationSelect, RepeatableFormSection, ReplyTree, RichTextEditor, RuntimeDebugger, SHEET_COLUMNS, SPRITE_SHEET_LAYOUT, ScaledDiagram, ScoreDisplay, SearchInput, Section, SectionHeader, SegmentRenderer, Select, SequenceBar, ServiceCatalog, SharedEntityStoreContext, ShowcaseCard, ShowcaseOrganism, SidePanel, Sidebar, SignaturePad, SimpleGrid, Skeleton, SlotContentRenderer, SocialProof, SortableList, Spacer, Sparkline, Spinner, Split, SplitPane, SplitSection, Stack, StarRating, StatBadge, StatCard, StatDisplay, StateGraph, StateJsonView, StateMachineView, StateNode2 as StateNode, StatsGrid, StatsOrganism, StatusBar, StatusDot, StepFlow, StepFlowOrganism, SubagentTracePanel, SvgBranch, SvgConnection, SvgFlow, SvgGrid, SvgLobe, SvgMesh, SvgMorph, SvgNode, SvgPulse, SvgRing, SvgShield, SvgStack, SwipeableRow, Switch, TERRAIN_COLORS, TILE_HEIGHT, TILE_WIDTH, TabbedContainer, TableView, Tabs, TagCloud, TagInput, TeamCard, TeamOrganism, TerrainPalette, TextHighlight, Textarea, ThemeToggle, TimeSlotCell, Timeline, TimerDisplay, Toast, ToastSlot, Tooltip, TraitFrame, TraitSlot, TraitStateViewer, TransitionArrow, TrendIndicator, TypewriterText, Typography, UISlotComponent, UISlotRenderer, UploadDropZone, VStack, VersionDiff, ViolationAlert, VoteStack, WizardContainer, WizardNavigation, WizardProgress, arrowBetween, billboardLabel, boardEntity, bool, calculateAttackTargets, calculateValidMoves, cn, createInitialGameState, createSharedEntityStore, createTranslate, createUnitAnimationState, cylinderBetween, dispatchCommandPaletteCommand, get3DClickPayload, getCurrentFrame, getTileDimensions, inferDirection, isoToScreen, makeAsset, makeAssetMap, mapBookData, meshSphere, num, objAvailableActions, objAvailableEvents, objCurrentState, objIcon, objId, objMaxRules, objName, objRules, objStates, parseEditFocus, parseLessonSegments, parseMarkdownWithCodeBlocks, parseQueryBinding, pendulum, projectileMotion, registerCodeLanguageLoader, renderPatternValue, resolveFieldMap, resolveFrame, resolveSheetDirection, rows, runTickFrame, sanitizeRichHtml, screenToIso, springOscillator, str, tickAnimationState, toCodeLanguage, transitionAnimation, unitHealth, unitPosition, unitTeam, useAgentChat, useAnchorRect, useAtlasSliceDataUrl, useAuthContext, useCamera, useCanvasGestures, useCompile, useConnectGitHub, useDeepAgentGeneration, useDisconnectGitHub, useDragReorder, useDraggable, useDropZone, useEmitEvent, useEventBus, useEventListener, useExtensions, useFileEditor, useFileSystem, useGameAudio, useGitHubBranches, useGitHubRepo, useGitHubRepos, useGitHubStatus, useImageCache, useInfiniteScroll, useKeyboardRouter, useLongPress, useMediaQuery, useOrbitalHistory, usePresence, usePreview, usePullToRefresh, useQuerySingleton, useRenderInterpolation, useSharedEntitySnapshot, useSharedEntityStore, useSharedEntityStoreContext, useSwipeGesture, useTapReveal, useTraitListens, useTranslate117 as useTranslate, useUIEvents, useUISlotManager, useUnitSpriteAtlas, useValidation, vec2 };
+// 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);
+  }
+}
+
+export { ALL_PRESETS, ALMADAR_DND_MIME, AR_BOOK_FIELDS, AboutPageTemplate, Accordion, Card2 as ActionCard, ActionPalette, ActionTile, ActivationBlock, Alert, AlgoGraphCanvas, AlgorithmCanvas, AnimatedCounter, AnimatedGraphic, AnimatedReveal, ArticleSection, Aside, AssetPicker, AtlasImage, AtlasPanel, AuthLayout, Avatar, Badge, BehaviorView, BiologyCanvas, BloomQuizBlock, BookChapterView, BookCoverPage, BookNavBar, BookTableOfContents, BookViewer, Box, BranchingLogicBuilder, Breadcrumb, Button, ButtonGroup, CTABanner, CalendarGrid, Canvas, Canvas2D, Card, CardBody, CardContent, CardFooter, CardGrid, CardHeader, CardTitle, Carousel, CaseStudyCard, CaseStudyOrganism, Center, Chart, ChartLegend, ChatBar, Checkbox, ChemistryCanvas, ChoiceButton, Coachmark, CodeBlock, CodeRunnerPanel, CollapsibleSection, CommandPalette, CommunityLinks, ConditionalWrapper, ConfettiEffect, ConfirmDialog, ConnectionBlock, Container, ContentRenderer, ContentSection, ControlButton, ControlGrid, CounterTemplate, DEFAULT_LIKERT_OPTIONS, DEFAULT_MATRIX_COLUMNS, DEFAULT_SLOTS, DIAMOND_TOP_Y, DashboardGrid, DashboardLayout, DataGrid, DataList, DataTable, DateRangePicker, DateRangeSelector, DayCell, DetailPanel, Dialog, DialogueBubble, Divider, DocBreadcrumb, DocPagination, DocSearch, DocSidebar, DocTOC, DockLayout, DocumentDetails, DocumentPanel, DocumentViewer, StateMachineView as DomStateMachineVisualizer, Drawer, DrawerSlot, ELEMENT_SELECTED_EVENT, EdgeDecoration, EditorCheckbox, EditorSelect, EditorSlider, EditorTextInput, EditorToolbar, EmojiPicker, EmptyState, EntityDisplayEvents, ErrorBoundary, ErrorState, FEATURE_COLORS, FEATURE_TYPES, FLOOR_HEIGHT, FeatureCard, FeatureDetailPageTemplate, FeatureGrid, FeatureGridOrganism, FileTree, FilterGroup, FilterPill, Flex, FlipCard, FlipContainer, FloatingActionButton, FloatingToolbar, Form, FormActions, FormField, FormLayout, FormSection, FormSectionHeader, FxOverlay, GameAudioCue, GameAudioToggle, GameHud, GameIcon, GameMenu, GameShell, GenericAppTemplate, GeometricPattern, GradientDivider, GraphCanvas, GraphView, Grid, GridPicker, HStack, Header, HealthBar, HeroOrganism, HeroSection, I18nProvider, IDENTITY_BOOK_FIELDS, Icon, IconPicker, ImportPreviewTree, ImportProgress, ImportSourcePicker, InfiniteScrollSentinel, Input, InputGroup, InstallBox, JazariStateMachine, JsonTreeEditor, Label, LandingPageTemplate, LawReferenceTooltip, LearningCanvas, LearningScene3D, Lightbox, LikertScale, LineChart2 as LineChart, List3 as List, LoadingState, MapView, MarkdownContent, MarketingFooter, MarketingStatCard, MasterDetail, MasterDetailLayout, MathCanvas, MatrixQuestion, MediaGallery, Menu, Meter, Modal, ModalSlot, ModuleCard, Navigation, NodeSlotEditor, NotifyListener, NumberStepper, OnboardingSpotlight, OptionConstraintGroup, StateMachineView as OrbitalStateMachineView, OrbitalVisualization, Overlay, PageHeader, PageTransition, Pagination, PatternTile, PhysicsCanvas, Popover, PositionedCanvas, Presence, PricingCard, PricingGrid, PricingOrganism, PricingPageTemplate, ProgressBar, ProgressDots, PropertyInspector, PullQuote, PullToRefresh, QrScanner, QuizBlock, Radio, RangeSlider, ReflectionBlock, RelationSelect, RepeatableFormSection, ReplyTree, RichTextEditor, RuntimeDebugger, SHEET_COLUMNS, SPRITE_SHEET_LAYOUT, ScaledDiagram, ScoreDisplay, SearchInput, Section, SectionHeader, SegmentRenderer, Select, SequenceBar, ServiceCatalog, SharedEntityStoreContext, ShowcaseCard, ShowcaseOrganism, SidePanel, Sidebar, SignaturePad, SimpleGrid, Skeleton, SlotContentRenderer, SocialProof, SortableList, Spacer, Sparkline, Spinner, Split, SplitPane, SplitSection, Stack, StarRating, StatBadge, StatCard, StatDisplay, StateGraph, StateJsonView, StateMachineView, StateNode2 as StateNode, StatsGrid, StatsOrganism, StatusBar, StatusDot, StepFlow, StepFlowOrganism, SubagentTracePanel, SvgBranch, SvgConnection, SvgFlow, SvgGrid, SvgLobe, SvgMesh, SvgMorph, SvgNode, SvgPulse, SvgRing, SvgShield, SvgStack, SwipeableRow, Switch, TERRAIN_COLORS, TILE_HEIGHT, TILE_WIDTH, TabbedContainer, TableView, Tabs, TagCloud, TagInput, TeamCard, TeamOrganism, TerrainPalette, TextHighlight, Textarea, ThemeToggle, TimeSlotCell, Timeline, TimerDisplay, Toast, ToastSlot, Tooltip, TraitFrame, TraitSlot, TraitStateViewer, TransitionArrow, TrendIndicator, TypewriterText, Typography, UISlotComponent, UISlotRenderer, UploadDropZone, VStack, VersionDiff, ViolationAlert, VoteStack, WizardContainer, WizardNavigation, WizardProgress, arrowBetween, assertUniqueSlotsPerHost, billboardLabel, boardEntity, bool, calculateAttackTargets, calculateValidMoves, cn, createInitialGameState, createSharedEntityStore, createTranslate, createUnitAnimationState, cylinderBetween, dispatchCommandPaletteCommand, get3DClickPayload, getCurrentFrame, getTileDimensions, inferDirection, isoToScreen, makeAsset, makeAssetMap, mapBookData, meshSphere, num, objAvailableActions, objAvailableEvents, objCurrentState, objIcon, objId, objMaxRules, objName, objRules, objStates, parseEditFocus, parseLessonSegments, parseMarkdownWithCodeBlocks, parseQueryBinding, pendulum, projectileMotion, registerCodeLanguageLoader, renderPatternValue, resolveFieldMap, resolveFrame, resolveSheetDirection, rows, runTickFrame, sanitizeRichHtml, screenToIso, springOscillator, str, tickAnimationState, toCodeLanguage, transitionAnimation, unitHealth, unitPosition, unitTeam, useAgentChat, useAnchorRect, useAtlasSliceDataUrl, useAuthContext, useCamera, useCanvasGestures, useCompile, useConnectGitHub, useDeepAgentGeneration, useDisconnectGitHub, useDragReorder, useDraggable, useDropZone, useEmitEvent, useEventBus, useEventListener, useExtensions, useFileEditor, useFileSystem, useGameAudio, useGitHubBranches, useGitHubRepo, useGitHubRepos, useGitHubStatus, useImageCache, useInfiniteScroll, useKeyboardRouter, useLongPress, useMediaQuery, useOrbitalHistory, usePresence, usePreview, usePullToRefresh, useQuerySingleton, useRenderInterpolation, useSharedEntitySnapshot, useSharedEntityStore, useSharedEntityStoreContext, useSwipeGesture, useTapReveal, useTraitListens, useTranslate117 as useTranslate, useUIEvents, useUISlotManager, useUnitSpriteAtlas, useValidation, vec2 };

package/dist/providers/index.cjs

@@ -51418,7 +51418,9 @@ function UISlotComponentInner({
   className,
   children,
   pattern,
-  sourceTrait
+  sourceTrait,
+  fallback,
+  mode = "replace"
 }) {
   const { slots, clear } = context.useUISlots();
   const eventBus = useEventBus();
@@ -51470,12 +51472,26 @@ function UISlotComponentInner({
     );
   }
   if (!content) {
+    if (fallback !== void 0) {
+      return /* @__PURE__ */ jsxRuntime.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__ */ jsxRuntime.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"
         }
       );
     }
@@ -51492,29 +51508,51 @@ function UISlotComponentInner({
     clear(slot);
   };
   if (portal) {
-    if (contained) {
-      return renderContainedPortal(t, slot, content, handleDismiss);
-    }
-    return /* @__PURE__ */ jsxRuntime.jsx(
-      SlotPortal,
+    const inlineFallback = mode === "append" && fallback !== void 0 ? /* @__PURE__ */ jsxRuntime.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__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+        inlineFallback,
+        renderContainedPortal(t, slot, content, handleDismiss)
+      ] });
+    }
+    return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      inlineFallback,
+      /* @__PURE__ */ jsxRuntime.jsx(
+        SlotPortal,
+        {
+          slot,
+          content,
+          position,
+          onDismiss: handleDismiss
+        }
+      )
+    ] });
   }
   const slotContent = /* @__PURE__ */ jsxRuntime.jsx(SlotContentRenderer, { content, onDismiss: handleDismiss });
   const wrappedContent = suspenseConfig.enabled ? /* @__PURE__ */ jsxRuntime.jsx(ErrorBoundary, { children: /* @__PURE__ */ jsxRuntime.jsx(React89.Suspense, { fallback: getSlotFallback(slot, suspenseConfig), children: slotContent }) }) : /* @__PURE__ */ jsxRuntime.jsx(ErrorBoundary, { children: slotContent });
-  return /* @__PURE__ */ jsxRuntime.jsx(
+  const showFallback = mode === "append" && fallback !== void 0;
+  return /* @__PURE__ */ jsxRuntime.jsxs(
     Box,
     {
       id: `slot-${slot}`,
       className: cn("ui-slot", `ui-slot-${slot}`, className),
       "data-pattern": content.pattern,
       "data-source-trait": content.sourceTrait,
-      children: /* @__PURE__ */ jsxRuntime.jsx(MaybeTraitScope, { sourceTrait: content.sourceTrait, children: wrappedContent })
+      "data-testid": `ui-slot-${slot}`,
+      "data-slot-mode": showFallback ? "append" : "content",
+      children: [
+        showFallback ? fallback : null,
+        /* @__PURE__ */ jsxRuntime.jsx(MaybeTraitScope, { sourceTrait: content.sourceTrait, children: wrappedContent })
+      ]
     }
   );
 }

package/dist/providers/index.js

@@ -51344,7 +51344,9 @@ function UISlotComponentInner({
   className,
   children,
   pattern,
-  sourceTrait
+  sourceTrait,
+  fallback,
+  mode = "replace"
 }) {
   const { slots, clear } = useUISlots();
   const eventBus = useEventBus();
@@ -51396,12 +51398,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"
         }
       );
     }
@@ -51418,29 +51434,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 })
+      ]
     }
   );
 }

package/dist/runtime/index.cjs

@@ -51067,7 +51067,9 @@ function UISlotComponentInner({
   className,
   children,
   pattern,
-  sourceTrait
+  sourceTrait,
+  fallback,
+  mode = "replace"
 }) {
   const { slots, clear } = context.useUISlots();
   const eventBus = useEventBus();
@@ -51119,12 +51121,26 @@ function UISlotComponentInner({
     );
   }
   if (!content) {
+    if (fallback !== void 0) {
+      return /* @__PURE__ */ jsxRuntime.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__ */ jsxRuntime.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"
         }
       );
     }
@@ -51141,29 +51157,51 @@ function UISlotComponentInner({
     clear(slot);
   };
   if (portal) {
-    if (contained) {
-      return renderContainedPortal(t, slot, content, handleDismiss);
-    }
-    return /* @__PURE__ */ jsxRuntime.jsx(
-      SlotPortal,
+    const inlineFallback = mode === "append" && fallback !== void 0 ? /* @__PURE__ */ jsxRuntime.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__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+        inlineFallback,
+        renderContainedPortal(t, slot, content, handleDismiss)
+      ] });
+    }
+    return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      inlineFallback,
+      /* @__PURE__ */ jsxRuntime.jsx(
+        SlotPortal,
+        {
+          slot,
+          content,
+          position,
+          onDismiss: handleDismiss
+        }
+      )
+    ] });
   }
   const slotContent = /* @__PURE__ */ jsxRuntime.jsx(SlotContentRenderer, { content, onDismiss: handleDismiss });
   const wrappedContent = suspenseConfig.enabled ? /* @__PURE__ */ jsxRuntime.jsx(ErrorBoundary, { children: /* @__PURE__ */ jsxRuntime.jsx(React87.Suspense, { fallback: getSlotFallback(slot, suspenseConfig), children: slotContent }) }) : /* @__PURE__ */ jsxRuntime.jsx(ErrorBoundary, { children: slotContent });
-  return /* @__PURE__ */ jsxRuntime.jsx(
+  const showFallback = mode === "append" && fallback !== void 0;
+  return /* @__PURE__ */ jsxRuntime.jsxs(
     Box,
     {
       id: `slot-${slot}`,
       className: cn("ui-slot", `ui-slot-${slot}`, className),
       "data-pattern": content.pattern,
       "data-source-trait": content.sourceTrait,
-      children: /* @__PURE__ */ jsxRuntime.jsx(MaybeTraitScope, { sourceTrait: content.sourceTrait, children: wrappedContent })
+      "data-testid": `ui-slot-${slot}`,
+      "data-slot-mode": showFallback ? "append" : "content",
+      children: [
+        showFallback ? fallback : null,
+        /* @__PURE__ */ jsxRuntime.jsx(MaybeTraitScope, { sourceTrait: content.sourceTrait, children: wrappedContent })
+      ]
     }
   );
 }
@@ -54243,17 +54281,30 @@ function PluginRuntimeMount({
     () => new Set(plugin.schema.orbitals.map((o) => o.name)),
     [plugin.schema]
   );
+  const inboundBusEvents = React87.useMemo(
+    () => new Set(plugin.inbound.map((row) => row.busEvent)),
+    [plugin.inbound]
+  );
+  const inboundTriggerNames = React87.useMemo(
+    () => new Set(plugin.inbound.map((row) => row.trigger)),
+    [plugin.inbound]
+  );
+  const snapshotAllStates = React87.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]);
   React87.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));
@@ -54261,7 +54312,39 @@ function PluginRuntimeMount({
     return () => {
       cancelled = true;
     };
-  }, [registrationReady, mockRuntime, plugin, onDispatched, onError]);
+  }, [registrationReady, mockRuntime, plugin, onDispatched, onError, snapshotAllStates]);
+  React87.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]);
+  React87.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 = React87.useCallback(
     async (row, payload) => {
       await registrationReady;
@@ -54280,11 +54363,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 = [];
@@ -54294,7 +54380,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]
   );
   React87.useEffect(() => {
     const unsubs = plugin.inbound.map(
@@ -54378,6 +54464,20 @@ 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();
 
@@ -54456,6 +54556,7 @@ Object.defineProperty(exports, "wrapCallbackForEvent", {
 exports.BrowserPlayground = BrowserPlayground;
 exports.OrbPreview = OrbPreview;
 exports.OrbitalPluginHost = OrbitalPluginHost;
+exports.assertUniqueSlotsPerHost = assertUniqueSlotsPerHost;
 exports.clearSchemaCache = clearSchemaCache;
 exports.createClientEffectHandlers = createClientEffectHandlers;
 exports.useDeclaredCaptureTable = useDeclaredCaptureTable;

package/dist/runtime/index.d.cts

@@ -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.cjs';
 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.cjs';
 export { p as profilerOnRender, u as usePerfBuffer } from '../perf-DaVdsbU0.cjs';
 import '../event-bus-types-Bl78kokd.cjs';
 import '../useUISlots-GNwGLlW2.cjs';
@@ -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
  */