@almadar/ui 6.59.0 → 6.62.0

package/dist/runtime/index.d.ts

@@ -1,4 +1,4 @@
-import { EventPayload, OrbitalDefinition, PersistenceAdapter, ServiceParams, TraitConfig, UserContext, ResolvedTraitBinding, ResolvedPage, ResolvedEntity, ResolvedTrait, ResolvedIR, OrbitalSchema, PatternConfig, ResolvedPatternProps, EventSource, SExpr, EntityData, MessageCatalogs } from '@almadar/core';
+import { EventPayload, OrbitalDefinition, PersistenceAdapter, ServiceParams, TraitConfig, UserContext, ResolvedTraitBinding, ResolvedPage, ResolvedEntity, ResolvedTrait, ResolvedIR, OrbitalSchema, PatternConfig, ResolvedPatternProps, EventSource, SExpr, EntityData, ViewerAuthority, MessageCatalogs, TraitValue, TraitValueMountResult, BehaviorRef, BehaviorValueMountResult } from '@almadar/core';
 export { ResolvedEntity, ResolvedIR, ResolvedPage, ResolvedTrait, ResolvedTraitBinding } from '@almadar/core';
 import { TraitState, EventTransport, AccessTokenProvider, SchemaLoader } from '@almadar/runtime';
 export { AccessTokenProvider, ClientEventBus, CreateClientEffectHandlersOptions, SlotSetter, createClientEffectHandlers } from '@almadar/runtime';
@@ -206,6 +206,13 @@ interface OrbPreviewProps {
      * it does on the server. Omitted → anonymous.
      */
     user?: UserData | null;
+    /**
+     * What the host's auth provider has resolved the viewer to be. An
+     * `access: authenticated` page mounts only on `authenticated`; any other
+     * resolved value sends the viewer to the app's `signIn` route. Omitted → the
+     * host offers no sign-in (`unavailable`).
+     */
+    authority?: ViewerAuthority;
     /**
      * Sandbox mode, for previews embedded in a host app (e.g. the studio
      * canvas): the event bus stays context-local, navigation stays in memory
@@ -246,8 +253,20 @@ interface OrbPreviewProps {
      * loaded behavior hands links back to the schema that imported it.
      */
     onUnmatchedNavigate?: (path: string) => void;
+    /**
+     * The host's own sign-in (`HOST_SIGN_IN_ROUTE`, `/login`): navigating there —
+     * including an `access: authenticated` page sending its viewer to
+     * `signIn: "/login"` — calls this with the return path instead of routing to a
+     * page. Omitted → the host offers no sign-in and nothing happens.
+     */
+    onSignIn?: (returnTo?: string) => void;
+    /**
+     * The host's session sign-out, called on the system event `UI:SIGN_OUT` (a
+     * Sign out inside the circuit). Omitted → the host offers no sign-out.
+     */
+    onSignOut?: () => void;
 }
-declare function OrbPreview({ schema, mockData, autoMock, height, className, serverUrl, transport, getAccessToken, initialPagePath, isolated, fit, onPageChange, user, localFallbackTimeoutMs, themeOverride, lazyLoader, schemaPath, onUnmatchedNavigate, }: OrbPreviewProps): React__default.ReactElement;
+declare function OrbPreview({ schema, mockData, autoMock, height, className, serverUrl, transport, getAccessToken, initialPagePath, isolated, fit, onPageChange, user, authority, localFallbackTimeoutMs, themeOverride, lazyLoader, schemaPath, onUnmatchedNavigate, onSignIn, onSignOut, }: OrbPreviewProps): React__default.ReactElement;
 declare namespace OrbPreview {
     var displayName: string;
 }
@@ -404,4 +423,52 @@ declare function useOrbitalPluginHost(): {
  */
 declare function OrbitalPluginHost({ plugins, mode, transport, deny, navigate, onTransition, children, }: OrbitalPluginHostProps): React__default.ReactElement;
 
-export { BrowserPlayground, type BrowserPlaygroundProps, OrbPreview, type OrbPreviewProps, OrbitalPluginHost, type OrbitalPluginHostProps, type PluginHostDenyVerb, type PluginHostInbound, type PluginHostPlugin, type ResolvedSchemaResult, ServerBridgeTransport, type SlotPatternEntry, type SlotSource, type TraitStateMachineResult, type UseTraitStateMachineOptions, clearSchemaCache, useDeclaredCaptureTable, useOrbitalPluginHost, useResolvedSchema, useTraitStateMachine };
+/**
+ * TraitValueFrame — renders a trait VALUE (a trait of an installed behavior held
+ * as data, language trio) where a render tree embeds it, the data-bound sibling
+ * of `TraitFrame`'s `@trait.X` lens.
+ *
+ * The host turns the value into a runnable program (`TraitValueMountProvider`'s
+ * `mount`: a validated, resolved one-orbital wrapper — the binding's admission
+ * check), and the frame runs it through the plugin host's own runtime, bridged
+ * to the ambient event bus, inside a scoped slot provider so the trait's UI
+ * paints HERE rather than into the app's shared slots. `INIT` reaches the
+ * mounted trait through the plugin host's declared inbound table.
+ *
+ * @packageDocumentation
+ */
+
+/** How the host mounts trait values: the resolver plus the plugin-host execution mode. */
+interface TraitValueMountHost {
+    mount: (value: TraitValue) => Promise<TraitValueMountResult>;
+    /** 'mock' (default): in-memory, as a preview. 'server': through `transport`. */
+    mode?: 'mock' | 'server';
+    transport?: EventTransport;
+    /** Mounts a whole behavior value (`BehaviorValueFrame`); a host without it cannot run behavior values. */
+    mountBehavior?: (value: BehaviorRef) => Promise<BehaviorValueMountResult>;
+    /** Where a mounted behavior value's events run; in-memory when omitted. */
+    behaviorTransport?: ServerBridgeTransport;
+}
+declare function TraitValueMountProvider({ host, children }: {
+    host: TraitValueMountHost;
+    children: ReactNode;
+}): React__default.ReactElement;
+declare function TraitValueFrame({ value }: {
+    value: TraitValue;
+}): React__default.ReactElement;
+
+/**
+ * BehaviorValueFrame — renders a whole behavior VALUE (`.lolo` type `behavior`,
+ * `behavior/ref`) where a render tree embeds it: the host mounts the program
+ * (validated at 0/0 and resolved), and the frame runs it in place through an
+ * isolated `OrbPreview` — its own event bus, in-memory navigation starting at the
+ * program's first page, the host URL untouched.
+ *
+ * @packageDocumentation
+ */
+
+declare function BehaviorValueFrame({ value }: {
+    value: BehaviorRef;
+}): React__default.ReactElement;
+
+export { BehaviorValueFrame, BrowserPlayground, type BrowserPlaygroundProps, OrbPreview, type OrbPreviewProps, OrbitalPluginHost, type OrbitalPluginHostProps, type PluginHostDenyVerb, type PluginHostInbound, type PluginHostPlugin, type ResolvedSchemaResult, ServerBridgeTransport, type SlotPatternEntry, type SlotSource, type TraitStateMachineResult, TraitValueFrame, type TraitValueMountHost, TraitValueMountProvider, type UseTraitStateMachineOptions, clearSchemaCache, useDeclaredCaptureTable, useOrbitalPluginHost, useResolvedSchema, useTraitStateMachine };

package/dist/runtime/index.js

@@ -1,387 +1,21 @@
-export { BrowserPlayground, OrbPreview, adjustSchemaForMockData, buildMockData, clearSchemaCache, prepareSchemaForPreview, useResolvedSchema, useTraitStateMachine } from '../chunk-QJIAJ6EH.js';
+export { BehaviorValueFrame } from '../chunk-D4NAA2JW.js';
+export { OrbitalPluginHost, TraitValueFrame, TraitValueMountProvider, useDeclaredCaptureTable, useOrbitalPluginHost } from '../chunk-WBWXBA5H.js';
 export { assertUniqueSlotsPerHost } from '../chunk-O2EIWXWE.js';
-import '../chunk-N7JIG57B.js';
-import '../chunk-L3MTZ3RH.js';
-import '../chunk-YYYHH5BA.js';
-export { wrapCallbackForEvent } from '../chunk-E6MWYQVZ.js';
-import '../chunk-J755QADM.js';
-import '../chunk-4ZGXIW3B.js';
-import '../chunk-I5QOYW2Z.js';
-import '../chunk-XJTHMW4G.js';
-import { useEventBus } from '../chunk-CHNC4UYE.js';
-export { PERF_NAMESPACE, clearPerf, perfEnd, perfStart, perfTime, profilerOnRender, usePerfBuffer } from '../chunk-KJGVLXEN.js';
-import '../chunk-Q47ZN2DW.js';
-import '../chunk-64WACXM7.js';
-import '../chunk-723MJUU3.js';
-import '../chunk-LZRW6GXG.js';
+export { BrowserPlayground, OrbPreview, adjustSchemaForMockData, buildMockData, clearSchemaCache, prepareSchemaForPreview, useResolvedSchema, useTraitStateMachine, wrapCallbackForEvent } from '../chunk-G6EFTACU.js';
 import '../chunk-PQKU62LK.js';
+import '../chunk-EDPUQ2ZJ.js';
+import '../chunk-ERDYADVZ.js';
+import '../chunk-DXPCAQJU.js';
+import '../chunk-XJTHMW4G.js';
+import '../chunk-CHNC4UYE.js';
+import '../chunk-L3MTZ3RH.js';
 import '../chunk-PEST66PN.js';
+import '../chunk-7JRWELUC.js';
+export { PERF_NAMESPACE, clearPerf, perfEnd, perfStart, perfTime, profilerOnRender, usePerfBuffer } from '../chunk-N4IJS5DD.js';
+import '../chunk-N23SVGTH.js';
+import '../chunk-64WACXM7.js';
+import '../chunk-CXQENFO2.js';
+import '../chunk-QOV3TUAA.js';
 import '../chunk-QPXIAUJD.js';
 export { EntitySchemaProvider, ServerBridgeProvider, TraitContext, TraitProvider, useEntitySchema, useEntitySchemaOptional, useServerBridge, useTrait, useTraitContext } from '@almadar/ui/providers';
 export { createClientEffectHandlers } from '@almadar/runtime';
-import { createContext, useMemo, useState, useRef, useCallback, useContext, useEffect } from 'react';
-import { OrbitalServerRuntime } from '@almadar/runtime/OrbitalServerRuntime';
-import { UI_SLOTS } from '@almadar/core';
-import { createLogger } from '@almadar/logger';
-import { useTranslate } from '@almadar/ui/hooks';
-import { useUISlots } from '@almadar/ui/context';
-import { jsxs, jsx } from 'react/jsx-runtime';
-
-var log = createLogger("almadar:ui:plugin-host");
-var UI_SLOT_SET = new Set(UI_SLOTS);
-function isUISlot(value) {
-  return UI_SLOT_SET.has(value);
-}
-var OrbitalPluginHostContext = createContext(null);
-function useOrbitalPluginHostContext(caller) {
-  const ctx = useContext(OrbitalPluginHostContext);
-  if (!ctx) {
-    throw new Error(`${caller} must be used within an <OrbitalPluginHost>.`);
-  }
-  return ctx;
-}
-function isTraitState(value) {
-  return value !== void 0 && typeof value.currentState === "string";
-}
-function toTraitState(runtime, orbital, trait, stateName, lastEvent) {
-  if (runtime) {
-    const raw = runtime.getState(orbital, trait);
-    if (isTraitState(raw)) return raw;
-  }
-  return { traitName: trait, currentState: stateName, previousState: null, lastEvent, context: {} };
-}
-function isKeymapValue(value) {
-  if (value === null || value === void 0 || typeof value !== "object" || Array.isArray(value)) return false;
-  return Object.values(value).every((entry) => Array.isArray(entry) && entry.every((k) => typeof k === "string"));
-}
-function findInlineTrait(schema, orbitalName, traitName) {
-  const orbital = schema.orbitals.find((o) => o.name === orbitalName);
-  if (!orbital) return void 0;
-  for (const ref of orbital.traits) {
-    if (typeof ref === "string") continue;
-    if ("ref" in ref) continue;
-    if (ref.name === traitName) return ref;
-  }
-  return void 0;
-}
-function readKeymapConfig(trait, knob) {
-  const declared = trait?.config?.[knob]?.default;
-  return isKeymapValue(declared) ? declared : {};
-}
-function traitNamesOf(orbital) {
-  const names = [];
-  for (const ref of orbital.traits) {
-    if (typeof ref === "string") {
-      names.push(ref);
-    } else if ("ref" in ref) {
-      if (ref.name) names.push(ref.name);
-    } else {
-      names.push(ref.name);
-    }
-  }
-  return names;
-}
-function useDeclaredCaptureTable(opts) {
-  const { pluginId, orbital, trait, keymapKnob = "keymap", target = "shell" } = opts;
-  const ctx = useOrbitalPluginHostContext("useDeclaredCaptureTable");
-  return useMemo(() => {
-    const schema = ctx.getPluginSchema(pluginId);
-    const inlineTrait = schema ? findInlineTrait(schema, orbital, trait) : void 0;
-    const keymap = readKeymapConfig(inlineTrait, keymapKnob);
-    const currentState = ctx.getState(pluginId, orbital, trait)?.currentState;
-    const keys = currentState !== void 0 ? keymap[currentState] ?? [] : [];
-    const entry = { mode: currentState ?? "unknown", keys: new Set(keys) };
-    const targets = Array.isArray(target) ? target : [target];
-    const table = {};
-    for (const t of targets) table[t] = entry;
-    return table;
-  }, [ctx, pluginId, orbital, trait, keymapKnob, target]);
-}
-function useOrbitalPluginHost() {
-  const ctx = useOrbitalPluginHostContext("useOrbitalPluginHost");
-  return { getState: ctx.getState, lastEvent: ctx.lastEvent, errors: ctx.errors };
-}
-function buildMockEffectHandlers(opts) {
-  const { pluginId, denySet, slotsRef, renderedSlotsRef, navigateRef } = opts;
-  const handlers = {
-    renderUI: (slot, pattern, props, priority) => {
-      if (!isUISlot(slot)) {
-        log.warn("renderUI:unknown-slot", { pluginId, slot });
-        return;
-      }
-      if (pattern === null) {
-        slotsRef.current.clearBySource(slot, pluginId);
-        return;
-      }
-      renderedSlotsRef.current.add(slot);
-      slotsRef.current.render({ target: slot, pattern: pattern.type, props, priority, sourceTrait: pluginId });
-    }
-  };
-  if (denySet.has("navigate")) {
-    handlers.navigate = (path) => log.warn("navigate:denied", { pluginId, path });
-  } else if (navigateRef.current) {
-    handlers.navigate = (path) => navigateRef.current?.(path);
-  }
-  if (denySet.has("persist")) {
-    handlers.persist = async (action, entityType) => {
-      log.warn("persist:denied", { pluginId, action, entityType });
-      return void 0;
-    };
-  }
-  if (denySet.has("call-service")) {
-    handlers.callService = async (service, action) => {
-      log.warn("call-service:denied", { pluginId, service, action });
-      return null;
-    };
-  }
-  return handlers;
-}
-function PluginRuntimeMount({
-  plugin,
-  mode,
-  transport,
-  deny,
-  navigate,
-  onTransition,
-  onDispatched,
-  onError
-}) {
-  const bus = useEventBus();
-  const { locale } = useTranslate();
-  const slots = useUISlots();
-  const slotsRef = useRef(slots);
-  slotsRef.current = slots;
-  const renderedSlotsRef = useRef(/* @__PURE__ */ new Set());
-  const navigateRef = useRef(navigate);
-  navigateRef.current = navigate;
-  const [mockRuntime] = useState(() => {
-    if (mode !== "mock") return void 0;
-    return new OrbitalServerRuntime({
-      mode: "mock",
-      debug: false,
-      effectHandlers: buildMockEffectHandlers({
-        pluginId: plugin.id,
-        denySet: new Set(deny ?? []),
-        slotsRef,
-        renderedSlotsRef,
-        navigateRef
-      })
-    });
-  });
-  const registrationReady = useMemo(() => {
-    if (mockRuntime) return mockRuntime.register(plugin.schema);
-    if (mode === "server" && transport) return transport.register(plugin.schema);
-    return Promise.resolve();
-  }, [mockRuntime, transport, mode, plugin.schema]);
-  useEffect(() => {
-    if (mode === "server" && !transport) {
-      onError(plugin.id, 'OrbitalPluginHost: mode "server" requires a transport');
-    }
-  }, [mode, transport, plugin.id, onError]);
-  const teardownTimerRef = useRef(null);
-  useEffect(() => {
-    if (teardownTimerRef.current !== null) {
-      clearTimeout(teardownTimerRef.current);
-      teardownTimerRef.current = null;
-    }
-    return () => {
-      teardownTimerRef.current = setTimeout(() => {
-        teardownTimerRef.current = null;
-        if (mockRuntime) {
-          mockRuntime.unregisterAll();
-        } else if (mode === "server" && transport) {
-          void transport.unregister();
-        }
-        for (const slot of renderedSlotsRef.current) {
-          slotsRef.current.clearBySource(slot, plugin.id);
-        }
-      }, 0);
-    };
-  }, [mockRuntime, transport, mode, plugin.id]);
-  const ownOrbitals = useMemo(
-    () => 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 = snapshotAllStates();
-      if (states.length > 0) onDispatched(plugin.id, null, states);
-    }).catch((err) => {
-      if (!cancelled) onError(plugin.id, err instanceof Error ? err.message : String(err));
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [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;
-      let response;
-      if (mockRuntime) {
-        response = await mockRuntime.processOrbitalEvent(row.orbital, {
-          event: row.trigger,
-          payload,
-          targetTrait: row.trait,
-          locale
-        });
-      } else if (mode === "server" && transport) {
-        response = await transport.send(row.orbital, { event: row.trigger, payload, locale });
-      } else {
-        return;
-      }
-      if (!response.success) {
-        onError(plugin.id, response.error ?? `${plugin.id}: ${row.trigger} failed`);
-      }
-      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 = [];
-      for (const [traitName, stateName] of Object.entries(response.states)) {
-        states.push([row.orbital, traitName, toTraitState(mockRuntime, row.orbital, traitName, stateName, row.trigger)]);
-        onTransition?.(plugin.id, row.orbital, traitName, stateName);
-      }
-      onDispatched(plugin.id, row.trigger, states);
-    },
-    [registrationReady, mockRuntime, mode, transport, locale, plugin, bus, ownOrbitals, inboundBusEvents, onError, onTransition, onDispatched]
-  );
-  useEffect(() => {
-    const unsubs = plugin.inbound.map(
-      (row) => bus.on(`UI:${row.busEvent}`, (event) => {
-        void dispatch(row, event.payload).catch((err) => {
-          onError(plugin.id, err instanceof Error ? err.message : String(err));
-        });
-      })
-    );
-    return () => {
-      for (const unsub of unsubs) unsub();
-    };
-  }, [bus, plugin, dispatch, onError]);
-  return null;
-}
-function OrbitalPluginHost({
-  plugins,
-  mode = "mock",
-  transport,
-  deny,
-  navigate,
-  onTransition,
-  children
-}) {
-  const [tick, setTick] = useState(0);
-  const [errors, setErrors] = useState({});
-  const statesRef = useRef(/* @__PURE__ */ new Map());
-  const lastEventRef = useRef(/* @__PURE__ */ new Map());
-  const pluginSchemas = useMemo(
-    () => new Map(plugins.map((plugin) => [plugin.id, plugin.schema])),
-    [plugins]
-  );
-  const handleDispatched = useCallback(
-    (pluginId, trigger, states) => {
-      if (trigger !== null) {
-        lastEventRef.current.set(pluginId, trigger);
-      }
-      let byKey = statesRef.current.get(pluginId);
-      if (!byKey) {
-        byKey = /* @__PURE__ */ new Map();
-        statesRef.current.set(pluginId, byKey);
-      }
-      for (const [orbital, trait, state] of states) {
-        byKey.set(`${orbital}.${trait}`, state);
-      }
-      setTick((t) => t + 1);
-    },
-    []
-  );
-  const handleError = useCallback((pluginId, message) => {
-    setErrors((prev) => prev[pluginId] === message ? prev : { ...prev, [pluginId]: message });
-  }, []);
-  const contextValue = useMemo(
-    () => ({
-      getState: (pluginId, orbital, trait) => statesRef.current.get(pluginId)?.get(`${orbital}.${trait}`),
-      lastEvent: (pluginId) => lastEventRef.current.get(pluginId),
-      errors,
-      tick,
-      getPluginSchema: (pluginId) => pluginSchemas.get(pluginId)
-    }),
-    [errors, tick, pluginSchemas]
-  );
-  return /* @__PURE__ */ jsxs(OrbitalPluginHostContext.Provider, { value: contextValue, children: [
-    plugins.map((plugin) => /* @__PURE__ */ jsx(
-      PluginRuntimeMount,
-      {
-        plugin,
-        mode,
-        transport,
-        deny,
-        navigate,
-        onTransition,
-        onDispatched: handleDispatched,
-        onError: handleError
-      },
-      plugin.id
-    )),
-    children ?? null
-  ] });
-}
-
-export { OrbitalPluginHost, useDeclaredCaptureTable, useOrbitalPluginHost };