@almadar/ui 1.0.34 → 2.0.1

package/dist/lib/traitRegistry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Trait Registry - Tracks active traits and their state machines for debugging
+ *
+ * @packageDocumentation
+ */
+export interface TraitTransition {
+    from: string;
+    to: string;
+    event: string;
+    guard?: string;
+}
+export interface TraitGuard {
+    name: string;
+    lastResult?: boolean;
+}
+export interface TraitDebugInfo {
+    id: string;
+    name: string;
+    currentState: string;
+    states: string[];
+    transitions: TraitTransition[];
+    guards: TraitGuard[];
+    transitionCount: number;
+}
+type ChangeListener = () => void;
+export declare function registerTrait(info: TraitDebugInfo): void;
+export declare function updateTraitState(id: string, newState: string): void;
+export declare function updateGuardResult(traitId: string, guardName: string, result: boolean): void;
+export declare function unregisterTrait(id: string): void;
+export declare function getAllTraits(): TraitDebugInfo[];
+export declare function getTrait(id: string): TraitDebugInfo | undefined;
+export declare function subscribeToTraitChanges(listener: ChangeListener): () => void;
+export declare function clearTraits(): void;
+export {};

package/dist/lib/verificationRegistry.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Verification Registry - Tracks runtime verification checks and transition traces
+ *
+ * Provides:
+ * 1. A checklist of pass/fail checks (INIT has fetch, bridge connected, etc.)
+ * 2. A full transition timeline with effect execution results
+ * 3. ServerBridge health snapshot
+ * 4. window.__orbitalVerification for Playwright/automation
+ *
+ * @packageDocumentation
+ */
+export type CheckStatus = "pass" | "fail" | "pending" | "warn";
+export interface VerificationCheck {
+    id: string;
+    label: string;
+    status: CheckStatus;
+    details?: string;
+    /** Timestamp when status last changed */
+    updatedAt: number;
+}
+export interface EffectTrace {
+    type: string;
+    args: unknown[];
+    status: "executed" | "failed" | "skipped";
+    error?: string;
+    durationMs?: number;
+}
+export interface TransitionTrace {
+    id: string;
+    traitName: string;
+    from: string;
+    to: string;
+    event: string;
+    guardExpression?: string;
+    guardResult?: boolean;
+    effects: EffectTrace[];
+    timestamp: number;
+}
+export interface BridgeHealth {
+    connected: boolean;
+    eventsForwarded: number;
+    eventsReceived: number;
+    lastError?: string;
+    lastHeartbeat: number;
+}
+export interface VerificationSummary {
+    totalChecks: number;
+    passed: number;
+    failed: number;
+    warnings: number;
+    pending: number;
+}
+export interface VerificationSnapshot {
+    checks: VerificationCheck[];
+    transitions: TransitionTrace[];
+    bridge: BridgeHealth | null;
+    summary: VerificationSummary;
+}
+type ChangeListener = () => void;
+export declare function registerCheck(id: string, label: string, status?: CheckStatus, details?: string): void;
+export declare function updateCheck(id: string, status: CheckStatus, details?: string): void;
+export declare function getAllChecks(): VerificationCheck[];
+export declare function recordTransition(trace: Omit<TransitionTrace, "id">): void;
+export declare function getTransitions(): TransitionTrace[];
+export declare function getTransitionsForTrait(traitName: string): TransitionTrace[];
+export declare function updateBridgeHealth(health: BridgeHealth): void;
+export declare function getBridgeHealth(): BridgeHealth | null;
+export declare function getSummary(): VerificationSummary;
+export declare function getSnapshot(): VerificationSnapshot;
+export declare function subscribeToVerification(listener: ChangeListener): () => void;
+/** Exposed on window for Playwright to query */
+interface OrbitalVerificationAPI {
+    getSnapshot: () => VerificationSnapshot;
+    getChecks: () => VerificationCheck[];
+    getTransitions: () => TransitionTrace[];
+    getBridge: () => BridgeHealth | null;
+    getSummary: () => VerificationSummary;
+    /** Wait for a specific event to be processed */
+    waitForTransition: (event: string, timeoutMs?: number) => Promise<TransitionTrace | null>;
+    /** Send an event into the runtime (requires eventBus binding) */
+    sendEvent?: (event: string, payload?: Record<string, unknown>) => void;
+    /** Get current trait state */
+    getTraitState?: (traitName: string) => string | undefined;
+}
+declare global {
+    interface Window {
+        __orbitalVerification?: OrbitalVerificationAPI;
+    }
+}
+/**
+ * Wait for a transition matching the given event to appear.
+ * Returns the trace or null on timeout.
+ */
+export declare function waitForTransition(event: string, timeoutMs?: number): Promise<TransitionTrace | null>;
+/**
+ * Bind the EventBus so automation can send events.
+ * Call this during app initialization.
+ */
+export declare function bindEventBus(eventBus: {
+    emit: (type: string, payload?: Record<string, unknown>) => void;
+}): void;
+/**
+ * Bind a trait state getter so automation can query current states.
+ */
+export declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
+export declare function clearVerification(): void;
+export {};

package/dist/{cn-BoBXsxuX.d.ts → lib/visualizer/index.d.ts}

@@ -1,12 +1,10 @@
-import { ClassValue } from 'clsx';
-
 /**
  * Orbital State Machine Visualizer
  *
  * Renders SVG diagrams from Orbital schemas and Trait definitions.
  * Can be used in documentation, IDE previews, and other tools.
  */
-interface VisualizerConfig {
+export interface VisualizerConfig {
     nodeRadius: number;
     nodeSpacing: number;
     initialIndicatorOffset: number;
@@ -30,35 +28,35 @@ interface VisualizerConfig {
         effect: string;
     };
 }
-interface StateDefinition {
+export interface StateDefinition {
     name: string;
     isInitial?: boolean;
     isFinal?: boolean;
     description?: string;
 }
-interface TransitionDefinition {
+export interface TransitionDefinition {
     from: string;
     to: string;
     event: string;
     guard?: unknown;
     effects?: unknown[];
 }
-interface StateMachineDefinition {
+export interface StateMachineDefinition {
     states: StateDefinition[];
     transitions: TransitionDefinition[];
 }
-interface EntityDefinition {
+export interface EntityDefinition {
     name: string;
     fields?: (string | {
         name: string;
     })[];
 }
-interface RenderOptions {
+export interface RenderOptions {
     title?: string;
     entity?: EntityDefinition;
 }
 /** Position data for a state node in DOM layout */
-interface DomStateNode {
+export interface DomStateNode {
     id: string;
     name: string;
     x: number;
@@ -69,7 +67,7 @@ interface DomStateNode {
     description?: string;
 }
 /** Position data for a transition arrow */
-interface DomTransitionPath {
+export interface DomTransitionPath {
     id: string;
     from: string;
     to: string;
@@ -80,7 +78,7 @@ interface DomTransitionPath {
     labelY: number;
 }
 /** Position data for a transition label with guard/effect details */
-interface DomTransitionLabel {
+export interface DomTransitionLabel {
     id: string;
     from: string;
     to: string;
@@ -95,7 +93,7 @@ interface DomTransitionLabel {
     hasDetails: boolean;
 }
 /** Entity input box data */
-interface DomEntityBox {
+export interface DomEntityBox {
     name: string;
     fields: string[];
     x: number;
@@ -104,7 +102,7 @@ interface DomEntityBox {
     height: number;
 }
 /** Output effects box data */
-interface DomOutputsBox {
+export interface DomOutputsBox {
     outputs: string[];
     x: number;
     y: number;
@@ -112,7 +110,7 @@ interface DomOutputsBox {
     height: number;
 }
 /** Complete DOM layout data for rendering */
-interface DomLayoutData {
+export interface DomLayoutData {
     width: number;
     height: number;
     title?: string;
@@ -123,72 +121,23 @@ interface DomLayoutData {
     outputs?: DomOutputsBox;
     config: VisualizerConfig;
 }
-declare const DEFAULT_CONFIG: VisualizerConfig;
+export declare const DEFAULT_CONFIG: VisualizerConfig;
 declare function formatGuard(guard: unknown): string;
-declare function getEffectSummary(effects: unknown[]): string;
+export declare function getEffectSummary(effects: unknown[]): string;
 declare function extractOutputsFromTransitions(transitions: TransitionDefinition[]): string[];
 /**
  * Render a state machine to an SVG string.
  * Works in both browser and Node.js environments.
  */
-declare function renderStateMachineToSvg(stateMachine: StateMachineDefinition, options?: RenderOptions, config?: VisualizerConfig): string;
+export declare function renderStateMachineToSvg(stateMachine: StateMachineDefinition, options?: RenderOptions, config?: VisualizerConfig): string;
 /**
  * Extract state machine from various data formats (Trait, Orbital, or raw)
  */
-declare function extractStateMachine(data: unknown): StateMachineDefinition | null;
+export declare function extractStateMachine(data: unknown): StateMachineDefinition | null;
 /**
  * Render a state machine to DOM layout data.
  * This is used by the DOM-based visualizer component for hybrid SVG/DOM rendering.
  * Unlike renderStateMachineToSvg, this returns structured data instead of an SVG string.
  */
-declare function renderStateMachineToDomData(stateMachine: StateMachineDefinition, options?: RenderOptions, config?: VisualizerConfig): DomLayoutData;
-
-/**
- * Content Segment Parsing Utilities
- *
- * Parses rich content with code blocks and quiz tags into structured
- * segments for rendering. Detects orbital schemas in JSON code blocks
- * and marks them for JazariStateMachine rendering.
- */
-/** Segment types for content rendering */
-type ContentSegment = {
-    type: 'markdown';
-    content: string;
-} | {
-    type: 'code';
-    language: string;
-    content: string;
-} | {
-    type: 'orbital';
-    language: string;
-    content: string;
-    schema: unknown;
-} | {
-    type: 'quiz';
-    question: string;
-    answer: string;
-};
-/**
- * Parse markdown content to extract code blocks.
- *
- * Splits markdown into segments of plain markdown and fenced code blocks.
- * JSON/orb code blocks containing orbital schemas are tagged as 'orbital'.
- */
-declare function parseMarkdownWithCodeBlocks(content: string | undefined | null): ContentSegment[];
-/**
- * Parse content to extract all segments including quiz tags and code blocks.
- *
- * Supported tags:
- * - <question>q</question><answer>a</answer> — Quiz Q&A
- *
- * Also handles fenced code blocks (```language...```) with orbital detection.
- */
-declare function parseContentSegments(content: string | undefined | null): ContentSegment[];
-
-/**
- * Utility function to merge Tailwind CSS classes
- * Combines clsx for conditional classes with tailwind-merge to handle conflicts
- */
-declare function cn(...inputs: ClassValue[]): string;
-
-export { type ContentSegment as C, DEFAULT_CONFIG as D, type EntityDefinition as E, type RenderOptions as R, type StateDefinition as S, type TransitionDefinition as T, type VisualizerConfig as V, type DomEntityBox as a, type DomLayoutData as b, type DomOutputsBox as c, type DomStateNode as d, type DomTransitionLabel as e, type DomTransitionPath as f, type StateMachineDefinition as g, cn as h, extractOutputsFromTransitions as i, extractStateMachine as j, formatGuard as k, getEffectSummary as l, parseMarkdownWithCodeBlocks as m, renderStateMachineToSvg as n, parseContentSegments as p, renderStateMachineToDomData as r };
+export declare function renderStateMachineToDomData(stateMachine: StateMachineDefinition, options?: RenderOptions, config?: VisualizerConfig): DomLayoutData;
+export { formatGuard, extractOutputsFromTransitions };

package/dist/locales/index.d.ts

@@ -4,19 +4,17 @@
  * Exports message maps for en/ar/sl and a helper to merge
  * project-specific messages on top of core.
  */
-type SupportedLocale = 'en' | 'ar' | 'sl';
-interface LocaleMeta {
+export type SupportedLocale = 'en' | 'ar' | 'sl';
+export interface LocaleMeta {
     locale: string;
     direction: 'ltr' | 'rtl';
 }
 /** Core messages keyed by locale */
-declare const coreMessages: Record<SupportedLocale, Record<string, string>>;
+export declare const coreMessages: Record<SupportedLocale, Record<string, string>>;
 /** Locale metadata */
-declare const localeMeta: Record<SupportedLocale, LocaleMeta>;
+export declare const localeMeta: Record<SupportedLocale, LocaleMeta>;
 /**
  * Merge core messages with project-specific messages.
  * Project keys override core keys.
  */
-declare function mergeMessages(locale: SupportedLocale, projectMessages: Record<string, string>): Record<string, string>;
-
-export { type LocaleMeta, type SupportedLocale, coreMessages, localeMeta, mergeMessages };
+export declare function mergeMessages(locale: SupportedLocale, projectMessages: Record<string, string>): Record<string, string>;

package/dist/providers/EventBusProvider.d.ts

@@ -0,0 +1,60 @@
+/**
+ * EventBusProvider - React context provider for the event bus
+ *
+ * Provides a page-scoped event bus for trait communication.
+ * Each page has its own event bus instance.
+ *
+ * NOTE: Selection state has been moved to SelectionProvider.
+ * Use SelectionProvider for tracking selected entities.
+ *
+ * @packageDocumentation
+ */
+import React, { type ReactNode } from 'react';
+import type { EventBusContextType } from '../hooks/event-bus-types';
+/**
+ * Extended context type for backward compatibility.
+ *
+ * @deprecated getSelectedEntity and clearSelectedEntity are deprecated.
+ * Use SelectionProvider and useSelection hook instead.
+ */
+export interface EventBusContextTypeExtended extends EventBusContextType {
+    /**
+     * @deprecated Use useSelection from SelectionProvider instead.
+     * This method now returns null - selection state moved to SelectionProvider.
+     */
+    getSelectedEntity: () => unknown | null;
+    /**
+     * @deprecated Use useSelection from SelectionProvider instead.
+     * This method is now a no-op - selection state moved to SelectionProvider.
+     */
+    clearSelectedEntity: () => void;
+}
+export declare const EventBusContext: React.Context<EventBusContextTypeExtended | null>;
+interface EventBusProviderProps {
+    children: ReactNode;
+    /** Enable debug logging in development */
+    debug?: boolean;
+}
+/**
+ * Provider component for the page event bus.
+ *
+ * This is a pure pub/sub event bus. For selection state,
+ * use SelectionProvider which listens to events and maintains state.
+ *
+ * @example
+ * ```tsx
+ * function TaskDetailPage() {
+ *   return (
+ *     <EventBusProvider debug={process.env.NODE_ENV === 'development'}>
+ *       <SelectionProvider>
+ *         <TaskHeader />
+ *         <TaskForm />
+ *         <TaskActions />
+ *       </SelectionProvider>
+ *     </EventBusProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function EventBusProvider({ children, debug }: EventBusProviderProps): import("react/jsx-runtime").JSX.Element;
+export type { EventBusContextType };

package/dist/providers/FetchedDataProvider.d.ts

@@ -0,0 +1,105 @@
+/**
+ * FetchedDataProvider
+ *
+ * Provides server-fetched entity data to the client runtime.
+ * This context stores data returned from compiled event handlers
+ * via the `data` field in EventResponse.
+ *
+ * Data Flow:
+ * 1. Client sends event to server
+ * 2. Server executes compiled handler with fetch effects
+ * 3. Server returns { data: { EntityName: [...records] }, clientEffects: [...] }
+ * 4. Provider stores data in this context
+ * 5. Pattern components access data via useFetchedData hook
+ *
+ * Used by both Builder preview and compiled shell.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface EntityRecord {
+    id: string;
+    [key: string]: unknown;
+}
+export interface FetchedDataState {
+    /** Entity data by entity name (e.g., { Task: [...], User: [...] }) */
+    data: Record<string, EntityRecord[]>;
+    /** Timestamp of last fetch per entity */
+    fetchedAt: Record<string, number>;
+    /** Whether data is currently being fetched */
+    loading: boolean;
+    /** Last error message */
+    error: string | null;
+}
+export interface FetchedDataContextValue {
+    /** Get all records for an entity */
+    getData: (entityName: string) => EntityRecord[];
+    /** Get a single record by ID */
+    getById: (entityName: string, id: string) => EntityRecord | undefined;
+    /** Check if entity data exists */
+    hasData: (entityName: string) => boolean;
+    /** Get fetch timestamp for entity */
+    getFetchedAt: (entityName: string) => number | undefined;
+    /** Update data from server response */
+    setData: (data: Record<string, unknown[]>) => void;
+    /** Clear all fetched data */
+    clearData: () => void;
+    /** Clear data for specific entity */
+    clearEntity: (entityName: string) => void;
+    /** Current loading state */
+    loading: boolean;
+    /** Set loading state */
+    setLoading: (loading: boolean) => void;
+    /** Current error */
+    error: string | null;
+    /** Set error */
+    setError: (error: string | null) => void;
+}
+export declare const FetchedDataContext: React.Context<FetchedDataContextValue | null>;
+export interface FetchedDataProviderProps {
+    /** Initial data (optional) */
+    initialData?: Record<string, unknown[]>;
+    /** Children */
+    children: React.ReactNode;
+}
+/**
+ * FetchedDataProvider - Provides server-fetched entity data
+ *
+ * @example
+ * ```tsx
+ * <FetchedDataProvider>
+ *   <OrbitalProvider>
+ *     <App />
+ *   </OrbitalProvider>
+ * </FetchedDataProvider>
+ * ```
+ */
+export declare function FetchedDataProvider({ initialData, children, }: FetchedDataProviderProps): React.ReactElement;
+/**
+ * Access the fetched data context.
+ * Returns null if not within a FetchedDataProvider.
+ */
+export declare function useFetchedDataContext(): FetchedDataContextValue | null;
+/**
+ * Access fetched data with fallback behavior.
+ * If not in a provider, returns empty data.
+ */
+export declare function useFetchedData(): FetchedDataContextValue;
+/**
+ * Access fetched data for a specific entity.
+ * Provides a convenient API for entity-specific operations.
+ */
+export declare function useFetchedEntity(entityName: string): {
+    /** All fetched records for this entity */
+    records: EntityRecord[];
+    /** Get a record by ID */
+    getById: (id: string) => EntityRecord | undefined;
+    /** Whether data has been fetched for this entity */
+    hasData: boolean;
+    /** When data was last fetched */
+    fetchedAt: number | undefined;
+    /** Whether data is loading */
+    loading: boolean;
+    /** Current error */
+    error: string | null;
+};

package/dist/providers/OfflineModeProvider.d.ts

@@ -0,0 +1,79 @@
+/**
+ * OfflineModeProvider
+ *
+ * Context provider that wraps useOfflineExecutor with force-offline toggle support.
+ * Enables testing offline behavior without actually disconnecting.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type UseOfflineExecutorOptions, type UseOfflineExecutorResult } from '../renderer/offline-executor';
+export interface OfflineModeContextValue extends UseOfflineExecutorResult {
+    /** Force offline mode for testing */
+    forceOffline: boolean;
+    /** Toggle force offline mode */
+    setForceOffline: (value: boolean) => void;
+    /** Whether effectively offline (real or forced) */
+    effectivelyOffline: boolean;
+}
+export interface OfflineModeProviderProps extends UseOfflineExecutorOptions {
+    children: React.ReactNode;
+}
+/**
+ * OfflineModeProvider - Wraps offline executor with force-offline support.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <OfflineModeProvider
+ *       serverUrl="/api/orbitals"
+ *       authToken={token}
+ *       autoSync={true}
+ *       renderToSlot={slotManager.render}
+ *       navigate={router.push}
+ *       notify={toast.show}
+ *       eventBus={{ emit: bus.emit }}
+ *     >
+ *       <PreviewPage />
+ *     </OfflineModeProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function OfflineModeProvider({ children, ...executorOptions }: OfflineModeProviderProps): React.ReactElement;
+/**
+ * Access offline mode context.
+ *
+ * @example
+ * ```tsx
+ * function OfflineToggle() {
+ *   const {
+ *     effectivelyOffline,
+ *     forceOffline,
+ *     setForceOffline,
+ *     pendingCount,
+ *     sync,
+ *   } = useOfflineMode();
+ *
+ *   return (
+ *     <div>
+ *       <Toggle
+ *         checked={forceOffline}
+ *         onChange={setForceOffline}
+ *       >
+ *         Test Offline
+ *       </Toggle>
+ *       {pendingCount > 0 && <Badge>{pendingCount} pending</Badge>}
+ *       <Button onClick={sync}>Sync Now</Button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useOfflineMode(): OfflineModeContextValue;
+/**
+ * Check if offline mode provider is available (optional usage).
+ */
+export declare function useOptionalOfflineMode(): OfflineModeContextValue | null;
+export default OfflineModeProvider;

package/dist/providers/OrbitalProvider.d.ts

@@ -0,0 +1,101 @@
+/**
+ * OrbitalProvider
+ *
+ * Unified provider that combines all required contexts for Orbital applications.
+ * Provides a single import for both Builder preview and compiled shell.
+ *
+ * Combines:
+ * - ThemeProvider - Theme and color mode management
+ * - EventBusProvider - Page-scoped event pub/sub
+ * - SelectionProvider - Selected entity tracking
+ * - FetchedDataProvider - Server-fetched entity data
+ *
+ * @packageDocumentation
+ */
+import React, { type ReactNode } from 'react';
+import { type ThemeDefinition } from '../context/ThemeContext';
+export interface OrbitalProviderProps {
+    children: ReactNode;
+    /** Custom themes (merged with built-in themes) */
+    themes?: ThemeDefinition[];
+    /** Default theme name */
+    defaultTheme?: string;
+    /** Default color mode */
+    defaultMode?: 'light' | 'dark' | 'system';
+    /** Optional target element ref for scoped theme application */
+    targetRef?: React.RefObject<HTMLElement>;
+    /** Skip ThemeProvider (use when already inside a themed container like shadow DOM) */
+    skipTheme?: boolean;
+    /** Enable debug logging for all providers */
+    debug?: boolean;
+    /** Initial fetched data */
+    initialData?: Record<string, unknown[]>;
+    /**
+     * Enable Suspense mode. When true, UISlotRenderer wraps each slot in
+     * `<ErrorBoundary><Suspense>` with Skeleton fallbacks.
+     * Opt-in — existing isLoading prop pattern still works when false/absent.
+     */
+    suspense?: boolean;
+    /**
+     * Enable verification wiring for visual testing.
+     * When true, lifecycle events are recorded and exposed via
+     * `window.__orbitalVerification` for Playwright/automation.
+     * Default: true in development, false in production.
+     */
+    verification?: boolean;
+}
+/**
+ * OrbitalProvider - Unified context provider for Orbital applications
+ *
+ * Wraps your application with all required providers in the correct order.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * function App() {
+ *   return (
+ *     <OrbitalProvider>
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </OrbitalProvider>
+ *   );
+ * }
+ *
+ * // With configuration
+ * function App() {
+ *   return (
+ *     <OrbitalProvider
+ *       defaultTheme="minimalist"
+ *       defaultMode="dark"
+ *       debug={process.env.NODE_ENV === 'development'}
+ *     >
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </OrbitalProvider>
+ *   );
+ * }
+ *
+ * // With custom themes from schema
+ * import { THEMES } from './generated/theme-manifest';
+ *
+ * function App() {
+ *   return (
+ *     <OrbitalProvider themes={THEMES} defaultTheme="ocean">
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </OrbitalProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function OrbitalProvider({ children, themes, defaultTheme, defaultMode, targetRef, skipTheme, debug, initialData, suspense, verification, }: OrbitalProviderProps): React.ReactElement;
+export declare namespace OrbitalProvider {
+    var displayName: string;
+}
+export { ThemeProvider } from '../context/ThemeContext';
+export { EventBusProvider } from './EventBusProvider';
+export { SelectionProvider } from './SelectionProvider';
+export { FetchedDataProvider } from './FetchedDataProvider';