@almadar/ui 6.59.0 → 6.62.0

package/dist/chunk-WBWXBA5H.js

@@ -0,0 +1,434 @@
+import { LoadingState, ErrorState, UISlotComponent } from './chunk-G6EFTACU.js';
+import { useEventBus } from './chunk-CHNC4UYE.js';
+import { createContext, useMemo, useState, useRef, useCallback, useContext, useEffect } from 'react';
+import { UISlotProvider, useUISlots } from '@almadar/ui/context';
+import { OrbitalServerRuntime } from '@almadar/runtime/OrbitalServerRuntime';
+import { UI_SLOTS } from '@almadar/core';
+import { createLogger } from '@almadar/logger';
+import { useTranslate } from '@almadar/ui/hooks';
+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);
+      const { type, ...inline } = pattern;
+      slotsRef.current.render({
+        target: slot,
+        pattern: type,
+        props: { ...inline, ...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
+  ] });
+}
+var TraitValueMountContext = createContext(null);
+function TraitValueMountProvider({ host, children }) {
+  return /* @__PURE__ */ jsx(TraitValueMountContext.Provider, { value: host, children });
+}
+function initEventOf(key) {
+  return `TRAIT_VALUE_MOUNTED:${key}`;
+}
+function MountedInit({ event }) {
+  const bus = useEventBus();
+  useEffect(() => {
+    bus.emit(`UI:${event}`, {});
+  }, [bus, event]);
+  return null;
+}
+function TraitValueFrame({ value }) {
+  const host = useContext(TraitValueMountContext);
+  const key = useMemo(() => JSON.stringify(value), [value]);
+  const latest = useRef(value);
+  latest.current = value;
+  const [state, setState] = useState({ status: "loading" });
+  useEffect(() => {
+    const current = latest.current;
+    if (host === null) {
+      setState({ status: "error", message: `No trait-value host is configured to mount ${current.behavior}.traits.${current.trait}` });
+      return;
+    }
+    let live = true;
+    setState({ status: "loading" });
+    void host.mount(current).then((result) => {
+      if (!live) return;
+      if (!result.ok) {
+        const detail = (result.errors ?? []).map((e) => `${e.code}: ${e.message}`).join("\n");
+        setState({ status: "error", message: detail.length > 0 ? `${result.error}
+${detail}` : result.error });
+        return;
+      }
+      const initEvent = initEventOf(key);
+      setState({
+        status: "ready",
+        initEvent,
+        plugin: {
+          id: key,
+          schema: result.mounted.schema,
+          inbound: [{ busEvent: initEvent, orbital: result.mounted.orbital, trait: result.mounted.trait, trigger: "INIT" }]
+        }
+      });
+    });
+    return () => {
+      live = false;
+    };
+  }, [host, key]);
+  if (state.status === "loading") return /* @__PURE__ */ jsx(LoadingState, {});
+  if (state.status === "error") return /* @__PURE__ */ jsx(ErrorState, { message: state.message });
+  return /* @__PURE__ */ jsx(UISlotProvider, { children: /* @__PURE__ */ jsxs(OrbitalPluginHost, { plugins: [state.plugin], mode: host?.mode ?? "mock", transport: host?.transport, children: [
+    /* @__PURE__ */ jsx(MountedInit, { event: state.initEvent }),
+    /* @__PURE__ */ jsx(UISlotComponent, { slot: "main" })
+  ] }) });
+}
+var TraitValueFrame_default = TraitValueFrame;
+
+export { OrbitalPluginHost, TraitValueFrame, TraitValueFrame_default, TraitValueMountContext, TraitValueMountProvider, useDeclaredCaptureTable, useOrbitalPluginHost };

package/dist/{chunk-V3FGTQUE.js → chunk-ZR45FGW3.js}

@@ -134,7 +134,13 @@ var SURFACE_VARS = [
   { cssVar: "--surface-card-image", key: "cardImage" },
   { cssVar: "--surface-page-image", key: "pageImage" },
   { cssVar: "--surface-page-image-size", key: "pageImageSize" },
-  { cssVar: "--surface-diagram", key: "diagram" }
+  { cssVar: "--surface-diagram", key: "diagram" },
+  { cssVar: "--surface-edge-mask", key: "edgeMask" },
+  { cssVar: "--surface-edge-height", key: "edgeHeight" },
+  { cssVar: "--surface-texture-mask", key: "textureMask" },
+  { cssVar: "--surface-texture-size", key: "textureSize" },
+  { cssVar: "--surface-accent-image", key: "accentImage" },
+  { cssVar: "--surface-scrim", key: "scrim" }
 ];
 var DIAGRAM_VARS = [
   { cssVar: "--diagram-stroke-thin", key: "strokeThin" },

package/dist/{cn-DIql5232.d.ts → cn-CDIhHCUC.d.ts}

@@ -135,12 +135,14 @@ declare const BloomQuizBlock: React__default.FC<BloomQuizBlockProps>;
 /**
  * CodeRunnerPanel Organism Component
  *
- * Editable code block with Run/Reset buttons and simulated terminal output.
- * Real execution is a future concern; callers supply a simulation function via
- * `onRun`. Emits `UI:RUN_CODE { language, exitCode }` on every run attempt.
+ * Editable code block with Run/Reset buttons and a terminal output pane.
+ * Running is the program's job: Run emits the declared `runEvent` request and the
+ * program binds the result back through `output` / `running` / `error`.
  *
  * Event Contract:
- * - Emits: UI:RUN_CODE { language, exitCode, error? }
+ * - Emits: UI:<runEvent> { code, language, runId? } on Run
+ * - Emits: UI:<resetEvent> { runId? } on Reset (when declared)
+ * - Emits: UI:COPY_CODE { language, success } on Copy
  * - entityAware: false
  */
 
@@ -160,16 +162,26 @@ interface CodeRunnerPanelProps extends Omit<React__default.AriaAttributes, keyof
     code: string;
     /** Programming language for syntax highlighting */
     language: string;
-    /** Whether the panel allows running (false = read-only code block) */
+    /** Whether the panel is editable and runnable (default false = read-only code block) */
     runnable?: boolean;
-    /**
-     * Simulate executing the code. Omit to render a read-only block.
-     * Real execution is a separate future track — this callback supplies
-     * deterministic simulated output for UI feedback.
-     */
-    onRun?: (code: string) => Promise<CodeSimulationOutput>;
-    /** Event name to emit on run (emitted as `UI:<runEvent>`). Defaults to 'RUN_CODE'. */
-    runEvent?: string;
+    /** Event emitted on Run as `UI:<runEvent>` with `{ code, language, runId }`. Defaults to 'RUN_CODE'. */
+    runEvent?: EventEmit<{
+        code: string;
+        language: string;
+        runId: string;
+    }>;
+    /** Event emitted on Reset as `UI:<resetEvent>` with `{ runId }`; Reset only restores the code when absent. */
+    resetEvent?: EventEmit<{
+        runId: string;
+    }>;
+    /** Identifies this panel in its run/reset payloads (e.g. a lesson segment); empty when one panel stands alone. */
+    runId?: string;
+    /** The program's result for the last run, bound back into the panel. */
+    output?: CodeSimulationOutput | null;
+    /** True while the program is running the code. */
+    running?: boolean;
+    /** A run failure message from the program; replaces the output body. */
+    error?: string | null;
     /** Additional CSS classes */
     className?: string;
 }
@@ -280,10 +292,22 @@ interface SegmentRendererProps extends Omit<React__default.AriaAttributes, keyof
     /** User progress for restoring activation/reflection state */
     userProgress?: LessonUserProgress;
     /**
-     * Simulate executing runnable code blocks. Omit to render runnable blocks
-     * as read-only. Real execution is a future track.
+     * Event a runnable code block emits on Run (`{ code, language, runId }`, runId = the segment
+     * index). Omit to render runnable blocks read-only.
      */
-    onRunCodeSimulation?: (code: string, language: string) => Promise<CodeSimulationOutput>;
+    runCodeEvent?: EventEmit<{
+        code: string;
+        language: string;
+        runId: string;
+    }>;
+    /** Event a runnable code block emits on Reset (`{ runId }`). */
+    resetCodeEvent?: EventEmit<{
+        runId: string;
+    }>;
+    /** The program's run results, keyed by segment runId. */
+    codeOutputs?: Record<string, CodeSimulationOutput>;
+    /** The runId the program is currently running. */
+    runningCode?: string;
     /**
      * Optional render slot for `visualization` segment types. When not provided,
      * visualization segments are silently skipped. Callers can wire this to any