@almadar/ui 5.113.0 → 5.115.0

package/dist/runtime/index.d.cts

@@ -1,5 +1,5 @@
 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';
+import { EventPayload, ServiceParams, ResolvedTraitBinding, ResolvedPage, ResolvedEntity, ResolvedTrait, ResolvedIR, OrbitalSchema, PatternConfig, FieldValue, EventSource, SExpr, 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';
@@ -7,10 +7,12 @@ 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 { PerfEntry } from '@almadar/runtime/ui';
+export { PERF_NAMESPACE, PerfEntry, PreparedPreviewSchema, adjustSchemaForMockData, buildMockData, clearPerf, perfEnd, perfStart, perfTime, prepareSchemaForPreview, wrapCallbackForEvent } from '@almadar/runtime/ui';
 import React__default, { ProfilerOnRenderCallback } from 'react';
 import '../event-bus-types-Bl78kokd.cjs';
 import '../useUISlots-BesZYMks.cjs';
+import '@almadar/core/patterns';
 
 interface TraitStateMachineResult {
     /** Current state for each trait */
@@ -145,21 +147,6 @@ interface SlotSource extends EventSource {
     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
  *
@@ -307,7 +294,7 @@ declare namespace OrbPreview {
 interface BrowserPlaygroundProps {
     /** OrbitalSchema to render. */
     schema: OrbitalSchema;
-    /** Persistence mode for the in-process runtime. Default: 'mock' (Faker-seeded MockPersistenceAdapter). */
+    /** Persistence mode for the in-process runtime. Default: 'mock' (seeded MockPersistenceAdapter). */
     mode?: 'mock';
     /** Initial page path to render (forwarded to OrbPreview). */
     initialPagePath?: string;
@@ -318,109 +305,21 @@ interface BrowserPlaygroundProps {
 }
 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.
+ * React-specific consumption layer on top of the renderer-agnostic perf ring
+ * now living in `@almadar/runtime/ui/perf`. Re-exports the framework-free
+ * timing primitives and adds `useSyncExternalStore` / `React.Profiler` hooks.
  */
 
-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.
+ * React hook: returns the current perf ring snapshot, re-renders on push.
  */
-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;
+declare function usePerfBuffer(): readonly PerfEntry[];
 /**
  * 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 };
+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, profilerOnRender, usePerfBuffer, useResolvedSchema, useTraitStateMachine };

package/dist/runtime/index.d.ts

@@ -1,5 +1,5 @@
 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';
+import { EventPayload, ServiceParams, ResolvedTraitBinding, ResolvedPage, ResolvedEntity, ResolvedTrait, ResolvedIR, OrbitalSchema, PatternConfig, FieldValue, EventSource, SExpr, 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';
@@ -7,10 +7,12 @@ import '../useEventBus-CQWyAWpK.js';
 import { c as useUISlots } from '../UISlotContext-C1FsU9GB.js';
 import { f as ServerBridgeTransport } from '../TraitProvider-YkK6tXDw.js';
 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.js';
-import { PatternCallbackArg } from '@almadar/core/patterns';
+import { PerfEntry } from '@almadar/runtime/ui';
+export { PERF_NAMESPACE, PerfEntry, PreparedPreviewSchema, adjustSchemaForMockData, buildMockData, clearPerf, perfEnd, perfStart, perfTime, prepareSchemaForPreview, wrapCallbackForEvent } from '@almadar/runtime/ui';
 import React__default, { ProfilerOnRenderCallback } from 'react';
 import '../event-bus-types-Bl78kokd.js';
 import '../useUISlots-BesZYMks.js';
+import '@almadar/core/patterns';
 
 interface TraitStateMachineResult {
     /** Current state for each trait */
@@ -145,21 +147,6 @@ interface SlotSource extends EventSource {
     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
  *
@@ -307,7 +294,7 @@ declare namespace OrbPreview {
 interface BrowserPlaygroundProps {
     /** OrbitalSchema to render. */
     schema: OrbitalSchema;
-    /** Persistence mode for the in-process runtime. Default: 'mock' (Faker-seeded MockPersistenceAdapter). */
+    /** Persistence mode for the in-process runtime. Default: 'mock' (seeded MockPersistenceAdapter). */
     mode?: 'mock';
     /** Initial page path to render (forwarded to OrbPreview). */
     initialPagePath?: string;
@@ -318,109 +305,21 @@ interface BrowserPlaygroundProps {
 }
 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.
+ * React-specific consumption layer on top of the renderer-agnostic perf ring
+ * now living in `@almadar/runtime/ui/perf`. Re-exports the framework-free
+ * timing primitives and adds `useSyncExternalStore` / `React.Profiler` hooks.
  */
 
-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.
+ * React hook: returns the current perf ring snapshot, re-renders on push.
  */
-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;
+declare function usePerfBuffer(): readonly PerfEntry[];
 /**
  * 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 };
+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, profilerOnRender, usePerfBuffer, useResolvedSchema, useTraitStateMachine };