@almadar/runtime 6.31.0 → 6.33.0

package/dist/ui/index.d.ts

@@ -0,0 +1,419 @@
+import { UISlot, AnyPatternConfig, ResolvedPatternProps, EventSource, SExpr, ResolvedTrait, EventPayload, EventPayloadValue, OrbitalSchema, EntityData, OrbitalVerificationAPI, BusEvent } from '@almadar/core';
+import { PatternCallbackArg } from '@almadar/core/patterns';
+
+/**
+ * Runtime contract enforcement for renderer implementations.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Error thrown when a renderer implementation violates the
+ * `@almadar/runtime/ui` contract (e.g. a `SlotManager` is missing required
+ * methods).
+ */
+declare class RendererContractViolationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Structured error returned by {@link validateSlotContent} when a slot content
+ * value does not satisfy the runtime contract.
+ */
+interface SlotContentValidationError {
+    /** Human-readable error message. */
+    readonly message: string;
+    /** Dotted path to the offending field, or `'.'` for the root value. */
+    readonly path: string;
+}
+
+/**
+ * Renderer-agnostic slot contract.
+ *
+ * Any UI library (React, Web Components, Vue, etc.) that wants to render an
+ * Almadar orbital schema must provide an implementation of {@link SlotManager}.
+ * The runtime itself is UI-framework blind: it only knows about UISlots and
+ * pattern configs from @almadar/core.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Metadata that attributes a slot write to the trait/transition that produced it.
+ *
+ * Mirrors the shape previously in `@almadar/ui/types/slot-types`, but grounded
+ * entirely in `@almadar/core` types so the contract lives in the runtime layer.
+ */
+interface SlotSource extends EventSource {
+    /** Trait that emitted the render-ui effect. */
+    trait: string;
+    /** State the trait was in when the effect fired. */
+    state: string;
+    /** Transition (or tick) that carried the effect. */
+    transition: string;
+    /** Effects executed during the transition. */
+    effects: SExpr[];
+    /** Resolved trait definition that owns the transition (optional attribution). */
+    traitDefinition?: ResolvedTrait;
+}
+/**
+ * One unit of content the runtime asks a renderer to place in a named slot.
+ *
+ * A `null` pattern means "clear this slot". Optional `props` carry resolved
+ * pattern props (e.g. from a render-ui effect's 4th tuple element). `source`
+ * is optional metadata for debug/verification attribution.
+ */
+interface SlotContent {
+    /** Target UI slot from the core UISlot union. */
+    slot: UISlot;
+    /** Pattern config to render, or null to clear the slot. */
+    pattern: AnyPatternConfig | null;
+    /** Resolved props merged on top of the pattern config. */
+    props?: ResolvedPatternProps;
+    /** Attribution metadata for tracing/debugging. */
+    source?: SlotSource;
+}
+/**
+ * Minimal slot-management contract every UI renderer must satisfy.
+ *
+ * The runtime's client effect handlers call `setContent`/`clearSlot` in
+ * response to `render-ui` effects. The renderer owns the actual DOM/
+ * component-tree update, subscription handling, and multi-source merging
+ * policy (e.g. stacking N trait writes into one synthetic container).
+ */
+interface SlotManager {
+    /** Return the latest content for a slot, or undefined if empty. */
+    getContent(slot: UISlot): SlotContent | undefined;
+    /** Place (or replace) content for a slot. */
+    setContent(content: SlotContent): void;
+    /** Clear a slot by writing a null pattern. */
+    clearSlot(slot: UISlot): void;
+    /** Snapshot of all currently populated slots. */
+    getAllSlots(): ReadonlyMap<UISlot, SlotContent>;
+    /** Subscribe to slot changes. Returns an unsubscribe function. */
+    subscribe(listener: (slot: UISlot, content: SlotContent | undefined) => void): () => void;
+}
+/**
+ * Extended slot manager contract that supports the multi-source aggregation
+ * and per-trait sidecar model used by the React `useUISlots` implementation.
+ *
+ * Renderers that need to support `@trait.X` embedding and multiple traits
+ * writing the same slot should implement this interface. The base
+ * {@link SlotManager} remains the minimal contract for simple renderers.
+ */
+interface MultiSourceSlotManager extends SlotManager {
+    /** Return the latest content a given trait rendered, or undefined if none. */
+    getTraitContent(traitName: string): SlotContent | undefined;
+    /** Subscribe to changes in a specific trait's render output. */
+    subscribeTrait(traitName: string, listener: (content: SlotContent | undefined) => void): () => void;
+    /**
+     * Update the per-trait sidecar without writing to a slot.
+     *
+     * Used for embed-aware routing: when a trait is referenced via `@trait.X` by
+     * a sibling layout, its render output should not stack into the layout's
+     * slot; instead the layout embeds the trait's frame and the sidecar keeps
+     * the trait's latest frame queryable.
+     */
+    updateTraitContent(traitName: string, content: Omit<SlotContent, 'source'>): void;
+}
+/**
+ * Aggregate a slot's per-source content map into a single {@link SlotContent}.
+ *
+ * - 0 sources → `undefined` (empty slot).
+ * - 1 source → that source's content verbatim.
+ * - 2+ sources → a synthetic `stack` wrapper whose `children` are the
+ *   pattern configs of each source in insertion order.
+ *
+ * This mirrors the React `useUISlots` aggregation behavior and is provided so
+ * every renderer implements the same multi-source semantics.
+ */
+declare function aggregateSlotContent(slot: UISlot, sources: ReadonlyMap<string, SlotContent>): SlotContent | undefined;
+
+/**
+ * Assert that a value satisfies the {@link SlotManager} contract at runtime.
+ *
+ * @throws RendererContractViolationError when the value is not a valid manager.
+ */
+declare function assertIsSlotManager(value: unknown): asserts value is SlotManager;
+/**
+ * Assert that a value satisfies the {@link MultiSourceSlotManager} contract.
+ *
+ * @throws RendererContractViolationError when the value is not a valid manager.
+ */
+declare function assertIsMultiSourceSlotManager(value: unknown): asserts value is MultiSourceSlotManager;
+/**
+ * Validate that a {@link SlotContent} value satisfies the runtime contract.
+ *
+ * Returns an array of validation errors; an empty array means the value is
+ * valid. This lets renderer authors surface contract failures without
+ * exceptions.
+ */
+declare function validateSlotContent(content: SlotContent): SlotContentValidationError[];
+/**
+ * Minimal adapter that turns a `SlotManager` into the shape expected by
+ * {@link createClientEffectHandlers} in `ClientEffectHandlers.ts`.
+ *
+ * This keeps the legacy `SlotSetter.addPattern/clearSlot` surface working while
+ * nudging new renderers toward the fuller `SlotManager` contract.
+ */
+declare function createSlotSetter(manager: SlotManager): {
+    addPattern: (slot: string, pattern: AnyPatternConfig, props?: ResolvedPatternProps) => void;
+    clearSlot: (slot: string) => void;
+};
+
+/**
+ * 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;
+
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @public
+ */
+declare function prepareSchemaForPreview(input: OrbitalSchema | string): PreparedPreviewSchema;
+
+/**
+ * Build the `trait name → owning orbital` map used to form the qualified
+ * `UI:<orbital>.<trait>.<event>` bus keys that trait state machines subscribe
+ * to. Pure + dependency-free so it can be unit-tested without a render.
+ *
+ * Critically, it backfills from the RESOLVED page bindings, not just the source
+ * `schema.orbitals[].traits`. An auto-pulled sibling trait (e.g. an embedded
+ * `@trait.X` calendar lifted into the orbital by the compiler's sibling-pull)
+ * is absent from the source orbital's `traits[]`, so a source-only map misses
+ * it — leaving its self-subscription unregistered and its own fetch-success
+ * (e.g. `CalendarEventLoaded`) unheard, so the trait sticks in `loading`. A
+ * pulled sibling lands in the same orbital as the page that references it, so
+ * we backfill from the resolved page's owning orbital. Source-declared mappings
+ * win; the IR only fills gaps.
+ */
+interface ResolvedPageTraits {
+    /** Page route path, matched against the source orbital's page paths. */
+    path?: string;
+    /** Resolved trait names mounted on the page (includes pulled siblings). */
+    traitNames: readonly string[];
+}
+/**
+ * Minimal trait-ref shape the mapper actually reads. Structurally widens
+ * `TraitRef` so tests and partial schemas don't have to satisfy every required
+ * inline-trait field (e.g. `scope`) that the mapper never touches.
+ */
+type OrbitalsByTraitTraitInput = string | {
+    ref?: string;
+    name?: string;
+};
+/**
+ * Minimal schema shape the mapper actually reads. Kept local because the
+ * function only needs `orbitals[].{name,traits,pages}`; the full
+ * `OrbitalSchema` carries many more required fields.
+ */
+interface OrbitalsByTraitInput {
+    orbitals: ReadonlyArray<{
+        name: string;
+        traits?: ReadonlyArray<OrbitalsByTraitTraitInput>;
+        pages?: ReadonlyArray<string | {
+            path?: string;
+        }>;
+    }>;
+}
+declare function buildOrbitalsByTrait(schema: OrbitalsByTraitInput | undefined, resolvedPages?: ReadonlyArray<ResolvedPageTraits>): Record<string, string>;
+
+/**
+ * Embed-aware slot routing — static analysis pass.
+ *
+ * Walks every trait's `transitions[].effects` looking for `render-ui`
+ * patterns whose tree contains `@trait.<Name>` string literals. Returns
+ * the flat set of trait names that are referenced this way by some
+ * sibling layout.
+ *
+ * Used by `<OrbPreview>` to route `applyServerEffects` — when an
+ * embedded trait's render-ui effect arrives, the runtime updates that
+ * trait's per-trait sidecar (`traitIndexRef`) only and skips the slot
+ * write. The sibling layout owns the slot and embeds the trait's frame
+ * via `<TraitFrame>`. Mirrors the compiled-path codegen which inlines
+ * the atom views as JSX inside the layout's pattern, never having them
+ * write a shared slot.
+ *
+ * The walker is a structural twin of
+ * `packages/almadar-runtime/src/resolver/reference-resolver.ts`'s
+ * `renameEventsInRenderUiConfig` — same recursive pattern shape, just
+ * collecting `@trait.X` substrings instead of renaming events.
+ *
+ * @packageDocumentation
+ */
+
+declare function collectTraitRefsFromResolvedTrait(trait: ResolvedTrait): Set<string>;
+declare function collectEmbeddedTraits(schema: OrbitalSchema | undefined | null): ReadonlySet<string>;
+
+/**
+ * Renderer-agnostic perf instrumentation.
+ *
+ * Contains the timing ring + mark/measure primitives used by runtime-side
+ * schema prep and other framework-free work. React-specific consumption hooks
+ * stay in `@almadar/ui/lib/perf` and read this shared ring.
+ *
+ * Gated behind `createLogger('almadar:perf:canvas')` so production builds
+ * (LOG_LEVEL >= WARN) skip the work.
+ *
+ * @packageDocumentation
+ */
+declare const PERF_NAMESPACE = "almadar:perf:canvas";
+/**
+ * Perf metadata values are local instrumentation scalars. There is no
+ * corresponding @almadar/core concept, so this local fallback type replaces
+ * the previous Record<string, unknown> while keeping the surface concrete.
+ */
+type PerfDetailValue = string | number | boolean | null | undefined;
+interface PerfDetail {
+    readonly [key: string]: PerfDetailValue;
+}
+interface PerfEntry {
+    readonly name: string;
+    readonly durationMs: number;
+    readonly ts: number;
+    readonly detail?: Readonly<PerfDetail>;
+}
+/**
+ * Start a phase. Returns an opaque token; pass to {@link perfEnd}.
+ * Returns -1 when the namespace is gated off.
+ */
+declare function perfStart(name: string): number;
+declare function perfEnd(name: string, startToken: number, detail?: PerfDetail): void;
+/** Synchronous wrapper that times a fn end-to-end. */
+declare function perfTime<T>(name: string, fn: () => T, detail?: PerfDetail): T;
+declare function getSnapshot(): readonly PerfEntry[];
+declare function subscribe(fn: () => void): () => void;
+/** Push a pre-computed entry (e.g. React.Profiler callback). */
+declare function pushPerfEntry(entry: PerfEntry): void;
+/** Clear the ring and notify subscribers. */
+declare function clearPerf(): void;
+/**
+ * Primitives a renderer-specific hook (e.g. React's `useSyncExternalStore`)
+ * uses to consume the perf ring.
+ */
+declare const perfStore: {
+    subscribe: typeof subscribe;
+    getSnapshot: typeof getSnapshot;
+};
+
+/**
+ * Renderer-agnostic `window.__orbitalVerification` bridge.
+ *
+ * The single observation point Playwright-based verifiers
+ * (`runtime-verify`, `orbital-verify`, `@almadar-io/verify`) use to read
+ * state out of a live app and drive events into it. The wire types live
+ * in `@almadar/core` (see `types/verification.ts`); this module owns only
+ * the minimal exposure plumbing so any UI library — React, Web
+ * Components, or a future renderer — can populate the same contract
+ * without duplicating it.
+ *
+ * Framework-specific state (transition traces, reducer snapshots, bridge
+ * health) is left empty by default; a renderer that tracks them can
+ * override the readers after {@link ensureVerificationApi} runs. The two
+ * bindings every renderer must provide are {@link bindEventBus} (so
+ * automation can `sendEvent`) and {@link bindTraitStateGetter} (so
+ * automation can `getTraitState`).
+ *
+ * @packageDocumentation
+ */
+
+declare global {
+    interface Window {
+        __orbitalVerification?: OrbitalVerificationAPI;
+    }
+}
+/**
+ * Minimal structural surface a renderer's event bus must satisfy to be
+ * driven by automation. Matches the runtime `EventBus` (`emit` +
+ * optional `onAny`) without forcing a concrete class, so any UI
+ * library's bus — including `@almadar/runtime`'s own — plugs in.
+ */
+interface VerificationBus {
+    emit: (type: string, payload?: EventPayload) => void;
+    onAny?: (listener: (event: BusEvent) => void) => () => void;
+}
+/**
+ * Ensure `window.__orbitalVerification` exists with the required
+ * readers, then return it. Returns `undefined` outside a DOM (SSR /
+ * tests without a window). Idempotent: an existing object is returned
+ * untouched so a renderer that already registered readers keeps them.
+ */
+declare function ensureVerificationApi(): OrbitalVerificationAPI | undefined;
+/** Read the current bridge, if any. SSR-safe. */
+declare function getOrbitalVerification(): OrbitalVerificationAPI | undefined;
+/**
+ * Bind the renderer's event bus so automation can send events and read
+ * a rolling emission log.
+ *
+ * `sendEvent(event, payload, traitScope)` mirrors the React bridge:
+ * when `traitScope` is provided the event is emitted on the qualified
+ * key `UI:${traitScope}.${event}` (matching codegen-emitted
+ * subscription keys); otherwise the legacy bare form `UI:${event}` is
+ * used. An already-`UI:`-prefixed event is emitted verbatim.
+ */
+declare function bindEventBus(eventBus: VerificationBus): void;
+/**
+ * Bind a trait-state getter so automation can query a trait's current
+ * state machine state by name.
+ */
+declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
+
+export { type MultiSourceSlotManager, PERF_NAMESPACE, type PerfDetail, type PerfDetailValue, type PerfEntry, type PreparedPreviewSchema, RendererContractViolationError, type ResolvedPageTraits, type SlotContent, type SlotContentValidationError, type SlotManager, type SlotSource, type VerificationBus, adjustSchemaForMockData, aggregateSlotContent, assertIsMultiSourceSlotManager, assertIsSlotManager, bindEventBus, bindTraitStateGetter, buildMockData, buildOrbitalsByTrait, clearPerf, collectEmbeddedTraits, collectTraitRefsFromResolvedTrait, createSlotSetter, ensureVerificationApi, getOrbitalVerification, perfEnd, perfStart, perfStore, perfTime, prepareSchemaForPreview, pushPerfEntry, validateSlotContent, wrapCallbackForEvent };

package/dist/ui/index.js

@@ -0,0 +1,3 @@
+export { PERF_NAMESPACE, RendererContractViolationError, adjustSchemaForMockData, aggregateSlotContent, assertIsMultiSourceSlotManager, assertIsSlotManager, bindEventBus, bindTraitStateGetter, buildMockData, buildOrbitalsByTrait, clearPerf, createSlotSetter, ensureVerificationApi, getOrbitalVerification, perfEnd, perfStart, perfStore, perfTime, prepareSchemaForPreview, pushPerfEntry, validateSlotContent, wrapCallbackForEvent } from '../chunk-O5VGKPTG.js';
+export { collectEmbeddedTraits, collectTraitRefsFromResolvedTrait } from '../chunk-SCRAHWOC.js';
+import '../chunk-MLKGABMK.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/runtime",
-  "version": "6.31.0",
+  "version": "6.33.0",
   "description": "Interpreted runtime for Almadar orbital applications (OrbitalServerRuntime)",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,6 +32,16 @@
       "types": "./dist/createOsHandlers.d.ts",
       "import": "./dist/createOsHandlers.js",
       "require": "./dist/createOsHandlers.js"
+    },
+    "./mockRandom": {
+      "types": "./dist/mockRandom.d.ts",
+      "import": "./dist/mockRandom.js",
+      "require": "./dist/mockRandom.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "import": "./dist/ui/index.js",
+      "require": "./dist/ui/index.js"
     }
   },
   "files": [
@@ -42,12 +52,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": "^10.27.0",
+    "@almadar/core": "^10.29.0",
     "@almadar/evaluator": "^2.29.0",
     "@almadar/logger": "^1.9.0",
-    "@almadar/server": "^2.20.0",
-    "@almadar/std": "^16.137.0",
-    "@faker-js/faker": "^9.3.0"
+    "@almadar/server": "^2.25.0",
+    "@almadar/std": "^16.138.0"
   },
   "peerDependencies": {
     "express": "^5.0.0"
@@ -65,9 +74,9 @@
     "eslint": "10.0.0",
     "express": "^5.0.0",
     "tsup": "^8.0.0",
+    "turbo": "^2.8.17",
     "typescript": "^5.7.0",
-    "vitest": "^2.1.0",
-    "turbo": "^2.8.17"
+    "vitest": "^2.1.0"
   },
   "repository": {
     "type": "git",
@@ -83,6 +92,7 @@
   ],
   "homepage": "https://github.com/almadar-io/almadar#readme",
   "scripts": {
+    "prebuild": "rm -rf dist",
     "build": "tsup",
     "build:watch": "tsup --watch",
     "lint": "eslint src/",