@almadar/ui 5.110.0 → 5.112.0

package/dist/cn-BbPvQLHt.d.cts

@@ -0,0 +1,294 @@
+import { OrbitalSchema, SExpr, Effect, OrbitalVerificationAPI, TraitStateSnapshot, EventPayload, BusEvent, VerificationCheck, BridgeHealth, VerificationSnapshot, VerificationSummary, TransitionTrace, ServerResponseTrace, CheckStatus, AssetLoadStatus } from '@almadar/core';
+import { ClassValue } from 'clsx';
+
+/**
+ * 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: OrbitalSchema;
+} | {
+    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[];
+
+/**
+ * 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 {
+    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;
+    };
+}
+interface StateDefinition {
+    name: string;
+    isInitial?: boolean;
+    isFinal?: boolean;
+    description?: string;
+}
+interface TransitionDefinition {
+    from: string;
+    to: string;
+    event: string;
+    guard?: SExpr | null;
+    effects?: Effect[];
+}
+interface StateMachineDefinition {
+    states: StateDefinition[];
+    transitions: TransitionDefinition[];
+}
+interface EntityDefinition {
+    name: string;
+    fields?: (string | {
+        name: string;
+    })[];
+}
+interface RenderOptions {
+    title?: string;
+    entity?: EntityDefinition;
+}
+/** Position data for a state node in DOM layout */
+interface DomStateNode {
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    radius: number;
+    isInitial: boolean;
+    isFinal: boolean;
+    description?: string;
+}
+/** Position data for a transition arrow */
+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 */
+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 */
+interface DomEntityBox {
+    name: string;
+    fields: string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Output effects box data */
+interface DomOutputsBox {
+    outputs: string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Complete DOM layout data for rendering */
+interface DomLayoutData {
+    width: number;
+    height: number;
+    title?: string;
+    states: DomStateNode[];
+    paths: DomTransitionPath[];
+    labels: DomTransitionLabel[];
+    entity?: DomEntityBox;
+    outputs?: DomOutputsBox;
+    config: VisualizerConfig;
+}
+declare const DEFAULT_CONFIG: VisualizerConfig;
+declare function formatGuard(guard: SExpr | null | undefined): string;
+declare function getEffectSummary(effects: Effect[]): 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;
+/**
+ * Extract state machine from various data formats (Trait, Orbital, or raw)
+ */
+declare function extractStateMachine(data: OrbitalSchema | object): 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;
+
+/**
+ * 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
+ */
+
+type ChangeListener = () => void;
+/**
+ * Per-trait snapshot getter. Each generated trait logic hook (or
+ * `useTraitStateMachine` trait binding) registers one on mount so the
+ * verifier can read the live reducer state for that trait.
+ */
+type TraitSnapshotGetter = () => TraitStateSnapshot;
+declare function registerCheck(id: string, label: string, status?: CheckStatus, details?: string): void;
+declare function updateCheck(id: string, status: CheckStatus, details?: string): void;
+declare function getAllChecks(): VerificationCheck[];
+declare function recordTransition(trace: Omit<TransitionTrace, "id">): void;
+declare function getTransitions(): TransitionTrace[];
+declare function getTransitionsForTrait(traitName: string): TransitionTrace[];
+/**
+ * Record a server response as a timeline entry.
+ * Creates a synthetic transition entry with type "server-response" to show
+ * what the server returned (clientEffects, data counts, emitted events).
+ */
+declare function recordServerResponse(orbitalName: string, event: string, response: Omit<ServerResponseTrace, "orbitalName" | "timestamp">): void;
+declare function updateBridgeHealth(health: BridgeHealth): void;
+declare function getBridgeHealth(): BridgeHealth | null;
+declare function getSummary(): VerificationSummary;
+declare function getSnapshot(): VerificationSnapshot;
+/**
+ * Per-trait snapshot for the verifier.
+ *
+ * Iterates every registered trait getter and collects the live reducer
+ * state. Empty until at least one trait hook calls `registerTraitSnapshot`.
+ * A getter that throws is logged and skipped — one broken trait must not
+ * poison the rest of the snapshot.
+ */
+declare function getTraitSnapshots(): TraitStateSnapshot[];
+declare function subscribeToVerification(listener: ChangeListener): () => void;
+declare global {
+    interface Window {
+        __orbitalVerification?: OrbitalVerificationAPI;
+    }
+}
+/**
+ * Wait for a transition matching the given event to appear.
+ * Returns the trace or null on timeout.
+ */
+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.
+ */
+declare function bindEventBus(eventBus: {
+    emit: (type: string, payload?: EventPayload) => void;
+    onAny?: (listener: (event: BusEvent) => void) => () => void;
+}): void;
+/**
+ * Bind a trait state getter so automation can query current states.
+ */
+declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
+/**
+ * Register a per-trait snapshot provider. The generated trait logic hook
+ * (or `useTraitStateMachine`) calls this once on mount, passing a getter
+ * that reads the current reducer state via a ref. Returns an unregister
+ * function for cleanup on unmount.
+ *
+ * Calling this twice for the same `traitName` replaces the previous
+ * getter (e.g. page navigation remounts the trait; the new registration
+ * wins).
+ */
+declare function registerTraitSnapshot(traitName: string, getter: TraitSnapshotGetter): () => void;
+/**
+ * Register a canvas frame capture function.
+ * Called by game organisms (IsometricCanvas, PlatformerCanvas)
+ * so the verifier can snapshot canvas content at checkpoints.
+ */
+declare function bindCanvasCapture(captureFn: () => string | null): void;
+/**
+ * Bind a reader for the last drawables list received by a canvas host.
+ * Lets verification scripts inspect exactly which neutral descriptors reached
+ * the painter without re-deriving them from state.
+ */
+declare function bindLastDrawables(getDrawables: () => unknown[] | null): void;
+/**
+ * Update asset load status for canvas verification.
+ * Game organisms call this when images load or fail.
+ */
+declare function updateAssetStatus(url: string, status: AssetLoadStatus): void;
+declare function clearVerification(): void;
+
+/**
+ * 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 { parseMarkdownWithCodeBlocks as A, recordServerResponse as B, type ContentSegment as C, DEFAULT_CONFIG as D, type EntityDefinition as E, recordTransition as F, registerCheck as G, registerTraitSnapshot as H, renderStateMachineToDomData as I, renderStateMachineToSvg as J, subscribeToVerification as K, updateAssetStatus as L, updateBridgeHealth as M, updateCheck as N, waitForTransition as O, type RenderOptions as R, type StateDefinition as S, type TraitSnapshotGetter 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, type TransitionDefinition as h, bindCanvasCapture as i, bindEventBus as j, bindLastDrawables as k, bindTraitStateGetter as l, clearVerification as m, cn as n, extractOutputsFromTransitions as o, extractStateMachine as p, formatGuard as q, getAllChecks as r, getBridgeHealth as s, getEffectSummary as t, getSnapshot as u, getSummary as v, getTraitSnapshots as w, getTransitions as x, getTransitionsForTrait as y, parseContentSegments as z };

package/dist/cn-BbPvQLHt.d.ts

@@ -0,0 +1,294 @@
+import { OrbitalSchema, SExpr, Effect, OrbitalVerificationAPI, TraitStateSnapshot, EventPayload, BusEvent, VerificationCheck, BridgeHealth, VerificationSnapshot, VerificationSummary, TransitionTrace, ServerResponseTrace, CheckStatus, AssetLoadStatus } from '@almadar/core';
+import { ClassValue } from 'clsx';
+
+/**
+ * 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: OrbitalSchema;
+} | {
+    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[];
+
+/**
+ * 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 {
+    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;
+    };
+}
+interface StateDefinition {
+    name: string;
+    isInitial?: boolean;
+    isFinal?: boolean;
+    description?: string;
+}
+interface TransitionDefinition {
+    from: string;
+    to: string;
+    event: string;
+    guard?: SExpr | null;
+    effects?: Effect[];
+}
+interface StateMachineDefinition {
+    states: StateDefinition[];
+    transitions: TransitionDefinition[];
+}
+interface EntityDefinition {
+    name: string;
+    fields?: (string | {
+        name: string;
+    })[];
+}
+interface RenderOptions {
+    title?: string;
+    entity?: EntityDefinition;
+}
+/** Position data for a state node in DOM layout */
+interface DomStateNode {
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    radius: number;
+    isInitial: boolean;
+    isFinal: boolean;
+    description?: string;
+}
+/** Position data for a transition arrow */
+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 */
+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 */
+interface DomEntityBox {
+    name: string;
+    fields: string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Output effects box data */
+interface DomOutputsBox {
+    outputs: string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Complete DOM layout data for rendering */
+interface DomLayoutData {
+    width: number;
+    height: number;
+    title?: string;
+    states: DomStateNode[];
+    paths: DomTransitionPath[];
+    labels: DomTransitionLabel[];
+    entity?: DomEntityBox;
+    outputs?: DomOutputsBox;
+    config: VisualizerConfig;
+}
+declare const DEFAULT_CONFIG: VisualizerConfig;
+declare function formatGuard(guard: SExpr | null | undefined): string;
+declare function getEffectSummary(effects: Effect[]): 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;
+/**
+ * Extract state machine from various data formats (Trait, Orbital, or raw)
+ */
+declare function extractStateMachine(data: OrbitalSchema | object): 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;
+
+/**
+ * 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
+ */
+
+type ChangeListener = () => void;
+/**
+ * Per-trait snapshot getter. Each generated trait logic hook (or
+ * `useTraitStateMachine` trait binding) registers one on mount so the
+ * verifier can read the live reducer state for that trait.
+ */
+type TraitSnapshotGetter = () => TraitStateSnapshot;
+declare function registerCheck(id: string, label: string, status?: CheckStatus, details?: string): void;
+declare function updateCheck(id: string, status: CheckStatus, details?: string): void;
+declare function getAllChecks(): VerificationCheck[];
+declare function recordTransition(trace: Omit<TransitionTrace, "id">): void;
+declare function getTransitions(): TransitionTrace[];
+declare function getTransitionsForTrait(traitName: string): TransitionTrace[];
+/**
+ * Record a server response as a timeline entry.
+ * Creates a synthetic transition entry with type "server-response" to show
+ * what the server returned (clientEffects, data counts, emitted events).
+ */
+declare function recordServerResponse(orbitalName: string, event: string, response: Omit<ServerResponseTrace, "orbitalName" | "timestamp">): void;
+declare function updateBridgeHealth(health: BridgeHealth): void;
+declare function getBridgeHealth(): BridgeHealth | null;
+declare function getSummary(): VerificationSummary;
+declare function getSnapshot(): VerificationSnapshot;
+/**
+ * Per-trait snapshot for the verifier.
+ *
+ * Iterates every registered trait getter and collects the live reducer
+ * state. Empty until at least one trait hook calls `registerTraitSnapshot`.
+ * A getter that throws is logged and skipped — one broken trait must not
+ * poison the rest of the snapshot.
+ */
+declare function getTraitSnapshots(): TraitStateSnapshot[];
+declare function subscribeToVerification(listener: ChangeListener): () => void;
+declare global {
+    interface Window {
+        __orbitalVerification?: OrbitalVerificationAPI;
+    }
+}
+/**
+ * Wait for a transition matching the given event to appear.
+ * Returns the trace or null on timeout.
+ */
+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.
+ */
+declare function bindEventBus(eventBus: {
+    emit: (type: string, payload?: EventPayload) => void;
+    onAny?: (listener: (event: BusEvent) => void) => () => void;
+}): void;
+/**
+ * Bind a trait state getter so automation can query current states.
+ */
+declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
+/**
+ * Register a per-trait snapshot provider. The generated trait logic hook
+ * (or `useTraitStateMachine`) calls this once on mount, passing a getter
+ * that reads the current reducer state via a ref. Returns an unregister
+ * function for cleanup on unmount.
+ *
+ * Calling this twice for the same `traitName` replaces the previous
+ * getter (e.g. page navigation remounts the trait; the new registration
+ * wins).
+ */
+declare function registerTraitSnapshot(traitName: string, getter: TraitSnapshotGetter): () => void;
+/**
+ * Register a canvas frame capture function.
+ * Called by game organisms (IsometricCanvas, PlatformerCanvas)
+ * so the verifier can snapshot canvas content at checkpoints.
+ */
+declare function bindCanvasCapture(captureFn: () => string | null): void;
+/**
+ * Bind a reader for the last drawables list received by a canvas host.
+ * Lets verification scripts inspect exactly which neutral descriptors reached
+ * the painter without re-deriving them from state.
+ */
+declare function bindLastDrawables(getDrawables: () => unknown[] | null): void;
+/**
+ * Update asset load status for canvas verification.
+ * Game organisms call this when images load or fail.
+ */
+declare function updateAssetStatus(url: string, status: AssetLoadStatus): void;
+declare function clearVerification(): void;
+
+/**
+ * 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 { parseMarkdownWithCodeBlocks as A, recordServerResponse as B, type ContentSegment as C, DEFAULT_CONFIG as D, type EntityDefinition as E, recordTransition as F, registerCheck as G, registerTraitSnapshot as H, renderStateMachineToDomData as I, renderStateMachineToSvg as J, subscribeToVerification as K, updateAssetStatus as L, updateBridgeHealth as M, updateCheck as N, waitForTransition as O, type RenderOptions as R, type StateDefinition as S, type TraitSnapshotGetter 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, type TransitionDefinition as h, bindCanvasCapture as i, bindEventBus as j, bindLastDrawables as k, bindTraitStateGetter as l, clearVerification as m, cn as n, extractOutputsFromTransitions as o, extractStateMachine as p, formatGuard as q, getAllChecks as r, getBridgeHealth as s, getEffectSummary as t, getSnapshot as u, getSummary as v, getTraitSnapshots as w, getTransitions as x, getTransitionsForTrait as y, parseContentSegments as z };