@almadar/ui 6.53.1 → 6.55.0

package/dist/{chunk-53VTY5CC.js → chunk-FQM37C56.js}

@@ -1,18 +1,18 @@
-import { runTickFrame } from './chunk-DQTV6QVS.js';
+import { useTranslate, useRenderI18n, runTickFrame } from './chunk-QGH4NAQO.js';
 import { ALL_SLOTS } from './chunk-VHTJRS2N.js';
-import { UISlotRenderer } from './chunk-HUG25TT3.js';
-import { Box } from './chunk-7LM6I3NA.js';
-import { Typography } from './chunk-HB4C27KU.js';
+import { LoadingState, ErrorState, UISlotRenderer } from './chunk-XZKGRSIO.js';
+import { Box } from './chunk-Y53Q55H5.js';
+import { Typography } from './chunk-HCSJHRC4.js';
 import { beginPending, endPending } from './chunk-JRW33U35.js';
 import { useEventBus } from './chunk-6EV3OEBQ.js';
-import { isNotificationSlot } from './chunk-PEST66PN.js';
 import { registerTrait, unregisterTrait, perfTimeAsync } from './chunk-KQXXO42S.js';
-import { bindTraitStateGetter, registerTraitSnapshot, recordTransition, recordingTransport, recordServerResponse } from './chunk-O7OLVVBR.js';
+import { bindTraitStateGetter, registerTraitSnapshot, recordTransition, recordingTransport, recordServerResponse } from './chunk-Q47ZN2DW.js';
+import { isNotificationSlot } from './chunk-PEST66PN.js';
 import React, { useState, useMemo, useEffect, useRef, useCallback, useSyncExternalStore } from 'react';
-import { schemaToIR, getPage, clearSchemaCache as clearSchemaCache$1, applyListenPayloadMapping, buildResolvedTraitConfigs, collectCallsiteCaptureChildren, walkSExpr, isRenderBindingMarker, containsEntityBinding, isSExpr, isEventPayloadValue, RENDER_BINDING_MARKER } from '@almadar/core';
+import { schemaToIR, getPage, clearSchemaCache as clearSchemaCache$1, traitsEmbeddedByEvent, traitReferencesCallsitePayload, configReferencesCallsitePayload, TRAIT_MOUNT_ERROR_TESTID, traitsEmbeddedByEffects, applyListenPayloadMapping, buildResolvedTraitConfigs, collectCallsiteCaptureChildren, orbitalInlineEntities, storesRowsInBrowser, walkSExpr, isRenderBindingMarker, containsEntityBinding, isSExpr, isEventPayloadValue, RENDER_BINDING_MARKER } from '@almadar/core';
 import { createLogger } from '@almadar/logger';
-import { collectListenerTargets, LIFECYCLE_EVENTS, InMemoryPersistence, createInProcessTransport, buildTraitIndex, createMemoryCircuitStore, createIndexStageRunner, evaluateOrbitalEvent, createClientKernel, createTickScheduler, isValidCronExpression, parseDurationString, UNMOUNT_EVENT, createClientEffectHandlers, EffectExecutor, isSExpression, collectDeclaredConfigDefaults, createContextFromBindings, normalizeCallSiteConfigToValues } from '@almadar/runtime';
-import { useUser, useArbitraryClassStyles, getAllPages, matchPathAmong, CurrentPagePathProvider, NavStackProvider, OrbitalProvider, useNavStack, VerificationProvider, EntitySchemaProvider, OrbitalThemeProvider, ServerBridgeProvider, useServerBridge, EntityBindingContext, AwaitingSkeletonContext } from '@almadar/ui/providers';
+import { collectListenerTargets, LIFECYCLE_EVENTS, TraitMountError, InMemoryPersistence, loadLazyPage, createInProcessTransport, buildTraitIndex, createMemoryCircuitStore, createLocalStoreTransport, createResidenceTransport, createClientKernel, createTickScheduler, isValidCronExpression, parseDurationString, UNMOUNT_EVENT, createClientEffectHandlers, EffectExecutor, isSExpression, collectDeclaredConfigDefaults, createContextFromBindings, openBrowserStore, browserStoreName, normalizeCallSiteConfigToValues } from '@almadar/runtime';
+import { useUser, useHasServerBridge, useArbitraryClassStyles, getAllPages, matchPathAmong, CurrentPagePathProvider, NavStackProvider, OrbitalProvider, ServerBridgeProvider, useNavStack, VerificationProvider, EntitySchemaProvider, OrbitalThemeProvider, useServerBridge, EntityBindingContext, AwaitingSkeletonContext } from '@almadar/ui/providers';
 import { evaluateListenPayloadExpr, evaluate, createMinimalContext, evaluateGuard, executeEffects } from '@almadar/evaluator';
 import { getPatternDefinition } from '@almadar/core/patterns';
 import { isKnownStdOperator } from '@almadar/std/registry';
@@ -20,9 +20,10 @@ import { prepareSchemaForPreview, collectTraitRefsFromResolvedTrait, buildOrbita
 export { adjustSchemaForMockData, buildMockData, collectEmbeddedTraits, prepareSchemaForPreview } from '@almadar/runtime/ui';
 import { useInRouterContext, useHref } from 'react-router-dom';
 import { UISlotProvider, useUISlots } from '@almadar/ui/context';
-import { useTranslate } from '@almadar/ui/hooks';
+import { useTranslate as useTranslate$1, createTranslate, I18nProvider } from '@almadar/ui/hooks';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { OrbitalServerRuntime } from '@almadar/runtime/OrbitalServerRuntime';
+import { localeDirection } from '@almadar/core/i18n';
 
 var resolvedSchemaLog = createLogger("almadar:ui:resolved-schema");
 function useResolvedSchema(schema, pageName) {
@@ -172,9 +173,9 @@ function getTabClientId() {
   return tabClientId;
 }
 var log = createLogger("almadar:ui:circuit-kernel");
-function postUnmounts(transport, traits) {
+function postUnmounts(transport, traits, locale) {
   for (const [traitName, orbitalName] of traits) {
-    transport.send(orbitalName, { event: UNMOUNT_EVENT, targetTrait: traitName, clientId: getTabClientId() }).catch((err) => log.warn("unmount-post-failed", { trait: traitName, orbital: orbitalName, error: String(err) }));
+    transport.send(orbitalName, { event: UNMOUNT_EVENT, targetTrait: traitName, clientId: getTabClientId(), locale }).catch((err) => log.warn("unmount-post-failed", { trait: traitName, orbital: orbitalName, error: String(err) }));
   }
 }
 function restrictTraitIndex(full, activeNames) {
@@ -185,16 +186,22 @@ function restrictTraitIndex(full, activeNames) {
   return { byName, allEntities: full.allEntities, orbitals: full.orbitals };
 }
 function useCircuitKernel(traitBindings, options) {
+  const hostRunsProgram = options.transport?.hostsBrowserStore === true;
   const fullTraitIndex = useMemo(
-    () => buildTraitIndex(options.orbitals, options.traitConfigsByName),
-    [options.orbitals, options.traitConfigsByName]
+    () => buildTraitIndex(options.orbitals, options.traitConfigsByName, { hostRunsProgram }),
+    [options.orbitals, options.traitConfigsByName, hostRunsProgram]
   );
+  const appTraitNames = useMemo(() => new Set(fullTraitIndex.byName.keys()), [fullTraitIndex]);
   const activeTraitKey = traitBindings.map((b) => b.trait.name).filter((n) => !!n).sort().join("\0");
   const traitIndex = useMemo(
     () => restrictTraitIndex(fullTraitIndex, new Set(activeTraitKey === "" ? [] : activeTraitKey.split("\0"))),
     [activeTraitKey, fullTraitIndex]
   );
   const mountedRef = useRef(/* @__PURE__ */ new Map());
+  const { locale } = useTranslate();
+  const i18n = useRenderI18n();
+  const localeRef = useRef(locale);
+  localeRef.current = locale;
   const transport = options.transport;
   const topologyPending = options.awaitTopology === true;
   useEffect(() => {
@@ -203,12 +210,12 @@ function useCircuitKernel(traitBindings, options) {
     const dropped = [...mounted].filter(([name]) => !traitIndex.byName.has(name));
     mounted.clear();
     for (const [name, entry] of traitIndex.byName) mounted.set(name, entry.orbitalName);
-    postUnmounts(transport, dropped);
+    postUnmounts(transport, dropped, localeRef.current);
   }, [traitIndex, transport, topologyPending]);
   useEffect(() => {
     if (transport === void 0) return;
     const mounted = mountedRef.current;
-    return () => postUnmounts(transport, [...mounted]);
+    return () => postUnmounts(transport, [...mounted], localeRef.current);
   }, [transport]);
   const store = useMemo(() => {
     const traitDefs = Array.from(traitIndex.byName.values(), (entry) => entry.traitDef);
@@ -219,42 +226,43 @@ function useCircuitKernel(traitBindings, options) {
     };
     return createMemoryCircuitStore(traitDefs, config, options.observer);
   }, [traitIndex, options.guardMode, options.strictBindings, options.contextExtensions, options.observer]);
-  const offlineTransport = useMemo(() => {
-    if (options.transport !== void 0 || options.persistence === void 0) return void 0;
-    const persistence = options.persistence;
-    return createInProcessTransport(
-      async (_orbitalName, request) => {
-        const runEffects = createIndexStageRunner({
-          traitIndex,
-          persistence,
-          frames: store.frames,
-          manager: store.manager,
-          ...options.callService !== void 0 ? { extraEffectHandlers: { callService: options.callService } } : {},
-          ...options.debug !== void 0 ? { debug: options.debug } : {}
-        });
-        return evaluateOrbitalEvent(
-          {
-            traitIndex,
-            manager: store.manager,
-            persistence,
-            frames: store.frames,
-            runEffects,
-            ...options.user !== void 0 ? { user: options.user } : {},
-            ...options.guardMode !== void 0 ? { guardMode: options.guardMode } : {},
-            ...options.strictBindings !== void 0 ? { strictBindings: options.strictBindings } : {},
-            ...options.contextExtensions !== void 0 ? { contextExtensions: options.contextExtensions } : {},
-            ...options.debug !== void 0 ? { debug: options.debug } : {},
-            ...options.logContext !== void 0 ? { logContext: options.logContext } : {}
-          },
-          request
-        );
-      },
-      { carriesCircuitState: false }
-    );
+  const localTransportOptions = {
+    traitIndex,
+    store,
+    ...options.callService !== void 0 ? { callService: options.callService } : {},
+    ...options.user !== void 0 ? { user: options.user } : {},
+    ...options.guardMode !== void 0 ? { guardMode: options.guardMode } : {},
+    ...options.strictBindings !== void 0 ? { strictBindings: options.strictBindings } : {},
+    ...options.contextExtensions !== void 0 ? { contextExtensions: options.contextExtensions } : {},
+    ...options.debug !== void 0 ? { debug: options.debug } : {},
+    ...options.logContext !== void 0 ? { logContext: options.logContext } : {}
+  };
+  const offlineTransport = useMemo(
+    () => options.transport !== void 0 || options.persistence === void 0 ? void 0 : createLocalStoreTransport({ ...localTransportOptions, persistence: options.persistence }),
+    [
+      options.transport,
+      options.persistence,
+      traitIndex,
+      store,
+      options.callService,
+      options.user,
+      options.guardMode,
+      options.strictBindings,
+      options.contextExtensions,
+      options.debug,
+      options.logContext
+    ]
+  );
+  const routedTransport = useMemo(() => {
+    if (options.browserStore === void 0) return void 0;
+    const local = createLocalStoreTransport({ ...localTransportOptions, traitIndex: fullTraitIndex, persistence: options.browserStore, clientRelays: true });
+    const remote = options.transport ?? offlineTransport;
+    return createResidenceTransport({ local, ...remote !== void 0 ? { remote } : {}, traitIndex: fullTraitIndex });
   }, [
+    options.browserStore,
     options.transport,
-    options.persistence,
-    traitIndex,
+    offlineTransport,
+    fullTraitIndex,
     store,
     options.callService,
     options.user,
@@ -264,7 +272,7 @@ function useCircuitKernel(traitBindings, options) {
     options.debug,
     options.logContext
   ]);
-  const baseTransport = options.transport ?? offlineTransport;
+  const baseTransport = routedTransport ?? options.transport ?? offlineTransport;
   const effectiveTransport = useMemo(
     () => baseTransport === void 0 ? void 0 : recordingTransport(baseTransport),
     [baseTransport]
@@ -289,6 +297,8 @@ function useCircuitKernel(traitBindings, options) {
     store,
     ...options.persistence !== void 0 ? { persistence: options.persistence } : {},
     ...options.user !== void 0 ? { user: options.user } : {},
+    locale,
+    ...i18n !== void 0 ? { messages: { [i18n.locale]: i18n.messages } } : {},
     ...options.guardMode !== void 0 ? { guardMode: options.guardMode } : {},
     ...options.strictBindings !== void 0 ? { strictBindings: options.strictBindings } : {},
     ...options.contextExtensions !== void 0 ? { contextExtensions: options.contextExtensions } : {},
@@ -304,6 +314,8 @@ function useCircuitKernel(traitBindings, options) {
     store,
     options.persistence,
     options.user,
+    locale,
+    i18n,
     options.guardMode,
     options.strictBindings,
     options.contextExtensions,
@@ -312,21 +324,29 @@ function useCircuitKernel(traitBindings, options) {
     topology,
     effectiveTransport
   ]);
-  const kernel = useMemo(() => ({
-    store: rawKernel.store,
-    dispatch: (request, hooks) => rawKernel.dispatch(request.clientId !== void 0 ? request : { ...request, clientId: getTabClientId() }, hooks),
-    dispatchMount: (seeds, hooks, base = {}) => rawKernel.dispatchMount(seeds, hooks, base.clientId !== void 0 ? base : { ...base, clientId: getTabClientId() }),
-    dispatchProgress: (request) => rawKernel.dispatchProgress(request.clientId !== void 0 ? request : { ...request, clientId: getTabClientId() })
-  }), [rawKernel]);
-  return { kernel, store, traitIndex, transport: effectiveTransport };
+  const kernel = useMemo(() => {
+    const stamp = (request) => ({
+      ...request,
+      clientId: request.clientId ?? getTabClientId(),
+      locale: request.locale ?? locale
+    });
+    return {
+      store: rawKernel.store,
+      dispatch: (request, hooks) => rawKernel.dispatch(stamp(request), hooks),
+      dispatchMount: (seeds, hooks, base = {}) => rawKernel.dispatchMount(seeds, hooks, stamp(base)),
+      dispatchProgress: (request) => rawKernel.dispatchProgress(stamp(request)),
+      foldHostDispatch: (request, response) => rawKernel.foldHostDispatch(request, response)
+    };
+  }, [rawKernel, locale]);
+  return { kernel, store, traitIndex, appTraitNames, transport: effectiveTransport };
 }
 var log2 = createLogger("almadar:ui:circuit:bus-ingress");
-function useBusIngress(traitBindings, traitIndex, settle, eventBus) {
+function useBusIngress(traitBindings, traitIndex, settle, eventBus, appTraitNames) {
   useEffect(() => {
     const unsubscribes = [];
     const subscribedQualified = /* @__PURE__ */ new Set();
     const subscribedBare = /* @__PURE__ */ new Set();
-    const deliveredHere = (source) => source?.dispatched === true && source.trait !== void 0 && traitIndex.byName.has(source.trait);
+    const deliveredHere = (source) => source?.dispatched === true && source.trait !== void 0 && (traitIndex.byName.has(source.trait) || appTraitNames.has(source.trait));
     const claims = /* @__PURE__ */ new WeakMap();
     const claim = (source, traitName, eventKey) => {
       if (source === void 0) return true;
@@ -423,7 +443,7 @@ function useBusIngress(traitBindings, traitIndex, settle, eventBus) {
     return () => {
       for (const unsub of unsubscribes) unsub();
     };
-  }, [traitBindings, traitIndex, settle, eventBus]);
+  }, [traitBindings, traitIndex, settle, eventBus, appTraitNames]);
 }
 var lambdaLog = createLogger("almadar:ui:fn-form-lambda");
 function patternPropsSchema(patternType) {
@@ -498,7 +518,7 @@ function resolveLambdaBindings(body, params, item, index) {
   return body;
 }
 var LazySlotContentRenderer = React.lazy(
-  () => import('./UISlotRenderer-P7A4SZSK.js').then((m) => ({ default: m.SlotContentRenderer }))
+  () => import('./UISlotRenderer-QTHFT6Z4.js').then((m) => ({ default: m.SlotContentRenderer }))
 );
 function deferLambdaEntityExprs(value) {
   if (typeof value === "string") {
@@ -795,11 +815,12 @@ async function runCircuitEffects(params) {
 // hooks/circuit/useCallsiteCapture.ts
 var log4 = createLogger("almadar:ui:circuit:callsite-capture");
 function useCallsiteCapture(traitBindings, store, traitIndex, slotFlush, options) {
-  return useCallback(async function reRender(traitName, callsitePayload, entityByTrait, visited = /* @__PURE__ */ new Set(), serverComposed = /* @__PURE__ */ new Set(), keepComposed = false) {
+  return useCallback(async function reRender(traitName, callsitePayload, entityByTrait, visited = /* @__PURE__ */ new Set(), serverComposed = /* @__PURE__ */ new Set(), keepComposed = false, composedBy) {
     const children = options.callsiteCaptureChildrenByTrait?.get(traitName);
     if (!children || children.size === 0) return;
     const bindingMap = new Map(traitBindings.map((b) => [b.trait.name, b]));
     for (const childName of children) {
+      if (composedBy !== void 0 && !composedBy.has(childName)) continue;
       if (visited.has(childName)) continue;
       visited.add(childName);
       const childBinding = bindingMap.get(childName);
@@ -853,7 +874,7 @@ function useCallsiteCapture(traitBindings, store, traitIndex, slotFlush, options
           { event: lifecycleEvent, state: entry.result.previousState, entity: childBinding.linkedEntity }
         );
       }
-      await reRender(childName, composedWith, entityByTrait, visited, serverComposed, keepComposed);
+      await reRender(childName, composedWith, entityByTrait, visited, serverComposed, keepComposed, traitsEmbeddedByEffects(indexed.irTrait, entry.result.effects));
     }
   }, [traitBindings, store, traitIndex, slotFlush, options.callsiteCaptureChildrenByTrait, options.eventBus, options.navigate, options.navigateBack, options.user]);
 }
@@ -1131,6 +1152,7 @@ function useAwaitingSkeletonSource(store, traitIndex, embeddedTraits) {
 }
 
 // hooks/useTraitStateMachine.ts
+var MOUNT_ERROR_SOURCE = "$mount";
 var stateLog = createLogger("almadar:ui:state-transitions");
 function diffDroppedTraitNames(prev, next) {
   const dropped = [];
@@ -1145,15 +1167,17 @@ function normalizeEventKey(eventKey) {
 function useTraitStateMachine(traitBindings, uiSlots, options) {
   const eventBus = useEventBus();
   const { user: contextViewer } = useUser();
+  const { t } = useTranslate();
   const userContext = options.user ?? contextViewer ?? void 0;
   const observer = useMemo(() => createCircuitVerificationObserver(), []);
-  const { kernel, store, traitIndex, transport } = useCircuitKernel(traitBindings, {
+  const { kernel, store, traitIndex, appTraitNames, transport } = useCircuitKernel(traitBindings, {
     orbitals: options.orbitals,
     ...options.traitConfigsByName !== void 0 ? { traitConfigsByName: options.traitConfigsByName } : {},
     ...options.transport !== void 0 ? { transport: options.transport } : {},
     ...options.carriesCircuitState !== void 0 ? { carriesCircuitState: options.carriesCircuitState } : {},
     ...options.awaitTopology !== void 0 ? { awaitTopology: options.awaitTopology } : {},
     ...options.persistence !== void 0 ? { persistence: options.persistence } : {},
+    ...options.browserStore !== void 0 ? { browserStore: options.browserStore } : {},
     ...options.callService !== void 0 ? { callService: options.callService } : {},
     ...userContext !== void 0 ? { user: userContext } : {},
     ...options.debug !== void 0 ? { debug: options.debug } : {},
@@ -1192,11 +1216,11 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
         name: trait.name,
         currentState: state?.currentState ?? trait.states[0]?.name ?? "unknown",
         states: trait.states.map((s) => s.name),
-        transitions: trait.transitions.flatMap((t) => {
-          const froms = Array.isArray(t.from) ? t.from : [t.from];
-          return froms.map((f) => ({ from: f, to: t.to, event: t.event, guard: t.guard ? String(t.guard) : void 0 }));
+        transitions: trait.transitions.flatMap((t2) => {
+          const froms = Array.isArray(t2.from) ? t2.from : [t2.from];
+          return froms.map((f) => ({ from: f, to: t2.to, event: t2.event, guard: t2.guard ? String(t2.guard) : void 0 }));
         }),
-        guards: trait.transitions.filter((t) => t.guard).map((t) => ({ name: String(t.guard) })),
+        guards: trait.transitions.filter((t2) => t2.guard).map((t2) => ({ name: String(t2.guard) })),
         transitionCount: 0
       };
       registerTrait(info);
@@ -1234,7 +1258,9 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
       }
       const repainted = new Set(repaints.map((e) => e.traitName));
       const serverComposed = new Set([...store.callsitePayloads].filter(([child, composed]) => composedBefore.get(child) !== composed).map(([child]) => child));
-      await reRenderCallsiteCaptureChildren(traitName, payload ?? {}, entityByTrait, repainted, serverComposed);
+      const irTrait = traitIndex.byName.get(traitName)?.irTrait;
+      const composedBy = irTrait !== void 0 ? traitsEmbeddedByEvent(irTrait, eventKey) : void 0;
+      await reRenderCallsiteCaptureChildren(traitName, payload ?? {}, entityByTrait, repainted, serverComposed, false, composedBy);
     }
     options.onEventProcessed?.(eventKey, payload);
   }, [traitIndex, store, reRenderCallsiteCaptureChildren, options.onEventProcessed]);
@@ -1303,11 +1329,20 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
   useEffect(() => {
     if (!transport?.subscribe) return;
     return transport.subscribe((emitted, target) => {
-      for (const t of collectListenerTargets(traitIndex, emitted.source, emitted.event, emitted.payload)) {
-        void (target === "origin" ? progressAndSettle(t.listenerTrait, t.triggers, t.payload) : dispatchAndSettle(t.listenerTrait, t.triggers, t.payload));
+      for (const t2 of collectListenerTargets(traitIndex, emitted.source, emitted.event, emitted.payload)) {
+        void (target === "origin" ? progressAndSettle(t2.listenerTrait, t2.triggers, t2.payload) : dispatchAndSettle(t2.listenerTrait, t2.triggers, t2.payload));
       }
     }, { clientId: getTabClientId() });
   }, [transport, traitIndex, progressAndSettle, dispatchAndSettle]);
+  useEffect(() => {
+    if (!transport?.subscribeHostDispatches) return;
+    return transport.subscribeHostDispatches((_orbitalName, request, response) => {
+      const traitName = request.targetTrait;
+      if (traitName === void 0 || !traitIndex.byName.has(traitName)) return;
+      const composedBefore = new Map(store.callsitePayloads);
+      void kernel.foldHostDispatch(request, response).then((outcome) => settleOutcome(traitName, request.event, request.payload, outcome, composedBefore));
+    });
+  }, [transport, traitIndex, kernel, store, settleOutcome]);
   const mountAndSettle = useCallback(async (seeds, payload) => {
     const composedBefore = new Map(store.callsitePayloads);
     let beforeLocalPaint;
@@ -1341,7 +1376,7 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
       await afterSettle(seed.trait, seed.event, payload, seed.local.transitioned, [...seed.local.clientEffectsByTrait ?? [], ...serverRepaints], composedBefore);
     }
   }, [kernel, slotFlush, traitIndex, store, eventBus, options.navigate, options.navigateBack, afterSettle]);
-  useBusIngress(traitBindings, traitIndex, dispatchAndSettle, eventBus);
+  useBusIngress(traitBindings, traitIndex, dispatchAndSettle, eventBus, appTraitNames);
   const sendEvent = useCallback((eventKey, payload) => {
     const normalized = normalizeEventKey(eventKey);
     for (const [traitName] of traitIndex.byName) {
@@ -1376,25 +1411,70 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
     for (const traitName of left) mount.initialized.delete(traitName);
     store.mount.unmounted(left);
     const entering = [];
+    const embeddedChildren = new Set([...options.callsiteCaptureChildrenByTrait?.values() ?? []].flatMap((c) => [...c]));
     for (const binding of traitBindings) {
       const traitName = binding.trait.name;
       if (mount.initialized.has(traitName)) continue;
       mount.initialized.add(traitName);
+      const indexed = traitIndex.byName.get(traitName);
+      if (embeddedChildren.has(traitName) && indexed !== void 0 && (traitReferencesCallsitePayload(indexed.irTrait) || configReferencesCallsitePayload(indexed.config)) && store.manager.repaintLifecycleEvent(traitName) !== void 0 && !store.callsitePayloads.has(traitName)) {
+        continue;
+      }
       const lifecycleEvent = LIFECYCLE_EVENTS.find((evt) => store.manager.canHandleEvent(traitName, evt));
       if (lifecycleEvent !== void 0) entering.push({ trait: traitName, event: lifecycleEvent });
     }
     store.mount.mounting(entering.map((e) => e.trait));
     if (entering.length > 0) {
+      uiSlots.clearBySource("main", MOUNT_ERROR_SOURCE);
       void mountAndSettle(entering, { ...options.initPayload ?? {} }).catch((err) => {
-        stateLog.warn("mount:failed", { traits: entering.map((e) => e.trait), error: String(err) });
+        const traits = entering.map((e) => e.trait);
+        const message = err instanceof Error ? err.message : String(err);
+        const failed = err instanceof TraitMountError ? err.trait : traits.join(", ");
+        const cause = err instanceof TraitMountError ? err.original : err;
+        stateLog.warn("mount:failed", { traits, failed, error: message, stack: cause instanceof Error ? cause.stack : void 0 });
+        uiSlots.render({
+          target: "main",
+          pattern: "error-state",
+          props: { title: t("error.traitMountFailed", { trait: failed }), message, "data-testid": TRAIT_MOUNT_ERROR_TESTID },
+          sourceTrait: MOUNT_ERROR_SOURCE
+        });
       });
     }
     mountedRef.current = mount;
-  }, [traitBindings, store, mountAndSettle, mountKey]);
+  }, [traitBindings, store, mountAndSettle, mountKey, uiSlots, traitIndex, options.callsiteCaptureChildrenByTrait, t]);
   useSyncExternalStore(store.subscribe, store.getVersion, store.getVersion);
   const traitStates = useMemo(() => store.manager.getAllStates(), [store, store.getVersion()]);
   return { traitStates, sendEvent, getTraitState, canHandleEvent, entityBindingSource, awaitingSkeletonSource };
 }
+function useBrowserStore(appName, orbitals, locale) {
+  const entities = useMemo(() => orbitals.flatMap(orbitalInlineEntities).filter(storesRowsInBrowser), [orbitals]);
+  const [state, setState] = useState(() => entities.length === 0 ? { status: "none" } : { status: "opening" });
+  useEffect(() => {
+    if (entities.length === 0) {
+      setState({ status: "none" });
+      return;
+    }
+    let cancelled = false;
+    let opened;
+    setState({ status: "opening" });
+    const open = async () => {
+      try {
+        const store = await openBrowserStore(browserStoreName(appName, locale), orbitals, void 0, locale);
+        if (store === null) return;
+        opened = store;
+        if (!cancelled) setState({ status: "ready", store });
+      } catch (err) {
+        if (!cancelled) setState({ status: "failed", error: err instanceof Error ? err : new Error(String(err)) });
+      }
+    };
+    void open();
+    return () => {
+      cancelled = true;
+      opened?.close();
+    };
+  }, [appName, locale, entities, orbitals]);
+  return state;
+}
 
 // runtime/fitContent.ts
 var IDENTITY = { scale: 1, x: 0, y: 0 };
@@ -1454,7 +1534,7 @@ function appPathFromHref(href, hostHrefBase) {
   if (!href.startsWith(`${root}/`)) return null;
   return href.slice(root.length);
 }
-function TraitInitializer({ traits, routeParams, mountKey, orbitals, onNavigate, onNavigateBack, onLocalFallback, localFallbackTimeoutMs, persistence, traitConfigsByName, embeddedTraits, callsiteCaptureChildrenByTrait, hasBridge, children }) {
+function TraitInitializer({ traits, routeParams, mountKey, orbitals, onNavigate, onNavigateBack, onLocalFallback, localFallbackTimeoutMs, persistence, browserStore, traitConfigsByName, embeddedTraits, callsiteCaptureChildrenByTrait, hasBridge, children }) {
   const bridge = useServerBridge();
   const uiSlots = useUISlots();
   useEffect(() => {
@@ -1473,11 +1553,13 @@ function TraitInitializer({ traits, routeParams, mountKey, orbitals, onNavigate,
     ...callsiteCaptureChildrenByTrait !== void 0 ? { callsiteCaptureChildrenByTrait } : {},
     initPayload: routeParams,
     ...mountKey !== void 0 ? { mountKey } : {},
-    ...hasBridge ? { transport: bridge.transport, carriesCircuitState: bridge.carriesCircuitState, awaitTopology: !bridge.topologyKnown } : { persistence }
+    ...hasBridge ? { transport: bridge.transport, carriesCircuitState: bridge.carriesCircuitState, awaitTopology: !bridge.topologyKnown } : { persistence },
+    ...browserStore !== void 0 ? { browserStore } : {}
   });
   return /* @__PURE__ */ jsx(EntityBindingContext.Provider, { value: entityBindingSource, children: /* @__PURE__ */ jsx(AwaitingSkeletonContext.Provider, { value: awaitingSkeletonSource, children }) });
 }
 var CONTENT_STAGE_WIDTH = 480;
+var NO_ORBITALS = [];
 function FitToBox({ children, mode = "box" }) {
   const outerRef = useRef(null);
   const innerRef = useRef(null);
@@ -1659,6 +1741,8 @@ function SchemaRunner({ schema, serverUrl, transport, getAccessToken, mockData,
     return set;
   }, [schema, pageName]);
   const activeOrbitalTheme = useMemo(() => resolvePreviewTheme(schema, pageName), [schema, pageName]);
+  const { locale } = useTranslate$1();
+  const browserStore = useBrowserStore(schema.name ?? "app", transport?.hostsBrowserStore === true ? NO_ORBITALS : schema.orbitals, locale);
   const inner = /* @__PURE__ */ jsx(VerificationProvider, { enabled: true, children: /* @__PURE__ */ jsx(
     EntitySchemaProvider,
     {
@@ -1681,13 +1765,15 @@ function SchemaRunner({ schema, serverUrl, transport, getAccessToken, mockData,
           onLocalFallback,
           localFallbackTimeoutMs,
           persistence,
+          ...browserStore.status === "ready" ? { browserStore: browserStore.store } : {},
           children: /* @__PURE__ */ jsx(OrbitalThemeProvider, { theme: activeOrbitalTheme, override: themeOverride, children: /* @__PURE__ */ jsx(Box, { className: "h-full min-h-full overflow-auto p-4", children: /* @__PURE__ */ jsx(UISlotRenderer, { includeHud: true, hudMode: "inline", includeFloating: true, pageKey: pageName }) }) })
         }
       )
     }
   ) });
-  if (serverUrl || transport) {
-    return /* @__PURE__ */ jsx(ServerBridgeProvider, { schema, serverUrl, transport, getAccessToken, children: inner });
+  if (browserStore.status === "opening") return /* @__PURE__ */ jsx(LoadingState, {});
+  if (browserStore.status === "failed") {
+    return /* @__PURE__ */ jsx(ErrorState, { "data-testid": "browser-store-error", message: browserStore.error.message });
   }
   return inner;
 }
@@ -1718,12 +1804,15 @@ function OrbPreview({
   onPageChange,
   user = null,
   localFallbackTimeoutMs,
-  themeOverride
+  themeOverride,
+  lazyLoader,
+  schemaPath,
+  onUnmatchedNavigate
 }) {
   if (serverUrl && transport) {
     throw new Error("OrbPreview accepts serverUrl OR transport, not both");
   }
-  const { t } = useTranslate();
+  const { t } = useTranslate$1();
   const [localFallback, setLocalFallback] = useState(false);
   const eventBus = useEventBus();
   const inHostRouter = useInRouterContext();
@@ -1732,6 +1821,7 @@ function OrbPreview({
     if (localFallback) return;
     setLocalFallback(true);
   }, [localFallback]);
+  const hasOuterBridge = useHasServerBridge();
   const parseResult = useMemo(() => {
     let parsed;
     if (typeof schema === "string") {
@@ -1767,12 +1857,44 @@ function OrbPreview({
       return [];
     }
   }, [parsedSchema]);
+  const lazyPages = useMemo(() => parsedSchema?.lazyPages ?? [], [parsedSchema]);
+  const matchRoute = useCallback((path) => {
+    const candidates = [
+      ...pages.map((entry) => ({ kind: "page", entry, path: entry.page.path })),
+      ...lazyPages.map((page) => ({ kind: "lazy", page, path: page.path }))
+    ];
+    const hit = matchPathAmong(candidates, path, (c) => c.path);
+    if (!hit) return null;
+    return hit.candidate.kind === "page" ? { kind: "page", entry: hit.candidate.entry, params: hit.params } : { kind: "lazy", page: hit.candidate.page, params: hit.params };
+  }, [pages, lazyPages]);
+  const initialRoute = useMemo(
+    () => initialPagePath ? matchRoute(initialPagePath) : null,
+    [matchRoute, initialPagePath]
+  );
   const initialPageMatch = useMemo(() => {
-    if (!initialPagePath) return void 0;
-    const hit = matchPathAmong(pages, initialPagePath, (entry) => entry.page.path);
-    if (!hit) return void 0;
-    return { name: hit.candidate.page.name, params: hit.params };
-  }, [pages, initialPagePath]);
+    if (initialRoute?.kind !== "page" || !initialRoute.entry.page.name) return void 0;
+    return { name: initialRoute.entry.page.name, params: initialRoute.params };
+  }, [initialRoute]);
+  const [lazyRoute, setLazyRoute] = useState(
+    initialRoute?.kind === "lazy" && initialPagePath ? { page: initialRoute.page, path: initialPagePath } : null
+  );
+  const [lazyLoad, setLazyLoad] = useState({ status: "loading" });
+  useEffect(() => {
+    if (!lazyRoute) return;
+    if (!lazyLoader) {
+      setLazyLoad({ status: "error", error: `No loader for lazy page ${lazyRoute.page.path} (${lazyRoute.page.orbRef})` });
+      return;
+    }
+    let cancelled = false;
+    setLazyLoad({ status: "loading" });
+    void loadLazyPage(lazyLoader, lazyRoute.page, schemaPath).then((result) => {
+      if (cancelled) return;
+      setLazyLoad(result.success ? { status: "ready", schema: result.data } : { status: "error", error: result.error });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [lazyRoute?.page, lazyLoader, schemaPath]);
   const initialPageName = initialPageMatch?.name;
   const [currentPage, setCurrentPage] = useState(initialPageName);
   const [routeParams, setRouteParams] = useState(initialPageMatch?.params ?? {});
@@ -1782,8 +1904,9 @@ function OrbPreview({
       prevInitialPagePathRef.current = initialPagePath;
       setCurrentPage(initialPageName);
       setRouteParams(initialPageMatch?.params ?? {});
+      setLazyRoute(initialRoute?.kind === "lazy" && initialPagePath ? { page: initialRoute.page, path: initialPagePath } : null);
     }
-  }, [initialPagePath, initialPageName, initialPageMatch]);
+  }, [initialPagePath, initialPageName, initialPageMatch, initialRoute]);
   const currentPagePath = useMemo(() => {
     const activePageName = currentPage ?? pages[0]?.page.name;
     const resolved = pages.find((p) => p.page.name === activePageName)?.page.path;
@@ -1798,10 +1921,30 @@ function OrbPreview({
     return pattern.replace(/:([A-Za-z0-9_]+)/g, (whole, key) => routeParams[key] ?? whole);
   }, [currentPagePath, routeParams]);
   const navStackRef = useRef(null);
+  const announcePage = useCallback((path) => {
+    if (onPageChange) {
+      onPageChange(path);
+    } else if (!isolated && 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"));
+    }
+  }, [isolated, onPageChange]);
   const handleNavigate = useCallback((path, navState) => {
-    const hit = matchPathAmong(pages, path, (entry) => entry.page.path);
-    const match = hit?.candidate;
-    const params = { ...hit?.params ?? {}, ...navState ?? {} };
+    const route = matchRoute(path);
+    if (!route) {
+      onUnmatchedNavigate?.(path);
+      return;
+    }
+    if (route.kind === "lazy") {
+      setLazyRoute({ page: route.page, path });
+      announcePage(path);
+      return;
+    }
+    setLazyRoute(null);
+    const match = route.entry;
+    const params = { ...route.params, ...navState ?? {} };
     navLog.debug("handleNavigate", () => ({
       path,
       matched: match?.page.name ?? null,
@@ -1809,19 +1952,12 @@ function OrbPreview({
       navState: navState ? JSON.stringify(navState) : void 0,
       availablePaths: pages.map((p) => p.page.path)
     }));
-    if (match?.page.name) {
+    if (match.page.name) {
       setRouteParams(params);
       setCurrentPage(match.page.name);
-      if (onPageChange) {
-        onPageChange(path);
-      } else if (!isolated && 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"));
-      }
+      announcePage(path);
     }
-  }, [pages, isolated, onPageChange]);
+  }, [pages, matchRoute, announcePage, onUnmatchedNavigate]);
   const handleNavigateEffect = useCallback(
     (path, params, crumb) => {
       navStackRef.current?.beginNavigate(path, crumb);
@@ -1886,64 +2022,96 @@ function OrbPreview({
     navLog.info("interceptor:installed", { pageCount: pages.length, paths: pages.map((p) => p.page.path) });
     return () => el.removeEventListener("click", handler, true);
   }, [pages, handleNavigate, isolated, hostHrefBase]);
-  return /* @__PURE__ */ jsxs(
-    Box,
-    {
-      ref: containerRef,
-      className: `${fit ? "overflow-hidden" : "overflow-auto"} border border-[var(--color-border)] rounded-[var(--radius-md)] ${className ?? ""}`,
-      style: { height },
-      children: [
-        localFallback && /* @__PURE__ */ jsx(Box, { className: "px-3 py-2 bg-[var(--color-warning)] bg-opacity-10 border-b border-[var(--color-warning)] flex items-center gap-2", children: /* @__PURE__ */ jsx(Typography, { variant: "caption", className: "text-[var(--color-warning-foreground)] flex-1", children: t("orbPreview.serverUnreachable") }) }),
-        inHostRouter ? /* @__PURE__ */ jsx(HostHrefBaseProbe, { onBase: setHostHrefBase }) : null,
-        /* @__PURE__ */ jsx(CurrentPagePathProvider, { value: currentPagePath, children: /* @__PURE__ */ jsxs(
-          NavStackProvider,
+  const withBridge = (node) => (serverUrl || transport) && !hasOuterBridge ? /* @__PURE__ */ jsx(ServerBridgeProvider, { schema: parseResult.schema, serverUrl, transport, getAccessToken, children: node }) : node;
+  if (lazyRoute) {
+    return withBridge(
+      /* @__PURE__ */ jsxs(Box, { ref: containerRef, className: `overflow-auto ${className ?? ""}`, style: { height }, children: [
+        lazyLoad.status === "loading" && /* @__PURE__ */ jsx(LoadingState, {}),
+        lazyLoad.status === "error" && /* @__PURE__ */ jsx(ErrorState, { "data-testid": "lazy-page-error", message: lazyLoad.error }),
+        lazyLoad.status === "ready" && /* @__PURE__ */ jsx(
+          OrbPreview,
           {
-            pages: navPages,
-            currentPath: concreteCurrentPath,
-            navigate: handleNavigate,
-            storageKey: `almadar:navstack:${parseResult.schema.name ?? "preview"}`,
-            children: [
-              /* @__PURE__ */ jsx(NavStackRefBridge, { apiRef: navStackRef }),
-              /* @__PURE__ */ jsx(OrbitalProvider, { initialData: effectiveMockData, skipTheme: true, verification: true, isolated, user, children: /* @__PURE__ */ jsx(UISlotProvider, { children: fit ? /* @__PURE__ */ jsx(FitToBox, { mode: fit === "content" ? "content" : "box", children: /* @__PURE__ */ jsx(
-                SchemaRunner,
-                {
-                  schema: parseResult.schema,
-                  serverUrl,
-                  transport,
-                  getAccessToken,
-                  mockData: effectiveMockData,
-                  pageName: currentPage,
-                  routeParams,
-                  onNavigate: handleNavigateEffect,
-                  onNavigateBack: handleNavigateBack,
-                  onLocalFallback: handleLocalFallback,
-                  localFallbackTimeoutMs,
-                  persistence,
-                  themeOverride
-                }
-              ) }) : /* @__PURE__ */ jsx(
-                SchemaRunner,
-                {
-                  schema: parseResult.schema,
-                  serverUrl,
-                  transport,
-                  getAccessToken,
-                  mockData: effectiveMockData,
-                  pageName: currentPage,
-                  routeParams,
-                  onNavigate: handleNavigateEffect,
-                  onNavigateBack: handleNavigateBack,
-                  onLocalFallback: handleLocalFallback,
-                  localFallbackTimeoutMs,
-                  persistence,
-                  themeOverride
-                }
-              ) }) })
-            ]
-          }
-        ) })
-      ]
-    }
+            schema: lazyLoad.schema,
+            autoMock,
+            height: "100%",
+            className: "border-0",
+            serverUrl,
+            transport,
+            getAccessToken,
+            initialPagePath: lazyRoute.path,
+            user,
+            isolated,
+            fit,
+            onPageChange: announcePage,
+            themeOverride,
+            lazyLoader,
+            onUnmatchedNavigate: handleNavigate
+          },
+          lazyRoute.page.orbRef
+        )
+      ] })
+    );
+  }
+  return withBridge(
+    /* @__PURE__ */ jsxs(
+      Box,
+      {
+        ref: containerRef,
+        className: `${fit ? "overflow-hidden" : "overflow-auto"} border border-[var(--color-border)] rounded-[var(--radius-md)] ${className ?? ""}`,
+        style: { height },
+        children: [
+          localFallback && /* @__PURE__ */ jsx(Box, { className: "px-3 py-2 bg-[var(--color-warning)] bg-opacity-10 border-b border-[var(--color-warning)] flex items-center gap-2", children: /* @__PURE__ */ jsx(Typography, { variant: "caption", className: "text-[var(--color-warning-foreground)] flex-1", children: t("orbPreview.serverUnreachable") }) }),
+          inHostRouter ? /* @__PURE__ */ jsx(HostHrefBaseProbe, { onBase: setHostHrefBase }) : null,
+          /* @__PURE__ */ jsx(CurrentPagePathProvider, { value: currentPagePath, children: /* @__PURE__ */ jsxs(
+            NavStackProvider,
+            {
+              pages: navPages,
+              currentPath: concreteCurrentPath,
+              navigate: handleNavigate,
+              storageKey: `almadar:navstack:${parseResult.schema.name ?? "preview"}`,
+              children: [
+                /* @__PURE__ */ jsx(NavStackRefBridge, { apiRef: navStackRef }),
+                /* @__PURE__ */ jsx(OrbitalProvider, { initialData: effectiveMockData, skipTheme: true, verification: true, isolated, user, children: /* @__PURE__ */ jsx(UISlotProvider, { children: fit ? /* @__PURE__ */ jsx(FitToBox, { mode: fit === "content" ? "content" : "box", children: /* @__PURE__ */ jsx(
+                  SchemaRunner,
+                  {
+                    schema: parseResult.schema,
+                    serverUrl,
+                    transport,
+                    getAccessToken,
+                    mockData: effectiveMockData,
+                    pageName: currentPage,
+                    routeParams,
+                    onNavigate: handleNavigateEffect,
+                    onNavigateBack: handleNavigateBack,
+                    onLocalFallback: handleLocalFallback,
+                    localFallbackTimeoutMs,
+                    persistence,
+                    themeOverride
+                  }
+                ) }) : /* @__PURE__ */ jsx(
+                  SchemaRunner,
+                  {
+                    schema: parseResult.schema,
+                    serverUrl,
+                    transport,
+                    getAccessToken,
+                    mockData: effectiveMockData,
+                    pageName: currentPage,
+                    routeParams,
+                    onNavigate: handleNavigateEffect,
+                    onNavigateBack: handleNavigateBack,
+                    onLocalFallback: handleLocalFallback,
+                    localFallbackTimeoutMs,
+                    persistence,
+                    themeOverride
+                  }
+                ) }) })
+              ]
+            }
+          ) })
+        ]
+      }
+    )
   );
 }
 OrbPreview.displayName = "OrbPreview";
@@ -1957,7 +2125,11 @@ function BrowserPlayground({
   paused,
   fit,
   onPageChange,
-  viewer
+  viewer,
+  messages,
+  locale,
+  lazyLoader,
+  schemaPath
 }) {
   const [runtime] = useState(
     () => new OrbitalServerRuntime({ mode, debug: false, ...viewer !== void 0 ? { defaultUser: viewer } : {} })
@@ -1973,10 +2145,18 @@ function BrowserPlayground({
   const registrationReady = useMemo(() => {
     const orbitalNames = schema.orbitals.map((o) => o.name);
     playgroundLog.debug("register:start", { schema: schema.name, orbitalNames });
-    return runtime.register(schema).then(() => {
+    const lazyPages = schema.lazyPages ?? [];
+    const lazy = lazyPages.length > 0 && lazyLoader !== void 0 ? Promise.all(lazyPages.map(async (page) => {
+      const loaded = await loadLazyPage(lazyLoader, page, schemaPath);
+      if (!loaded.success) throw new Error(loaded.error);
+      return loaded.data;
+    })) : Promise.resolve([]);
+    return lazy.then(
+      (lazySchemas) => runtime.register(schema, { ...messages !== void 0 ? { messages } : {}, lazy: lazySchemas })
+    ).then(() => {
       playgroundLog.debug("register:done", { schema: schema.name, orbitalNames });
     });
-  }, [runtime, schema]);
+  }, [runtime, schema, messages, lazyLoader, schemaPath]);
   const teardownTimerRef = useRef(null);
   useEffect(() => {
     if (teardownTimerRef.current !== null) {
@@ -1998,7 +2178,8 @@ function BrowserPlayground({
         return runtime.processOrbitalEvent(orbitalName, request);
       },
       {
-        onRegister: (s) => runtime.register(s),
+        // The program (lazy behaviors included) is registered above; the bridge only waits for it.
+        onRegister: () => registrationReady,
         onUnregister: () => {
           runtime.unregisterAll();
         }
@@ -2006,7 +2187,13 @@ function BrowserPlayground({
     ),
     [runtime, registrationReady]
   );
-  return /* @__PURE__ */ jsx(
+  const viewerLocale = locale ?? schema.locales?.[0];
+  const i18n = useMemo(() => {
+    if (viewerLocale === void 0 || messages === void 0) return void 0;
+    const catalog = messages[viewerLocale] ?? {};
+    return { locale: viewerLocale, direction: localeDirection(viewerLocale), t: createTranslate(catalog), messages: catalog };
+  }, [viewerLocale, messages]);
+  const preview = /* @__PURE__ */ jsx(
     OrbPreview,
     {
       schema,
@@ -2017,9 +2204,12 @@ function BrowserPlayground({
       fit,
       onPageChange,
       user: viewer ?? null,
+      lazyLoader,
+      schemaPath,
       isolated: true
     }
   );
+  return i18n !== void 0 ? /* @__PURE__ */ jsx(I18nProvider, { value: i18n, children: preview }) : preview;
 }
 
 export { BrowserPlayground, OrbPreview, clearSchemaCache, useResolvedSchema, useTraitStateMachine };