@almadar/ui 5.111.0 → 5.113.0

package/dist/lib/index.d.ts

@@ -1,19 +1,505 @@
+export { C as ContentSegment, D as DEFAULT_CONFIG, a as DomEntityBox, b as DomLayoutData, c as DomOutputsBox, d as DomStateNode, e as DomTransitionLabel, f as DomTransitionPath, E as EntityDefinition, R as RenderOptions, S as StateDefinition, g as StateMachineDefinition, T as TraitSnapshotGetter, h as TransitionDefinition, V as VisualizerConfig, i as bindCanvasCapture, j as bindEventBus, k as bindLastDrawables, l as bindTraitStateGetter, m as clearVerification, n as cn, o as extractOutputsFromTransitions, p as extractStateMachine, q as formatGuard, r as getAllChecks, s as getBridgeHealth, t as getEffectSummary, u as getSnapshot, v as getSummary, w as getTraitSnapshots, x as getTransitions, y as getTransitionsForTrait, z as parseContentSegments, A as parseMarkdownWithCodeBlocks, B as recordServerResponse, F as recordTransition, G as registerCheck, H as registerTraitSnapshot, I as renderStateMachineToDomData, J as renderStateMachineToSvg, K as subscribeToVerification, L as updateAssetStatus, M as updateBridgeHealth, N as updateCheck, O as waitForTransition } from '../cn-CTEFm9PC.js';
+import { FieldValue, EntityRow, EventPayload } from '@almadar/core';
+export { AssetLoadStatus, BridgeHealth, CheckStatus, EffectTrace, EventLogEntry, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary } from '@almadar/core';
+import '../paintDispatch-DR942knx.js';
+import 'clsx';
+
 /**
- * Lib - Utility functions and registries
- *
- * Core utilities for the Almadar UI library.
- */
-export { cn } from './cn';
-export * from './api-client';
-export * from './debug';
-export { setDebugEnabled, toggleDebug, onDebugToggle, initDebugShortcut, } from './debugUtils';
-export * from './entityDebug';
-export * from './debugRegistry';
-export * from './guardRegistry';
-export * from './tickRegistry';
-export * from './traitRegistry';
-export * from './verificationRegistry';
-export * from './getNestedValue';
-export * from './visualizer/index';
-export * from './parseContentSegments';
-export * from './jazari/index';
+ * Trait Registry - Tracks active traits and their state machines for debugging
+ *
+ * @packageDocumentation
+ */
+interface TraitTransition {
+    from: string;
+    to: string;
+    event: string;
+    guard?: string;
+}
+interface TraitGuard {
+    name: string;
+    lastResult?: boolean;
+}
+interface TraitDebugInfo {
+    id: string;
+    name: string;
+    currentState: string;
+    states: string[];
+    transitions: TraitTransition[];
+    guards: TraitGuard[];
+    transitionCount: number;
+}
+type ChangeListener$3 = () => void;
+declare function registerTrait(info: TraitDebugInfo): void;
+declare function updateTraitState(id: string, newState: string): void;
+declare function updateGuardResult(traitId: string, guardName: string, result: boolean): void;
+declare function unregisterTrait(id: string): void;
+declare function getAllTraits(): TraitDebugInfo[];
+declare function getTrait(id: string): TraitDebugInfo | undefined;
+declare function subscribeToTraitChanges(listener: ChangeListener$3): () => void;
+declare function clearTraits(): void;
+
+/**
+ * Tick Registry - Tracks scheduled tick executions for debugging
+ *
+ * @packageDocumentation
+ */
+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$2 = () => void;
+declare function registerTick(tick: TickExecution): void;
+declare function updateTickExecution(id: string, timestamp: number): void;
+declare function setTickActive(id: string, isActive: boolean): void;
+declare function unregisterTick(id: string): void;
+declare function getAllTicks(): TickExecution[];
+declare function getTick(id: string): TickExecution | undefined;
+declare function subscribeToTickChanges(listener: ChangeListener$2): () => void;
+declare function clearTicks(): void;
+
+/**
+ * Guard Registry - Tracks guard evaluations for debugging
+ *
+ * @packageDocumentation
+ */
+
+interface GuardContext {
+    traitName?: string;
+    type?: "transition" | "tick";
+    transitionFrom?: string;
+    transitionTo?: string;
+    tickName?: string;
+    [key: string]: FieldValue | undefined;
+}
+interface GuardEvaluation {
+    id: string;
+    traitName: string;
+    guardName: string;
+    expression: string;
+    result: boolean;
+    context: GuardContext;
+    timestamp: number;
+    /** Input values used in guard evaluation */
+    inputs: Record<string, FieldValue>;
+}
+type ChangeListener$1 = () => void;
+declare function recordGuardEvaluation(evaluation: Omit<GuardEvaluation, "id" | "timestamp">): void;
+declare function getGuardHistory(): GuardEvaluation[];
+declare function getRecentGuardEvaluations(count: number): GuardEvaluation[];
+declare function getGuardEvaluationsForTrait(traitName: string): GuardEvaluation[];
+declare function subscribeToGuardChanges(listener: ChangeListener$1): () => void;
+declare function clearGuardHistory(): void;
+
+/**
+ * Entity Debug - Provides entity state snapshots for debugging
+ *
+ * @packageDocumentation
+ */
+
+interface EntityState {
+    id: string;
+    type: string;
+    fields: Record<string, FieldValue>;
+    lastUpdated: number;
+}
+interface RuntimeEntity {
+    id: string;
+    type: string;
+    data: Record<string, FieldValue>;
+}
+interface PersistentEntityInfo {
+    loaded: boolean;
+    count: number;
+}
+interface EntitySnapshot {
+    entities: EntityState[];
+    timestamp: number;
+    totalCount: number;
+    /** Singleton entities by name */
+    singletons: Record<string, EntityRow>;
+    /** Runtime entities (in-memory) */
+    runtime: RuntimeEntity[];
+    /** Persistent entities info by type */
+    persistent: Record<string, PersistentEntityInfo>;
+}
+type EntityProvider = () => EntityState[];
+declare function setEntityProvider(provider: EntityProvider): void;
+declare function clearEntityProvider(): void;
+declare function getEntitySnapshot(): EntitySnapshot | null;
+declare function getEntityById(id: string): EntityState | undefined;
+declare function getEntitiesByType(type: string): EntityState[];
+
+/**
+ * Debug Registry - Central event log for debugging
+ *
+ * @packageDocumentation
+ */
+
+type DebugEventType = 'state-change' | 'event-fired' | 'effect-executed' | 'guard-evaluated' | 'error' | 'warning' | 'info';
+interface DebugEvent {
+    id: string;
+    type: DebugEventType;
+    source: string;
+    message: string;
+    data?: Record<string, FieldValue>;
+    timestamp: number;
+}
+type ChangeListener = () => void;
+declare function logDebugEvent(type: DebugEventType, source: string, message: string, data?: Record<string, FieldValue>): void;
+declare function logStateChange(source: string, from: string, to: string, event?: string): void;
+declare function logEventFired(source: string, eventName: string, payload?: FieldValue): void;
+declare function logEffectExecuted(source: string, effectType: string, details?: FieldValue): void;
+declare function logError(source: string, message: string, error?: Error | null): void;
+declare function logWarning(source: string, message: string, data?: Record<string, FieldValue>): void;
+declare function logInfo(source: string, message: string, data?: Record<string, FieldValue>): void;
+declare function getDebugEvents(): DebugEvent[];
+declare function getRecentEvents(count: number): DebugEvent[];
+declare function getEventsByType(type: DebugEventType): DebugEvent[];
+declare function getEventsBySource(source: string): DebugEvent[];
+declare function subscribeToDebugEvents(listener: ChangeListener): () => void;
+declare function clearDebugEvents(): void;
+
+/**
+ * API Client - HTTP client for backend API calls
+ *
+ * Provides typed methods for making API requests.
+ * All requests go through the backend server, NOT directly to Firestore.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * API Error class for handling HTTP errors
+ */
+declare class ApiError extends Error {
+    status: number;
+    statusText: string;
+    constructor(status: number, statusText: string, message?: string);
+}
+/**
+ * API client with typed methods
+ */
+declare const apiClient: {
+    /**
+     * GET request
+     */
+    get<T>(endpoint: string): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(endpoint: string, data?: Record<string, FieldValue>): Promise<T>;
+    /**
+     * PUT request
+     */
+    put<T>(endpoint: string, data?: Record<string, FieldValue>): Promise<T>;
+    /**
+     * PATCH request
+     */
+    patch<T>(endpoint: string, data?: Record<string, FieldValue>): Promise<T>;
+    /**
+     * DELETE request
+     */
+    delete<T = void>(endpoint: string): Promise<T>;
+};
+
+/**
+ * Legacy debug helpers, now routed through `@almadar/logger`.
+ *
+ * The variadic `debug(...args)` shape is preserved for the many existing
+ * call sites (Form.tsx, RelationSelect.tsx, game helpers, etc.), but the
+ * gate is no longer a separate localStorage check — every helper here
+ * runs through the same priority/namespace gate the rest of the codebase
+ * uses. `setLogLevel('WARN')` silences them. `globalThis.__ALMADAR_DEBUG__`
+ * filters them by namespace.
+ *
+ * Namespace: `almadar:ui:debug` (plus per-area suffixes for input,
+ * collision, physics, game-state).
+ */
+declare function isDebugEnabled(): boolean;
+/**
+ * Variadic legacy debug. The first arg is the message; the rest is
+ * stringified into the LogData. Routes through the shared gate.
+ */
+declare function debug(...args: unknown[]): void;
+declare function debugGroup(label: string): void;
+declare function debugGroupEnd(): void;
+declare function debugWarn(...args: unknown[]): void;
+declare function debugError(...args: unknown[]): void;
+declare function debugTable(data: unknown): void;
+declare function debugTime(label: string): void;
+declare function debugTimeEnd(label: string): void;
+declare function debugInput(inputType: string, data: unknown): void;
+declare function debugCollision(entityA: {
+    id?: string;
+    type?: string;
+}, entityB: {
+    id?: string;
+    type?: string;
+}, details?: unknown): void;
+declare function debugPhysics(entityId: string, physics: unknown): void;
+declare function debugGameState(stateName: string, value: unknown): void;
+
+/**
+ * Debug Utilities - Functions for toggling and checking debug mode
+ *
+ * @packageDocumentation
+ */
+type DebugToggleListener = (enabled: boolean) => void;
+/**
+ * Enable or disable debug mode
+ */
+declare function setDebugEnabled(enabled: boolean): void;
+/**
+ * Toggle debug mode
+ */
+declare function toggleDebug(): boolean;
+/**
+ * Subscribe to debug mode changes
+ */
+declare function onDebugToggle(listener: DebugToggleListener): () => void;
+/**
+ * Initialize debug mode from keyboard shortcut (Ctrl+Shift+D)
+ */
+declare function initDebugShortcut(): () => void;
+
+/**
+ * Get Nested Value Utility
+ *
+ * Safely retrieves nested values from objects using dot-notation paths.
+ * Used by display components to support relation field access like "company.name".
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get a nested value from an object using dot-notation path.
+ *
+ * @param obj - The object to traverse
+ * @param path - Dot-notation path (e.g., "company.name", "address.city")
+ * @returns The value at the path, or undefined if not found
+ *
+ * @example
+ * const data = { company: { name: "Acme Corp", address: { city: "NYC" } } };
+ * getNestedValue(data, "company.name");         // => "Acme Corp"
+ * getNestedValue(data, "company.address.city"); // => "NYC"
+ * getNestedValue(data, "company.missing");      // => undefined
+ */
+declare function getNestedValue(obj: EventPayload | Record<string, FieldValue | undefined> | null | undefined, path: string): FieldValue | undefined;
+/**
+ * Format a nested field path as a human-readable label.
+ *
+ * @param path - Dot-notation path (e.g., "company.name")
+ * @returns Formatted label (e.g., "Company Name")
+ *
+ * @example
+ * formatFieldLabel("company.name");    // => "Company Name"
+ * formatFieldLabel("address.zipCode"); // => "Address Zip Code"
+ */
+declare function formatNestedFieldLabel(path: string): string;
+
+/**
+ * Shared types for the Al-Jazari state machine visualization.
+ * Pure TypeScript — zero React/DOM dependencies.
+ */
+/** Layout for a single gear (state node) */
+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 */
+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 */
+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 */
+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 */
+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 */
+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";
+};
+
+/**
+ * Layout algorithm for the Al-Jazari state machine visualization.
+ * Pure TypeScript — zero React/DOM dependencies.
+ *
+ * 1. BFS from initial state to order states by graph distance.
+ * 2. Horizontal distribution of gears along the golden axis.
+ * 3. Transition arm routing: forward arcs above, backward arcs below, self-loops above.
+ * 4. Guard icons at 30% along arm, effect icons at 70%.
+ */
+
+interface LayoutState {
+    name: string;
+    isInitial?: boolean;
+    isTerminal?: boolean;
+    isFinal?: boolean;
+}
+interface LayoutTransition {
+    from: string;
+    to: string;
+    event: string;
+    guard?: FieldValue;
+    effects?: FieldValue[];
+}
+interface LayoutInput {
+    states: LayoutState[];
+    transitions: LayoutTransition[];
+    entityFields?: string[];
+    direction?: 'ltr' | 'rtl';
+}
+declare function computeJazariLayout(input: LayoutInput): JazariLayout;
+
+/**
+ * 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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+declare function arrowheadPath(size: number): string;
+
+export { ApiError, type DebugEvent, type DebugEventType, type EntitySnapshot, type EntityState, type GuardContext, type GuardEvaluation, JAZARI_COLORS, type JazariArmLayout, type JazariEffectInfo, type JazariGearLayout, type JazariGuardInfo, type JazariLayout, type LayoutInput, type LayoutState, type LayoutTransition, type PersistentEntityInfo, type RuntimeEntity, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, apiClient, arrowheadPath, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, formatNestedFieldLabel, gearTeethPath, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getTick, getTrait, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, pipeIconPath, recordGuardEvaluation, registerTick, registerTrait, setDebugEnabled, setEntityProvider, setTickActive, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, toggleDebug, unregisterTick, unregisterTrait, updateGuardResult, updateTickExecution, updateTraitState };

package/dist/locales/index.d.cts

@@ -0,0 +1,22 @@
+/**
+ * Core locale loader for @almadar/ui.
+ *
+ * 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 {
+    locale: string;
+    direction: 'ltr' | 'rtl';
+}
+/** Core messages keyed by locale */
+declare const coreMessages: Record<SupportedLocale, Record<string, string>>;
+/** Locale metadata */
+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 };

package/dist/locales/index.d.ts

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