@almadar/ui 2.43.0 → 2.46.0

package/dist/components/molecules/avl/BehaviorComposeNode.d.ts

@@ -0,0 +1,13 @@
+/**
+ * BehaviorComposeNode
+ *
+ * React Flow custom node for behavior-level composition.
+ * Shows AvlBehaviorGlyph instead of live UI (OrbPreview).
+ * Each behavior is one compact node with event handles for wiring.
+ *
+ * This is the compose-level node. Double-clicking drills into
+ * the orbital-level view (OrbPreviewNode).
+ */
+import React from 'react';
+import { type NodeProps } from '@xyflow/react';
+export declare const BehaviorComposeNode: React.NamedExoticComponent<NodeProps>;

package/dist/components/molecules/avl/avl-behavior-compose-converter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * AVL Behavior Compose Converter
+ *
+ * Converts BehaviorCanvasEntry[] to React Flow nodes and edges
+ * for the behavior-level composition canvas.
+ *
+ * Parallel to avl-preview-converter.ts which works at the orbital level.
+ * This works one level higher: each node is a behavior (not an orbital).
+ */
+import type { Node, Edge } from '@xyflow/react';
+import type { BehaviorCanvasEntry, BehaviorComposeNodeData, BehaviorWireEdgeData } from './avl-behavior-compose-types';
+/**
+ * Build a React Flow graph for behavior-level composition.
+ * Each behavior entry becomes one BehaviorComposeNode.
+ */
+export declare function behaviorsToComposeGraph(entries: BehaviorCanvasEntry[], wires: BehaviorWireEdgeData[], layoutHint?: 'pipeline' | 'grid'): {
+    nodes: Node<BehaviorComposeNodeData>[];
+    edges: Edge<BehaviorWireEdgeData>[];
+};
+/** Registry record shape (matches behaviors-registry.json entries). */
+export interface BehaviorRegistryRecord {
+    name: string;
+    level: 'atom' | 'molecule' | 'organism';
+    family: string;
+    layer: string;
+    description: string;
+    complexity: {
+        states: number;
+        events: number;
+        transitions: number;
+    };
+    defaultEntity: {
+        name: string;
+        persistence?: string;
+        fields: Array<{
+            name: string;
+            type: string;
+            required?: boolean;
+        }>;
+    };
+    connectableEvents: string[];
+    eventPayloads: Record<string, Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+    }>>;
+    composableWith: string[];
+}
+/**
+ * Convert a registry entry to a BehaviorCanvasEntry.
+ * Maps connectableEvents + eventPayloads into typed ConnectableEvent[].
+ */
+export declare function registryEntryToCanvasEntry(entry: BehaviorRegistryRecord, orbitalNames: string[]): BehaviorCanvasEntry;

package/dist/components/molecules/avl/avl-behavior-compose-types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * AVL Behavior Compose Types
+ *
+ * Types for behavior-level composition canvas.
+ * At this level, each node represents a BEHAVIOR (not an orbital).
+ * A behavior is a higher-level unit: atom (1 orbital), molecule (1 orbital
+ * with composed traits), or organism (multiple orbitals).
+ *
+ * Three navigation levels:
+ *   Behavior (compose): One node per behavior showing AvlBehaviorGlyph
+ *   Overview: One node per orbital showing live UI (OrbPreviewNode)
+ *   Expanded: One node per UI state within an orbital (OrbPreviewNode)
+ */
+import type { EntityPersistence, EventPayloadField } from '@almadar/core';
+import type { BehaviorLevel, BehaviorGlyphChild, BehaviorGlyphConnection } from './AvlBehaviorGlyph';
+import type { AvlEffectType } from '../../atoms/avl/types';
+/** Extended view level adding 'behavior' to the existing overview/expanded. */
+export type ComposeViewLevel = 'behavior' | 'overview' | 'expanded';
+/** An event that can be wired between behaviors. */
+export interface ConnectableEvent {
+    /** Event name (e.g., "ADD_TO_CART"). */
+    event: string;
+    /** Typed payload fields if declared. */
+    payloadFields?: EventPayloadField[];
+    /** Vertical position hint (0..1) for handle placement on the node. */
+    positionHint: number;
+}
+/** Data for a BehaviorComposeNode in React Flow. */
+export interface BehaviorComposeNodeData extends Record<string, unknown> {
+    /** Behavior name from registry (e.g., "std-cart"). */
+    behaviorName: string;
+    /** Composition level: atom, molecule, organism. */
+    level: BehaviorLevel;
+    /** Domain for color coding (e.g., "commerce"). */
+    domain?: string;
+    /** Layer classification (e.g., "Domain", "UI Patterns"). */
+    layer?: string;
+    /** Primary entity name (e.g., "CartItem"). */
+    entityName: string;
+    /** Number of states in the behavior. */
+    stateCount: number;
+    /** Number of entity fields. */
+    fieldCount?: number;
+    /** Persistence kind. */
+    persistence?: EntityPersistence;
+    /** Effect types used by this behavior. */
+    effectTypes?: AvlEffectType[];
+    /** Child behaviors for molecule/organism glyphs. */
+    children?: BehaviorGlyphChild[];
+    /** Connections between children (for organism glyphs). */
+    connections?: BehaviorGlyphConnection[];
+    /** Events this behavior can emit (source handles). */
+    connectableEvents: ConnectableEvent[];
+    /** Behaviors this is composable with (for palette hints). */
+    composableWith?: string[];
+    /** Names of orbitals produced by this behavior (for drill-down). */
+    orbitalNames: string[];
+}
+/** Edge data for behavior-level wiring. */
+export interface BehaviorWireEdgeData extends Record<string, unknown> {
+    /** The event name displayed on the edge. */
+    event: string;
+    /** Source behavior name. */
+    sourceBehavior: string;
+    /** Target behavior name. */
+    targetBehavior: string;
+    /** Typed payload fields if declared. */
+    payloadFields?: EventPayloadField[];
+}
+/** Mapping from behavior name to its metadata + produced orbitals. */
+export interface BehaviorCanvasEntry {
+    /** Behavior name (e.g., "std-cart"). */
+    behaviorName: string;
+    /** Composition level. */
+    level: BehaviorLevel;
+    /** Domain for color coding. */
+    domain?: string;
+    /** Layer classification. */
+    layer?: string;
+    /** Primary entity name. */
+    entityName: string;
+    /** Number of states. */
+    stateCount: number;
+    /** Number of entity fields. */
+    fieldCount?: number;
+    /** Persistence kind. */
+    persistence?: EntityPersistence;
+    /** Effect types used. */
+    effectTypes?: AvlEffectType[];
+    /** Child behaviors (molecule/organism). */
+    children?: BehaviorGlyphChild[];
+    /** Connections between children (organism). */
+    connections?: BehaviorGlyphConnection[];
+    /** Events available for wiring. */
+    connectableEvents: ConnectableEvent[];
+    /** Compatible behavior names. */
+    composableWith?: string[];
+    /** Orbital names produced by this behavior (for drill-down mapping). */
+    orbitalNames: string[];
+}

package/dist/components/molecules/avl/avl-preview-converter.d.ts

@@ -19,7 +19,9 @@ import type { PreviewNodeData, EventEdgeData } from './avl-preview-types';
  * Build a React Flow graph for the overview level.
  * Each orbital gets one node showing its INIT transition's UI.
  */
-export declare function schemaToOverviewGraph(schema: OrbitalSchema, mockData?: Record<string, unknown[]>): {
+export declare function schemaToOverviewGraph(schema: OrbitalSchema, mockData?: Record<string, unknown[]>, behaviorMeta?: Record<string, {
+    layer: string;
+}>, layoutHint?: 'pipeline' | 'grid'): {
     nodes: Node<PreviewNodeData>[];
     edges: Edge<EventEdgeData>[];
 };

package/dist/components/molecules/avl/avl-preview-types.d.ts

@@ -39,6 +39,12 @@ export interface PatternEventSource {
     path: string;
     /** Vertical position hint (0..1) for handle placement on the node. */
     positionHint: number;
+    /** Typed payload fields if this event carries data. */
+    payloadFields?: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+    }>;
 }
 /** A slot + pattern config pair extracted from a render-ui effect. */
 export interface RenderUIEntry {
@@ -70,6 +76,8 @@ export interface PreviewNodeData extends Record<string, unknown> {
      * to connect from the specific button/link to the target screen.
      */
     eventSources: PatternEventSource[];
+    /** Behavior layer for visual indicator (color band). */
+    layer?: string;
     /** State role for visual indicator. */
     stateRole?: 'initial' | 'terminal' | 'hub' | 'error' | 'default';
     /** All effect types on this transition (for overlay). */

package/dist/components/molecules/avl/index.d.ts

@@ -27,6 +27,9 @@ export { type ViewLevel, type PreviewNodeData, type EventEdgeData, type PatternE
 export { schemaToOverviewGraph, orbitalToExpandedGraph } from './avl-preview-converter';
 export { OrbPreviewNode, ScreenSizeContext } from './OrbPreviewNode';
 export { EventFlowEdge } from './EventFlowEdge';
+export { type ComposeViewLevel, type BehaviorComposeNodeData, type BehaviorWireEdgeData, type BehaviorCanvasEntry, type ConnectableEvent } from './avl-behavior-compose-types';
+export { BehaviorComposeNode } from './BehaviorComposeNode';
+export { behaviorsToComposeGraph, registryEntryToCanvasEntry, type BehaviorRegistryRecord } from './avl-behavior-compose-converter';
 export { Avl3DOrbitalNode, type Avl3DOrbitalNodeProps } from './Avl3DOrbitalNode';
 export { Avl3DCrossWire, type Avl3DCrossWireProps } from './Avl3DCrossWire';
 export { Avl3DEntityCore, type Avl3DEntityCoreProps } from './Avl3DEntityCore';

package/dist/components/molecules/avl/wire-validation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Wire Validation
+ *
+ * Validates event wire compatibility between behaviors based on typed payloads.
+ * Used by FlowCanvas when the user drags between event handles.
+ */
+export interface PayloadField {
+    name: string;
+    type: string;
+    required?: boolean;
+}
+export interface WireValidationResult {
+    valid: boolean;
+    warnings: string[];
+}
+/**
+ * Validate that a wire between two event handles is payload-compatible.
+ *
+ * Rules:
+ * - If neither side declares a payload, the wire is valid (no data contract).
+ * - If source has payload but target doesn't, valid with info (data is unused).
+ * - If target expects required fields that source doesn't provide, warn.
+ * - If both have fields with the same name but different types, warn.
+ */
+export declare function validateWire(sourcePayload: PayloadField[] | undefined, targetPayload: PayloadField[] | undefined): WireValidationResult;
+/**
+ * Format payload fields into a tooltip string.
+ * Example: "{ data: object (req), query: string }"
+ */
+export declare function formatPayloadTooltip(fields: PayloadField[]): string;

package/dist/components/organisms/avl/FlowCanvas.d.ts

@@ -14,6 +14,7 @@
 import React from 'react';
 import type { OrbitalSchema } from '@almadar/core';
 import type { ViewLevel, PreviewNodeData } from '../../molecules/avl/avl-preview-types';
+import type { ComposeViewLevel, BehaviorCanvasEntry, BehaviorWireEdgeData } from '../../molecules/avl/avl-behavior-compose-types';
 export interface FlowCanvasProps {
     schema: OrbitalSchema | string;
     mockData?: Record<string, unknown[]>;
@@ -28,6 +29,10 @@ export interface FlowCanvasProps {
     }) => void;
     onLevelChange?: (level: ViewLevel, orbital?: string) => void;
     initialOrbital?: string;
+    /** Start at Level 2 (expanded) when initialOrbital is set. Default: 'overview'. */
+    initialLevel?: ViewLevel;
+    /** Pre-select a node on mount (opens OrbInspector). */
+    initialSelectedNode?: PreviewNodeData;
     /** Enable editing in the inspector. When true, fields become inputs. */
     editable?: boolean;
     /** Called when the user edits the schema via the inspector. */
@@ -45,6 +50,20 @@ export interface FlowCanvasProps {
         sourceTraitName?: string;
         targetTraitName?: string;
     }) => void;
+    /** Behavior layer metadata for node styling (layer color bands). */
+    behaviorMeta?: Record<string, {
+        layer: string;
+    }>;
+    /** Layout hint: 'pipeline' renders nodes left-to-right, 'grid' (default) uses sqrt-based grid. */
+    layoutHint?: 'pipeline' | 'grid';
+    /** Called when the user clicks a node in overview level (for composition hints). */
+    onNodeSelect?: (orbitalName: string) => void;
+    /** When 'behavior', shows behavior-level glyph nodes instead of orbital previews. */
+    composeLevel?: ComposeViewLevel;
+    /** Behavior entries for compose mode (only when composeLevel='behavior'). */
+    behaviorEntries?: BehaviorCanvasEntry[];
+    /** Event wires between behaviors (only when composeLevel='behavior'). */
+    behaviorWires?: BehaviorWireEdgeData[];
     /** @deprecated Use onNodeClick instead. Kept for AvlCosmicZoom compat. */
     onZoomChange?: (level: string, context: Record<string, string | undefined>) => void;
     /** @deprecated Not used in V3. */

package/dist/components/organisms/debug/WalkMinimap.d.ts

@@ -0,0 +1,17 @@
+/**
+ * WalkMinimap
+ *
+ * Visual minimap for orbital-verify state walks.
+ * Shows trait overview pills, state graph for active trait,
+ * and coverage progress. Replaces the text-based walk step indicator.
+ *
+ * Data comes from window.__orbitalWalkStep, window.__orbitalWalkTraits,
+ * and window.__orbitalCoveredEdges (broadcast by phase4-browser.ts).
+ *
+ * @packageDocumentation
+ */
+import * as React from 'react';
+export declare function WalkMinimap(): React.ReactElement | null;
+export declare namespace WalkMinimap {
+    var displayName: string;
+}