@almadar/ui 5.111.0 → 5.113.0

package/dist/runtime/index.d.cts

@@ -0,0 +1,426 @@
+import * as _almadar_core from '@almadar/core';
+import { EventPayload, ServiceParams, ResolvedTraitBinding, ResolvedPage, ResolvedEntity, ResolvedTrait, ResolvedIR, OrbitalSchema, PatternConfig, FieldValue, EventSource, SExpr, EventPayloadValue, EntityRow, EntityData } from '@almadar/core';
+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 { c as useUISlots } from '../UISlotContext-D8_SoDsD.cjs';
+import { f as ServerBridgeTransport } from '../TraitProvider-YkK6tXDw.cjs';
+export { E as EntitySchemaContextValue, a as EntitySchemaProvider, b as EntitySchemaProviderProps, c as ServerBridgeContextValue, d as ServerBridgeProvider, g as ServerClientEffect, T as TraitContext, i as TraitContextValue, j as TraitInstance, k as TraitProvider, l as TraitProviderProps, u as useEntitySchema, m as useEntitySchemaOptional, n as useServerBridge, o as useTrait, p as useTraitContext } from '../TraitProvider-YkK6tXDw.cjs';
+import { PatternCallbackArg } from '@almadar/core/patterns';
+import React__default, { ProfilerOnRenderCallback } from 'react';
+import '../event-bus-types-Bl78kokd.cjs';
+import '../useUISlots-BesZYMks.cjs';
+
+interface TraitStateMachineResult {
+    /** Current state for each trait */
+    traitStates: Map<string, TraitState>;
+    /** Send an event to trigger a transition */
+    sendEvent: (eventKey: string, payload?: EventPayload) => void;
+    /** Get current state for a specific trait */
+    getTraitState: (traitName: string) => TraitState | undefined;
+    /** Check if a trait can handle an event from its current state */
+    canHandleEvent: (traitName: string, eventKey: string) => boolean;
+}
+interface UseTraitStateMachineOptions {
+    /**
+     * Callback invoked after each event is processed (for server forwarding).
+     *
+     * `dispatchedOrbitals` is the set of orbital names whose traits actually
+     * executed a transition for this event. The server-bridge fan-out should
+     * be scoped to this set; sending the event to other orbitals fires
+     * same-named transitions in unrelated orbitals and stacks their UI into
+     * the wrong slot (gap #11 in `docs/Almadar_Std_Verification.md`). Empty
+     * set means no local transition matched — leave the legacy fallback to
+     * the consumer.
+     */
+    onEventProcessed?: (eventKey: string, payload?: EventPayload, dispatchedOrbitals?: Set<string>) => void | Promise<void>;
+    /** Router navigate function for navigate effects */
+    navigate?: (path: string, params?: Record<string, string>) => void;
+    /** Notification function for notify effects */
+    notify?: (message: string, type?: 'success' | 'error' | 'warning' | 'info') => void;
+    /**
+     * Offline-preview persistence layer. When set, the client runtime merges
+     * `@almadar/runtime` `createServerEffectHandlers` on top of the default
+     * client handlers so `fetch` / `persist` / `set` / `ref` / `deref` /
+     * `swap!` / `atomic` / `callService` run against this adapter — matching
+     * what `OrbitalServerRuntime` would do on the server. Left unset in the
+     * server-bridge path; effects there flow to the real server.
+     */
+    persistence?: _almadar_runtime.PersistenceAdapter;
+    /** Optional consumer `call-service` hook forwarded to the mock server handlers. */
+    callService?: (service: string, action: string, params?: ServiceParams) => Promise<EventPayload>;
+    /**
+     * Trait configs keyed by trait name. Threaded into setTraitConfig so
+     * `@config.X` resolves inside guard expressions on the client. Page-level
+     * `ResolvedTraitBinding`s often arrive without a config (the orbital-level
+     * config doesn't propagate through `@almadar/core`'s page resolver), so the
+     * caller assembles this map from the orbital schema directly.
+     */
+    traitConfigsByName?: Record<string, _almadar_core.TraitConfig>;
+    /**
+     * Trait → orbital map built from `schema.orbitals[].traits[]` by the
+     * caller. Threaded down so bus emits (`UI:Orbital.Trait.Event`) and
+     * subscriptions can carry the qualified `Orbital.Trait` scope —
+     * gap #13 unification. Same mechanism as `traitConfigsByName`: the
+     * orbital boundary doesn't propagate through `@almadar/core`'s
+     * `ResolvedTraitBinding`, so the caller assembles the map directly.
+     */
+    orbitalsByTrait?: Record<string, string>;
+    /**
+     * Set of trait names referenced via `@trait.X` by some sibling
+     * layout in the resolved schema. Slot writes from these traits go
+     * to the per-trait sidecar via `uiSlots.updateTraitContent`; the
+     * layout owns the slot and embeds via `<TraitFrame>`. Mirrors
+     * compiled-path codegen semantics.
+     */
+    embeddedTraits?: ReadonlySet<string>;
+}
+declare function useTraitStateMachine(traitBindings: ResolvedTraitBinding[], uiSlots: ReturnType<typeof useUISlots>, options?: UseTraitStateMachineOptions): TraitStateMachineResult;
+
+/**
+ * useResolvedSchema Hook
+ *
+ * Resolves OrbitalSchema to IR for the OrbitalRuntime.
+ * Uses the shared resolver to ensure consistency with the compiler.
+ *
+ * TRAIT-DRIVEN ARCHITECTURE:
+ * - Pages have traits, NOT sections
+ * - UI is produced by trait effects (render_ui)
+ * - No backwards compatibility with legacy formats
+ *
+ * @packageDocumentation
+ */
+
+interface ResolvedSchemaResult {
+    /** The resolved page (or undefined if not found) */
+    page: ResolvedPage | undefined;
+    /** Trait bindings for this page */
+    traits: ResolvedTraitBinding[];
+    /** Entities used by this page */
+    entities: Map<string, ResolvedEntity>;
+    /** All entities from schema */
+    allEntities: Map<string, ResolvedEntity>;
+    /** All resolved traits */
+    allTraits: Map<string, ResolvedTrait>;
+    /** Loading state */
+    loading: boolean;
+    /** Error message if resolution failed */
+    error: string | null;
+    /** Full IR (for debugging) */
+    ir: ResolvedIR | null;
+}
+/**
+ * Hook to resolve an OrbitalSchema to IR.
+ *
+ * @param schema - The OrbitalSchema to resolve
+ * @param pageName - Optional page name (defaults to first page or initial page)
+ * @returns Resolved schema data including page, traits, and entities
+ */
+declare function useResolvedSchema(schema: OrbitalSchema | null | undefined, pageName?: string): ResolvedSchemaResult;
+/**
+ * Clear the schema resolution cache
+ */
+declare function clearSchemaCache(): void;
+
+/**
+ * One pattern within a slot's accumulated render-ui set, plus any
+ * caller-supplied props that should be merged on top.
+ */
+interface SlotPatternEntry {
+    pattern: PatternConfig;
+    props: Record<string, FieldValue | undefined>;
+}
+/**
+ * The originating trait + state for a slot write. Embedded in the
+ * `useUISlots` SlotContent's metadata so observers (verifier, debugger,
+ * cross-orbital tracer) can attribute every render to the trait that
+ * caused it.
+ */
+interface SlotSource extends EventSource {
+    trait: string;
+    state: string;
+    transition: string;
+    effects: SExpr[];
+    traitDefinition: ResolvedTrait;
+}
+
+/**
+ * Build the runtime wrapper that turns a string-typed callback prop
+ * (e.g. `onTabChange: "TAB_CHANGED"`) into a function the component can
+ * invoke. The wrapper consumes the component's positional callback args
+ * by name and dispatches an OBJECT payload `{ argName: value, ... }` so
+ * the bus carries the trait's declared event payload, not a raw
+ * positional spread. Mirrors the codegen wrapper in
+ * `orbital-shell-typescript/src/codegen/pattern.rs` (C2 compiled path).
+ *
+ * Single-sourcing this logic across runtime and codegen (shared shape,
+ * not shared code — codegen emits string source) is what keeps the two
+ * paths from silently diverging on payload shape.
+ */
+declare function wrapCallbackForEvent(qualifiedEvent: string, callbackArgs: PatternCallbackArg[] | undefined, emit: (eventKey: string, payload?: EventPayload) => void): (...args: EventPayloadValue[]) => void;
+
+/**
+ * Client Effect Handlers Factory
+ *
+ * Creates the standard effect handler set for client-side trait execution.
+ *
+ * @packageDocumentation
+ */
+
+interface ClientEventBus {
+    emit: (type: string, payload?: EventPayload) => void;
+}
+interface SlotSetter {
+    addPattern: (slot: string, pattern: PatternConfig | null, props?: Record<string, FieldValue | undefined>) => void;
+    clearSlot: (slot: string) => void;
+}
+interface CreateClientEffectHandlersOptions {
+    eventBus: ClientEventBus;
+    slotSetter: SlotSetter;
+    navigate?: (path: string, params?: Record<string, string>) => void;
+    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;
+    /**
+     * Live client-entity write target for `[runtime]` entities. `(set
+     * @entity.<field> value)` runs entirely in the browser for in-memory
+     * entities (game boards, wizards): there is no server row to persist to,
+     * so the canonical client `set` must mutate THIS object — the same object
+     * `EffectExecutor` reads `@entity.*` from for the current `executeAll` and
+     * the next tick seeds from. When omitted, `set` is a no-op (bridge mode:
+     * the server owns persistence). One store, read live by render-ui, guards,
+     * and ticks — no guard-vs-render split.
+     */
+    liveEntity?: EntityRow;
+    /**
+     * Optional consumer-supplied call-service handler. When set, it runs
+     * instead of the default mock fallback — use to wire the playground
+     * to real backends. When omitted, `callService` returns a synthetic
+     * mock result so service-atom chains advance end-to-end in offline /
+     * standalone-preview mode (see OrbitalServerRuntime's mock parallel).
+     */
+    callService?: (service: string, action: string, params?: ServiceParams) => Promise<EventPayload>;
+}
+declare function createClientEffectHandlers(options: CreateClientEffectHandlersOptions): EffectHandlers;
+
+/**
+ * OrbPreview Component
+ *
+ * Renders a live preview of an Orbital schema (.orb program).
+ * Uses static imports (no lazy loading) to ensure all providers,
+ * hooks, and components share the same module instances.
+ *
+ * Usage:
+ *   <OrbPreview schema={orbJsonStringOrObject} />
+ *   <OrbPreview schema={schema} serverUrl="/api/orbitals" />
+ *
+ * @packageDocumentation
+ */
+
+interface OrbPreviewProps {
+    /**
+     * The orbital schema. Accepts a JSON string or an `OrbitalSchema` object
+     * from `@almadar/core` (the validated `.orb` program type).
+     */
+    schema: string | OrbitalSchema;
+    /**
+     * Mock entity rows keyed by entity name. The `EntityData` type from
+     * `@almadar/core` is `Record<string, EntityRow[]>` where each row is a
+     * `{ id?: string } & Record<string, FieldValue>`. Ignored if `autoMock`
+     * is set.
+     */
+    mockData?: EntityData;
+    /**
+     * When true, run the schema through `prepareSchemaForPreview` before
+     * rendering: auto-generate mock entity rows and flip two-state INIT
+     * machines so the data state is initial. This is the same pipeline the
+     * playground uses, so consumers (docs MDX, playground) all share one path.
+     *
+     * Ignored when `serverUrl` is set — server-driven previews provide their
+     * own data.
+     */
+    autoMock?: boolean;
+    /** Preview container height. Default: '400px'. */
+    height?: string;
+    /** CSS class for the outer container. */
+    className?: string;
+    /** Server URL for dual execution (e.g. "/api/orbitals"). When set, events are forwarded to the server. */
+    serverUrl?: string;
+    /**
+     * Custom transport for in-process execution. Mutually exclusive with
+     * `serverUrl`. Used by `<BrowserPlayground>` to invoke
+     * `OrbitalServerRuntime.processOrbitalEvent` directly without HTTP.
+     */
+    transport?: ServerBridgeTransport;
+    /**
+     * Initial page path to render (e.g. `/deals`). Resolves against the
+     * schema's `pages[]` to seed `currentPage` so the right orbital's traits
+     * mount on first render. Without this the playground falls back to the
+     * schema's first page binding (gap #13 Phase 5). runtime-verify uses this
+     * to walk DealCreate, NoteCompose, etc. on their owning pages.
+     */
+    initialPagePath?: string;
+    /**
+     * Sandbox mode: the preview's event bus stays context-local and does NOT
+     * register as the global bus. Set when embedded inside a host app (e.g. the
+     * studio canvas) so preview events don't clobber the host's global bus.
+     * Default false (standalone previews own the global bridge).
+     */
+    isolated?: boolean;
+}
+/**
+ * Renders a live preview of an Orbital schema.
+ *
+ * Uses static imports for all runtime components to ensure providers
+ * and hooks share the same module instances (no context duplication).
+ *
+ * @example
+ * ```tsx
+ * <OrbPreview schema={orbJsonString} height="300px" />
+ * <OrbPreview schema={schema} autoMock />
+ * <OrbPreview schema={schema} serverUrl="/api/orbitals" />
+ * ```
+ */
+declare function OrbPreview({ schema, mockData, autoMock, height, className, serverUrl, transport, initialPagePath, isolated, }: OrbPreviewProps): React__default.ReactElement;
+declare namespace OrbPreview {
+    var displayName: string;
+}
+
+/**
+ * BrowserPlayground — in-browser Almadar runtime mount.
+ *
+ * Runs `OrbitalServerRuntime` (mock mode) in-process and threads it through
+ * `<OrbPreview>` via the `ServerBridgeTransport` adapter. Equivalent to
+ * canonical playground-runtime's server-mode mount, but without Express,
+ * fork, or HTTP — invokes `runtime.processOrbitalEvent` directly.
+ *
+ * Same React tree as `runtime-verify` (and apps/builder server-mode) speak,
+ * so any `@almadar/runtime` fix flows in through one bump cycle.
+ *
+ * @example
+ * ```tsx
+ * <BrowserPlayground schema={schema} mode="mock" height="100%" />
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+interface BrowserPlaygroundProps {
+    /** OrbitalSchema to render. */
+    schema: OrbitalSchema;
+    /** Persistence mode for the in-process runtime. Default: 'mock' (Faker-seeded MockPersistenceAdapter). */
+    mode?: 'mock';
+    /** Initial page path to render (forwarded to OrbPreview). */
+    initialPagePath?: string;
+    /** Preview container height. Default: '400px'. */
+    height?: string;
+    /** CSS class for the outer container. */
+    className?: string;
+}
+declare function BrowserPlayground({ schema, mode, initialPagePath, height, className, }: BrowserPlaygroundProps): React__default.ReactElement;
+
+/**
+ * prepareSchemaForPreview
+ *
+ * Single source of truth for the "give an Orbital schema a runnable preview"
+ * pipeline. Used by both:
+ *   * `<OrbPreview autoMock />` (the docs / MDX path)
+ *   * `PlaygroundContent` (the interactive playground)
+ *
+ * Type signature in `@almadar/core` terms:
+ *
+ *   buildMockData          : OrbitalSchema → EntityData
+ *   adjustSchemaForMockData: (OrbitalSchema, EntityData) → OrbitalSchema
+ *   prepareSchemaForPreview: OrbitalSchema → { schema: OrbitalSchema, mockData: EntityData }
+ *
+ * Steps:
+ *   1. `buildMockData` — for each orbital, generate (or pick up from
+ *     `entity.instances`) `EntityRow[]` for that entity.
+ *   2. `adjustSchemaForMockData` — flip two-state INIT machines so the data
+ *      state is initial (e.g. `empty -> hasItems` becomes `hasItems` initial).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Build mock entity rows (`EntityData`) for every orbital in the schema.
+ *
+ * For each orbital's entity:
+ *   * If the entity has an `instances` array (from the schema author),
+ *     use it as-is.
+ *   * Otherwise generate 10 synthetic `EntityRow`s from the field
+ *     definitions via `generateEntityRow`.
+ *
+ * @public
+ */
+declare function buildMockData(schema: OrbitalSchema): EntityData;
+/**
+ * When mock data exists for a trait's linked entity, swap the state
+ * machine's initial state to the state that also handles INIT (the "data
+ * state"). This makes previews land directly in the populated UI.
+ *
+ * Behavior is per-trait:
+ *   * Inline traits with two-state INIT patterns are rewritten.
+ *   * String / object trait refs are left untouched (the resolver handles them).
+ *   * Single-state INIT machines are left untouched.
+ *
+ * @public
+ */
+declare function adjustSchemaForMockData(schema: OrbitalSchema, mockData: EntityData): OrbitalSchema;
+/**
+ * Result of `prepareSchemaForPreview`.
+ *
+ * @public
+ */
+interface PreparedPreviewSchema {
+    /** Schema with state machines flipped so data states are initial. */
+    schema: OrbitalSchema;
+    /** Mock entity rows keyed by entity name — pass to `OrbPreview.mockData`. */
+    mockData: EntityData;
+}
+/**
+ * Run the full preview prep pipeline on a schema.
+ *
+ * Accepts either an already-parsed `OrbitalSchema` or a JSON string.
+ * Returns `{ schema, mockData }` ready to feed `<OrbPreview>`.
+ *
+ * Functional signature:
+ *   `OrbitalSchema | string → { schema: OrbitalSchema, mockData: EntityData }`
+ *
+ * @public
+ */
+declare function prepareSchemaForPreview(input: OrbitalSchema | string): PreparedPreviewSchema;
+
+/**
+ * @almadar/ui/runtime — perf instrumentation
+ *
+ * Ring buffer of timing events for the canvas render path, plus mark/measure
+ * helpers and a React.Profiler onRender callback. All gated behind
+ * `createLogger('almadar:perf:canvas')` so production (LOG_LEVEL >= WARN)
+ * skips both `performance.*` calls and the ring write.
+ */
+
+declare const PERF_NAMESPACE = "almadar:perf:canvas";
+interface PerfEntry {
+    readonly name: string;
+    readonly durationMs: number;
+    readonly ts: number;
+    readonly detail?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Start a phase. Returns an opaque token; pass to {@link perfEnd}.
+ * Returns -1 when the namespace is gated off, so call sites pay only one comparison.
+ */
+declare function perfStart(name: string): number;
+declare function perfEnd(name: string, startToken: number, detail?: Record<string, unknown>): void;
+/** Synchronous wrapper that times a fn end-to-end. */
+declare function perfTime<T>(name: string, fn: () => T, detail?: Record<string, unknown>): T;
+/**
+ * React.Profiler `onRender` callback. Records `actualDuration` per commit.
+ * Phase is `"mount" | "update" | "nested-update"`.
+ */
+declare const profilerOnRender: ProfilerOnRenderCallback;
+/** React hook: returns the current ring snapshot, re-renders on push. */
+declare function usePerfBuffer(): readonly PerfEntry[];
+declare function clearPerf(): void;
+
+export { BrowserPlayground, type BrowserPlaygroundProps, type ClientEventBus, type CreateClientEffectHandlersOptions, OrbPreview, type OrbPreviewProps, PERF_NAMESPACE, type PerfEntry, type PreparedPreviewSchema, type ResolvedSchemaResult, ServerBridgeTransport, type SlotPatternEntry, type SlotSetter, type SlotSource, type TraitStateMachineResult, type UseTraitStateMachineOptions, adjustSchemaForMockData, buildMockData, clearPerf, clearSchemaCache, createClientEffectHandlers, perfEnd, perfStart, perfTime, prepareSchemaForPreview, profilerOnRender, usePerfBuffer, useResolvedSchema, useTraitStateMachine, wrapCallbackForEvent };