@almadar/ui 2.13.3 → 2.15.0

package/dist/lib/jazari/svg-paths.d.ts

@@ -0,0 +1,61 @@
+/**
+ * SVG path generators for the Al-Jazari state machine visualization.
+ * Pure TypeScript — zero React/DOM dependencies.
+ *
+ * Generates paths for gear teeth, arabesque borders, pipe shapes, and lock icons.
+ */
+/**
+ * Generate an SVG path for gear teeth around a circle.
+ *
+ * @param cx - Center X
+ * @param cy - Center Y
+ * @param innerRadius - Inner radius (base circle)
+ * @param outerRadius - Outer radius (tip of teeth)
+ * @param numTeeth - Number of teeth around the gear
+ * @returns SVG path d attribute string
+ */
+export declare function gearTeethPath(cx: number, cy: number, innerRadius: number, outerRadius: number, numTeeth: number): string;
+/**
+ * Generate an SVG path for a small gear-shaped lock icon.
+ *
+ * @param cx - Center X
+ * @param cy - Center Y
+ * @param size - Overall size of the lock icon
+ * @returns SVG path d attribute for the lock body + shackle
+ */
+export declare function lockIconPath(cx: number, cy: number, size: number): string;
+/**
+ * Generate a simple brain-like icon path.
+ *
+ * @param cx - Center X
+ * @param cy - Center Y
+ * @param size - Overall size
+ * @returns SVG path d attribute
+ */
+export declare function brainIconPath(cx: number, cy: number, size: number): string;
+/**
+ * Generate a simple pipe/tube icon path.
+ *
+ * @param cx - Center X
+ * @param cy - Center Y
+ * @param size - Overall size
+ * @returns SVG path d attribute
+ */
+export declare function pipeIconPath(cx: number, cy: number, size: number): string;
+/**
+ * Generate a single 8-pointed star path for the arabesque border pattern.
+ *
+ * @param cx - Center X
+ * @param cy - Center Y
+ * @param outerR - Outer radius (star tips)
+ * @param innerR - Inner radius (star valleys)
+ * @returns SVG path d attribute
+ */
+export declare function eightPointedStarPath(cx: number, cy: number, outerR: number, innerR: number): string;
+/**
+ * Generate a simple arrowhead path for transition arm endpoints.
+ *
+ * @param size - Arrow size
+ * @returns SVG path d attribute
+ */
+export declare function arrowheadPath(size: number): string;

package/dist/lib/jazari/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared types for the Al-Jazari state machine visualization.
+ * Pure TypeScript — zero React/DOM dependencies.
+ */
+/** Layout for a single gear (state node) */
+export interface JazariGearLayout {
+    /** State name */
+    name: string;
+    /** Center X coordinate */
+    cx: number;
+    /** Center Y coordinate */
+    cy: number;
+    /** Gear outer radius */
+    radius: number;
+    /** Whether this is the initial state */
+    isInitial: boolean;
+    /** Whether this is a terminal state */
+    isTerminal: boolean;
+}
+/** Guard info attached to an arm */
+export interface JazariGuardInfo {
+    /** Position X along the arm (30% point) */
+    x: number;
+    /** Position Y along the arm (30% point) */
+    y: number;
+    /** Whether this is an AI guard (call-service) vs deterministic */
+    isAI: boolean;
+}
+/** Effect info attached to an arm */
+export interface JazariEffectInfo {
+    /** Position X along the arm (70% point) */
+    x: number;
+    /** Position Y along the arm (70% point) */
+    y: number;
+    /** Number of effects */
+    count: number;
+    /** Effect labels for tooltip display */
+    names: string[];
+}
+/** Layout for a single transition arm */
+export interface JazariArmLayout {
+    /** Source state name */
+    from: string;
+    /** Target state name */
+    to: string;
+    /** Event name label */
+    event: string;
+    /** SVG path d attribute for the arm curve */
+    path: string;
+    /** Label position X (midpoint of arm) */
+    labelX: number;
+    /** Label position Y (midpoint of arm) */
+    labelY: number;
+    /** Guard info if transition has guards */
+    guard: JazariGuardInfo | null;
+    /** Effect info if transition has effects */
+    effect: JazariEffectInfo | null;
+    /** Whether this is a self-loop */
+    isSelfLoop: boolean;
+}
+/** Complete layout result for an entire state machine diagram */
+export interface JazariLayout {
+    /** Total SVG width */
+    width: number;
+    /** Total SVG height */
+    height: number;
+    /** All gear positions */
+    gears: JazariGearLayout[];
+    /** All transition arm paths */
+    arms: JazariArmLayout[];
+    /** Golden axis Y position */
+    axisY: number;
+    /** Golden axis start X */
+    axisStartX: number;
+    /** Golden axis end X */
+    axisEndX: number;
+    /** Entity field labels to display on the axis */
+    entityFields: string[];
+    /** Text direction */
+    direction: 'ltr' | 'rtl';
+}
+/** Al-Jazari color palette constants */
+export declare const JAZARI_COLORS: {
+    readonly brass: "#B87333";
+    readonly gold: "#C8A951";
+    readonly sky: "#0EA5E9";
+    readonly crimson: "#DC2626";
+    readonly lapis: "#1E40AF";
+    readonly ivory: "#FFFBEB";
+    readonly darkBg: "#1a1a2e";
+};

package/dist/lib/parseContentSegments.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 */
+export 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'.
+ */
+export 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.
+ */
+export declare function parseContentSegments(content: string | undefined | null): ContentSegment[];

package/dist/lib/tickRegistry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Tick Registry - Tracks scheduled tick executions for debugging
+ *
+ * @packageDocumentation
+ */
+export interface TickExecution {
+    id: string;
+    traitName: string;
+    /** Tick name (display name) */
+    name: string;
+    /** Tick identifier */
+    tickName: string;
+    interval: number;
+    /** Last execution timestamp */
+    lastRun: number;
+    lastExecuted: number | null;
+    nextExecution: number | null;
+    /** Number of times this tick has run */
+    runCount: number;
+    executionCount: number;
+    /** Average execution time in ms */
+    executionTime: number;
+    /** Whether the tick is currently active */
+    active: boolean;
+    isActive: boolean;
+    /** Guard name if this tick has a guard */
+    guardName?: string;
+    /** Whether the guard passed on last evaluation */
+    guardPassed?: boolean;
+}
+type ChangeListener = () => void;
+export declare function registerTick(tick: TickExecution): void;
+export declare function updateTickExecution(id: string, timestamp: number): void;
+export declare function setTickActive(id: string, isActive: boolean): void;
+export declare function unregisterTick(id: string): void;
+export declare function getAllTicks(): TickExecution[];
+export declare function getTick(id: string): TickExecution | undefined;
+export declare function subscribeToTickChanges(listener: ChangeListener): () => void;
+export declare function clearTicks(): void;
+export {};

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,138 @@
+/**
+ * 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;
+/** Asset load status for canvas verification */
+export type AssetLoadStatus = "loaded" | "failed" | "pending";
+/** Event bus log entry for verification */
+export interface EventLogEntry {
+    type: string;
+    payload?: Record<string, unknown>;
+    timestamp: number;
+}
+/** 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;
+    /** Capture a canvas frame as PNG data URL. Registered by game organisms. */
+    captureFrame?: () => string | null;
+    /** Asset load status map. Registered by game organisms. */
+    assetStatus?: Record<string, AssetLoadStatus>;
+    /** Event bus log. Records all emit() calls for verification. */
+    eventLog?: EventLogEntry[];
+    /** Clear the event log. */
+    clearEventLog?: () => void;
+}
+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 and log emissions.
+ * Call this during app initialization.
+ */
+export declare function bindEventBus(eventBus: {
+    emit: (type: string, payload?: Record<string, unknown>) => void;
+    onAny?: (listener: (event: {
+        type: string;
+        payload?: Record<string, unknown>;
+    }) => void) => () => void;
+}): void;
+/**
+ * Bind a trait state getter so automation can query current states.
+ */
+export declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
+/**
+ * Register a canvas frame capture function.
+ * Called by game organisms (IsometricCanvas, PlatformerCanvas, SimulationCanvas)
+ * so the verifier can snapshot canvas content at checkpoints.
+ */
+export declare function bindCanvasCapture(captureFn: () => string | null): void;
+/**
+ * Update asset load status for canvas verification.
+ * Game organisms call this when images load or fail.
+ */
+export declare function updateAssetStatus(url: string, status: AssetLoadStatus): void;
+export declare function clearVerification(): void;
+export {};

package/dist/lib/visualizer/browser.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Browser entry point for the Orbital Visualizer
+ *
+ * This file is bundled by esbuild to create a standalone browser script.
+ * It exports the visualizer to the global `OrbitalVisualizer` object.
+ */
+import { renderStateMachineToSvg, extractStateMachine, getEffectSummary, extractOutputsFromTransitions, type RenderOptions, type VisualizerConfig } from './index.js';
+type SExpr = string | number | boolean | SExpr[];
+declare function formatSExprHumanReadable(expr: SExpr, indent?: number): string;
+interface BrowserRenderOptions extends RenderOptions {
+    config?: Partial<VisualizerConfig>;
+}
+/**
+ * Render a state machine into a container element
+ */
+declare function render(container: HTMLElement, data: unknown, options?: BrowserRenderOptions): void;
+/**
+ * Auto-initialize diagrams from data attributes
+ */
+declare function init(): void;
+declare let pinnedTooltip: {
+    element: HTMLElement;
+    bundleId: string;
+} | null;
+/**
+ * Render a state machine into a container element using DOM-based approach
+ * This matches the React DomStateMachineVisualizer component
+ */
+declare function renderDom(container: HTMLElement, data: unknown, options?: BrowserRenderOptions): void;
+declare const OrbitalVisualizer: {
+    render: typeof render;
+    renderDom: typeof renderDom;
+    init: typeof init;
+    renderToSvg: typeof renderStateMachineToSvg;
+    extractStateMachine: typeof extractStateMachine;
+    getEffectSummary: typeof getEffectSummary;
+    extractOutputsFromTransitions: typeof extractOutputsFromTransitions;
+    formatSExprHumanReadable: typeof formatSExprHumanReadable;
+    CONFIG: VisualizerConfig;
+};
+declare global {
+    interface Window {
+        OrbitalVisualizer: typeof OrbitalVisualizer;
+        _pinnedTooltip: typeof pinnedTooltip;
+    }
+}
+export { OrbitalVisualizer };

package/dist/lib/visualizer/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Orbital State Machine Visualizer
+ *
+ * Renders SVG diagrams from Orbital schemas and Trait definitions.
+ * Can be used in documentation, IDE previews, and other tools.
+ */
+export interface VisualizerConfig {
+    nodeRadius: number;
+    nodeSpacing: number;
+    initialIndicatorOffset: number;
+    arrowSize: number;
+    colors: {
+        background: string;
+        node: string;
+        nodeBorder: string;
+        nodeText: string;
+        initialNode: string;
+        finalNode: string;
+        arrow: string;
+        arrowText: string;
+        effectText: string;
+        guardText: string;
+        initial: string;
+    };
+    fonts: {
+        node: string;
+        event: string;
+        effect: string;
+    };
+}
+export interface StateDefinition {
+    name: string;
+    isInitial?: boolean;
+    isFinal?: boolean;
+    description?: string;
+}
+export interface TransitionDefinition {
+    from: string;
+    to: string;
+    event: string;
+    guard?: unknown;
+    effects?: unknown[];
+}
+export interface StateMachineDefinition {
+    states: StateDefinition[];
+    transitions: TransitionDefinition[];
+}
+export interface EntityDefinition {
+    name: string;
+    fields?: (string | {
+        name: string;
+    })[];
+}
+export interface RenderOptions {
+    title?: string;
+    entity?: EntityDefinition;
+}
+/** Position data for a state node in DOM layout */
+export interface DomStateNode {
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    radius: number;
+    isInitial: boolean;
+    isFinal: boolean;
+    description?: string;
+}
+/** Position data for a transition arrow */
+export interface DomTransitionPath {
+    id: string;
+    from: string;
+    to: string;
+    /** SVG path data for the curved arrow */
+    pathData: string;
+    /** Midpoint for label positioning */
+    labelX: number;
+    labelY: number;
+}
+/** Position data for a transition label with guard/effect details */
+export interface DomTransitionLabel {
+    id: string;
+    from: string;
+    to: string;
+    event: string;
+    x: number;
+    y: number;
+    /** Human-readable guard text (e.g., "if amount > 100") */
+    guardText?: string;
+    /** Human-readable effect texts */
+    effectTexts: string[];
+    /** Whether this transition has details to show in tooltip */
+    hasDetails: boolean;
+}
+/** Entity input box data */
+export interface DomEntityBox {
+    name: string;
+    fields: string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Output effects box data */
+export interface DomOutputsBox {
+    outputs: string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Complete DOM layout data for rendering */
+export interface DomLayoutData {
+    width: number;
+    height: number;
+    title?: string;
+    states: DomStateNode[];
+    paths: DomTransitionPath[];
+    labels: DomTransitionLabel[];
+    entity?: DomEntityBox;
+    outputs?: DomOutputsBox;
+    config: VisualizerConfig;
+}
+export declare const DEFAULT_CONFIG: VisualizerConfig;
+declare function formatGuard(guard: 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.
+ */
+export declare function renderStateMachineToSvg(stateMachine: StateMachineDefinition, options?: RenderOptions, config?: VisualizerConfig): string;
+/**
+ * Extract state machine from various data formats (Trait, Orbital, or raw)
+ */
+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.
+ */
+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 };