@almadar/ui 6.5.0 → 6.6.0

package/dist/runtime/index.d.cts

@@ -3,12 +3,12 @@ import { EventPayload, ServiceParams, ResolvedTraitBinding, ResolvedPage, Resolv
 export { ResolvedEntity, ResolvedIR, ResolvedPage, ResolvedTrait, ResolvedTraitBinding } from '@almadar/core';
 import * as _almadar_runtime from '@almadar/runtime';
 import { TraitState, EffectHandlers } from '@almadar/runtime';
-import '../useEventBus-Ckr4wqW3.cjs';
+import { K as KeyCaptureTable } from '../useKeyboardRouter-DQEE_9mq.cjs';
 import { c as useUISlots } from '../UISlotContext-BlRDbHDy.cjs';
-import { E as EntityBindingSource, S as ServerBridgeTransport } from '../EntityBindingContext-0Evn_LcT.cjs';
-export { a as EntitySchemaContextValue, b as EntitySchemaProvider, c as EntitySchemaProviderProps, d as ServerBridgeContextValue, e as ServerBridgeProvider, f as ServerClientEffect, T as TraitContext, g as TraitContextValue, h as TraitInstance, i as TraitProvider, j as TraitProviderProps, u as useEntitySchema, k as useEntitySchemaOptional, l as useServerBridge, m as useTrait, n as useTraitContext } from '../EntityBindingContext-0Evn_LcT.cjs';
+import { a as EntityBindingSource, h as ServerBridgeTransport } from '../EntityBindingContext-Bn3ePJQC.cjs';
+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 from 'react';
+import React__default, { ReactNode } from 'react';
 export { p as profilerOnRender, u as usePerfBuffer } from '../perf-DaVdsbU0.cjs';
 import '../event-bus-types-Bl78kokd.cjs';
 import '../useUISlots-GNwGLlW2.cjs';
@@ -309,7 +309,79 @@ interface BrowserPlaygroundProps {
     height?: string;
     /** CSS class for the outer container. */
     className?: string;
+    /** Pause the in-process runtime's tick scheduler. Default: undefined (running, same as today). */
+    paused?: boolean;
 }
-declare function BrowserPlayground({ schema, mode, initialPagePath, height, className, }: BrowserPlaygroundProps): React__default.ReactElement;
+declare function BrowserPlayground({ schema, mode, initialPagePath, height, className, paused, }: BrowserPlaygroundProps): React__default.ReactElement;
 
-export { BrowserPlayground, type BrowserPlaygroundProps, type ClientEventBus, type CreateClientEffectHandlersOptions, OrbPreview, type OrbPreviewProps, type ResolvedSchemaResult, ServerBridgeTransport, type SlotPatternEntry, type SlotSetter, type SlotSource, type TraitStateMachineResult, type UseTraitStateMachineOptions, clearSchemaCache, createClientEffectHandlers, useResolvedSchema, useTraitStateMachine };
+/**
+ * OrbitalPluginHost — runs an ordinary behavior headless against the
+ * AMBIENT event bus + slot provider (Almadar Studio V4 §14 plan, Part F1).
+ *
+ * A "plugin" is not a new kind of artifact: it is a `.lolo` behavior a host
+ * chooses to run in its own `OrbitalServerRuntime`, wired to the SAME bus
+ * and slots every other UI component uses. One runtime per plugin (mirrors
+ * `BrowserPlayground`'s single-schema mount, generalized over a list).
+ * Default policy denies nothing — a plugin has the full behavior power a
+ * preview has (in-memory persist, mock services); `deny` is an opt-in
+ * host policy, never a default sandbox.
+ *
+ * @packageDocumentation
+ */
+
+/** Verbs a host may deny. Never includes `emit` — the runtime's own emit
+ *  handler drives the internal `listens` cascade and must never be replaced. */
+type PluginHostDenyVerb = 'persist' | 'call-service' | 'navigate' | 'notify';
+/** One bus-event → orbital-event wiring: `UI:<busEvent>` dispatches `trigger` at `orbital`/`trait`. */
+interface PluginHostInbound {
+    busEvent: string;
+    orbital: string;
+    trait: string;
+    trigger: string;
+}
+interface PluginHostPlugin {
+    id: string;
+    schema: OrbitalSchema;
+    inbound: PluginHostInbound[];
+}
+interface OrbitalPluginHostProps {
+    plugins: PluginHostPlugin[];
+    /** 'mock' (default): in-memory persist, mock services — full behavior power, as any preview.
+     *  'server': dispatch through `transport` instead of a local runtime, as `AlmadarApp`. */
+    mode?: 'mock' | 'server';
+    /** Required when `mode === 'server'`. */
+    transport?: ServerBridgeTransport;
+    /** OPTIONAL policy: verbs listed here are denied with a logged warning, never a throw. Default: none denied. */
+    deny?: PluginHostDenyVerb[];
+    navigate?: (path: string) => void;
+    notify?: (message: string, type?: string) => void;
+    onTransition?: (pluginId: string, orbital: string, trait: string, state: string) => void;
+    children?: ReactNode;
+}
+/**
+ * Reads the declared `keymap` config knob off the plugin's own trait and the
+ * live `currentState`, so `useKeyboardRouter`'s capture table always follows
+ * the trait's actual mode. Re-derives whenever the host records a new
+ * transition (the context's `tick`).
+ */
+declare function useDeclaredCaptureTable(opts: {
+    pluginId: string;
+    orbital: string;
+    trait: string;
+    keymapKnob?: string;
+    target?: string;
+}): KeyCaptureTable;
+declare function useOrbitalPluginHost(): {
+    getState: (pluginId: string, orbital: string, trait: string) => TraitState | undefined;
+    lastEvent: (pluginId: string) => string | undefined;
+    errors: Readonly<Record<string, string>>;
+};
+/**
+ * Mounts one headless `OrbitalServerRuntime` per plugin against the ambient
+ * event bus + slot provider. Renders nothing of its own besides an optional
+ * `children` passthrough — MUST be mounted inside `EventBusProvider` +
+ * `UISlotProvider`.
+ */
+declare function OrbitalPluginHost({ plugins, mode, transport, deny, navigate, notify, onTransition, children, }: OrbitalPluginHostProps): React__default.ReactElement;
+
+export { BrowserPlayground, type BrowserPlaygroundProps, type ClientEventBus, type CreateClientEffectHandlersOptions, OrbPreview, type OrbPreviewProps, OrbitalPluginHost, type OrbitalPluginHostProps, type PluginHostDenyVerb, type PluginHostInbound, type PluginHostPlugin, type ResolvedSchemaResult, ServerBridgeTransport, type SlotPatternEntry, type SlotSetter, type SlotSource, type TraitStateMachineResult, type UseTraitStateMachineOptions, clearSchemaCache, createClientEffectHandlers, useDeclaredCaptureTable, useOrbitalPluginHost, useResolvedSchema, useTraitStateMachine };

package/dist/runtime/index.d.ts

@@ -3,12 +3,12 @@ import { EventPayload, ServiceParams, ResolvedTraitBinding, ResolvedPage, Resolv
 export { ResolvedEntity, ResolvedIR, ResolvedPage, ResolvedTrait, ResolvedTraitBinding } from '@almadar/core';
 import * as _almadar_runtime from '@almadar/runtime';
 import { TraitState, EffectHandlers } from '@almadar/runtime';
-import '../useEventBus-CQWyAWpK.js';
+import { K as KeyCaptureTable } from '../useKeyboardRouter-D84cNWmA.js';
 import { c as useUISlots } from '../UISlotContext-CB89mv7N.js';
-import { E as EntityBindingSource, S as ServerBridgeTransport } from '../EntityBindingContext-0Evn_LcT.js';
-export { a as EntitySchemaContextValue, b as EntitySchemaProvider, c as EntitySchemaProviderProps, d as ServerBridgeContextValue, e as ServerBridgeProvider, f as ServerClientEffect, T as TraitContext, g as TraitContextValue, h as TraitInstance, i as TraitProvider, j as TraitProviderProps, u as useEntitySchema, k as useEntitySchemaOptional, l as useServerBridge, m as useTrait, n as useTraitContext } from '../EntityBindingContext-0Evn_LcT.js';
+import { a as EntityBindingSource, h as ServerBridgeTransport } from '../EntityBindingContext-Bn3ePJQC.js';
+export { b as EntitySchemaContextValue, c as EntitySchemaProvider, d as EntitySchemaProviderProps, e as ServerBridgeContextValue, f as ServerBridgeProvider, i as ServerClientEffect, T as TraitContext, k as TraitContextValue, l as TraitInstance, m as TraitProvider, n as TraitProviderProps, o as useEntitySchema, p as useEntitySchemaOptional, q as useServerBridge, r as useTrait, s as useTraitContext } from '../EntityBindingContext-Bn3ePJQC.js';
 export { PERF_NAMESPACE, PerfEntry, PreparedPreviewSchema, adjustSchemaForMockData, buildMockData, clearPerf, perfEnd, perfStart, perfTime, prepareSchemaForPreview, wrapCallbackForEvent } from '@almadar/runtime/ui';
-import React__default from 'react';
+import React__default, { ReactNode } from 'react';
 export { p as profilerOnRender, u as usePerfBuffer } from '../perf-DaVdsbU0.js';
 import '../event-bus-types-Bl78kokd.js';
 import '../useUISlots-GNwGLlW2.js';
@@ -309,7 +309,79 @@ interface BrowserPlaygroundProps {
     height?: string;
     /** CSS class for the outer container. */
     className?: string;
+    /** Pause the in-process runtime's tick scheduler. Default: undefined (running, same as today). */
+    paused?: boolean;
 }
-declare function BrowserPlayground({ schema, mode, initialPagePath, height, className, }: BrowserPlaygroundProps): React__default.ReactElement;
+declare function BrowserPlayground({ schema, mode, initialPagePath, height, className, paused, }: BrowserPlaygroundProps): React__default.ReactElement;
 
-export { BrowserPlayground, type BrowserPlaygroundProps, type ClientEventBus, type CreateClientEffectHandlersOptions, OrbPreview, type OrbPreviewProps, type ResolvedSchemaResult, ServerBridgeTransport, type SlotPatternEntry, type SlotSetter, type SlotSource, type TraitStateMachineResult, type UseTraitStateMachineOptions, clearSchemaCache, createClientEffectHandlers, useResolvedSchema, useTraitStateMachine };
+/**
+ * OrbitalPluginHost — runs an ordinary behavior headless against the
+ * AMBIENT event bus + slot provider (Almadar Studio V4 §14 plan, Part F1).
+ *
+ * A "plugin" is not a new kind of artifact: it is a `.lolo` behavior a host
+ * chooses to run in its own `OrbitalServerRuntime`, wired to the SAME bus
+ * and slots every other UI component uses. One runtime per plugin (mirrors
+ * `BrowserPlayground`'s single-schema mount, generalized over a list).
+ * Default policy denies nothing — a plugin has the full behavior power a
+ * preview has (in-memory persist, mock services); `deny` is an opt-in
+ * host policy, never a default sandbox.
+ *
+ * @packageDocumentation
+ */
+
+/** Verbs a host may deny. Never includes `emit` — the runtime's own emit
+ *  handler drives the internal `listens` cascade and must never be replaced. */
+type PluginHostDenyVerb = 'persist' | 'call-service' | 'navigate' | 'notify';
+/** One bus-event → orbital-event wiring: `UI:<busEvent>` dispatches `trigger` at `orbital`/`trait`. */
+interface PluginHostInbound {
+    busEvent: string;
+    orbital: string;
+    trait: string;
+    trigger: string;
+}
+interface PluginHostPlugin {
+    id: string;
+    schema: OrbitalSchema;
+    inbound: PluginHostInbound[];
+}
+interface OrbitalPluginHostProps {
+    plugins: PluginHostPlugin[];
+    /** 'mock' (default): in-memory persist, mock services — full behavior power, as any preview.
+     *  'server': dispatch through `transport` instead of a local runtime, as `AlmadarApp`. */
+    mode?: 'mock' | 'server';
+    /** Required when `mode === 'server'`. */
+    transport?: ServerBridgeTransport;
+    /** OPTIONAL policy: verbs listed here are denied with a logged warning, never a throw. Default: none denied. */
+    deny?: PluginHostDenyVerb[];
+    navigate?: (path: string) => void;
+    notify?: (message: string, type?: string) => void;
+    onTransition?: (pluginId: string, orbital: string, trait: string, state: string) => void;
+    children?: ReactNode;
+}
+/**
+ * Reads the declared `keymap` config knob off the plugin's own trait and the
+ * live `currentState`, so `useKeyboardRouter`'s capture table always follows
+ * the trait's actual mode. Re-derives whenever the host records a new
+ * transition (the context's `tick`).
+ */
+declare function useDeclaredCaptureTable(opts: {
+    pluginId: string;
+    orbital: string;
+    trait: string;
+    keymapKnob?: string;
+    target?: string;
+}): KeyCaptureTable;
+declare function useOrbitalPluginHost(): {
+    getState: (pluginId: string, orbital: string, trait: string) => TraitState | undefined;
+    lastEvent: (pluginId: string) => string | undefined;
+    errors: Readonly<Record<string, string>>;
+};
+/**
+ * Mounts one headless `OrbitalServerRuntime` per plugin against the ambient
+ * event bus + slot provider. Renders nothing of its own besides an optional
+ * `children` passthrough — MUST be mounted inside `EventBusProvider` +
+ * `UISlotProvider`.
+ */
+declare function OrbitalPluginHost({ plugins, mode, transport, deny, navigate, notify, onTransition, children, }: OrbitalPluginHostProps): React__default.ReactElement;
+
+export { BrowserPlayground, type BrowserPlaygroundProps, type ClientEventBus, type CreateClientEffectHandlersOptions, OrbPreview, type OrbPreviewProps, OrbitalPluginHost, type OrbitalPluginHostProps, type PluginHostDenyVerb, type PluginHostInbound, type PluginHostPlugin, type ResolvedSchemaResult, ServerBridgeTransport, type SlotPatternEntry, type SlotSetter, type SlotSource, type TraitStateMachineResult, type UseTraitStateMachineOptions, clearSchemaCache, createClientEffectHandlers, useDeclaredCaptureTable, useOrbitalPluginHost, useResolvedSchema, useTraitStateMachine };