@almadar/ui 4.54.5 → 4.54.7

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

@@ -0,0 +1,33 @@
+/**
+ * TraitCardNode — React Flow node for the `trait-expanded` view level.
+ *
+ * Renders one card per trait of a single orbital. The card body shows
+ * the trait's state-machine flow chart (states + transitions, laid out
+ * by ELK) via the existing `AvlTraitScene` organism. Clicking a
+ * transition arc drills into L4 transition detail.
+ *
+ * Left edge has one target handle per `listens[]` event; right edge
+ * has one source handle per `emits[]` event. Edges produced by
+ * `orbitalToTraitGraph` connect emit handles to listen handles where
+ * the event names match within the same orbital.
+ *
+ * Transition clicks bubble through `TraitCardSelectionContext`
+ * (mirrors `PatternSelectionContext` in `OrbPreviewNode`). FlowCanvas
+ * wraps the canvas in a provider that translates the context callback
+ * into its `onNodeClick({ level: 'transition', ... })` prop.
+ */
+import React from 'react';
+import { type NodeProps } from '@xyflow/react';
+export interface TraitCardTransitionClick {
+    orbitalName: string;
+    traitName: string;
+    transitionEvent: string;
+    fromState: string;
+    toState: string;
+    index: number;
+}
+export interface TraitCardSelectionContextValue {
+    selectTransition: (sel: TraitCardTransitionClick) => void;
+}
+export declare const TraitCardSelectionContext: React.Context<TraitCardSelectionContextValue>;
+export declare const TraitCardNode: React.NamedExoticComponent<NodeProps>;

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

@@ -51,3 +51,21 @@ export declare function orbitalAliasToExpandedGraph(schema: OrbitalSchema, orbit
     nodes: Node<PreviewNodeData>[];
     edges: Edge<EventEdgeData>[];
 };
+/**
+ * Build a React Flow graph for the `trait-expanded` level: one node per
+ * trait of `orbitalName`, with intra-orbital `emits → listens` edges
+ * between trait cards (an emit on trait A connects to a listen for the
+ * same event on trait B in the same orbital).
+ *
+ * Used by the cosmic tab at L3 (after the user drills into an orbital
+ * from the L1 grid). The canvas tab does not call this today; the new
+ * level is opt-in via `initialLevel="trait-expanded"`.
+ *
+ * Layout: grid (`ceil(sqrt(N))` cols). Nodes are `type: 'traitCard'`
+ * with `data.kind === 'trait-card'` so `FlowCanvas`'s NODE_TYPES routes
+ * them to `TraitCardNode`.
+ */
+export declare function orbitalToTraitGraph(schema: OrbitalSchema, orbitalName: string, _mockData?: Record<string, unknown[]>): {
+    nodes: Node<PreviewNodeData>[];
+    edges: Edge<EventEdgeData>[];
+};

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

@@ -18,8 +18,12 @@ import type { Expression, UISlot } from '@almadar/core';
  * - `behavior-expanded` (L3) — drilled into a single imported behavior at
  *   L2: one card per transition of THAT behavior. Used to inspect what an
  *   import contributes without leaving the canvas.
+ * - `trait-expanded` — one card per trait of a single orbital, connected
+ *   by intra-orbital `emits → listens` edges. Used by the cosmic tab to
+ *   render the trait-level circuit when the user drills into an orbital
+ *   from the L1 grid. Not used by the canvas tab today.
  */
-export type ViewLevel = 'overview' | 'expanded' | 'behavior-expanded';
+export type ViewLevel = 'overview' | 'expanded' | 'behavior-expanded' | 'trait-expanded';
 /**
  * Screen size preset for OrbPreview rendering inside nodes.
  *
@@ -162,6 +166,42 @@ export interface PreviewNodeData extends Record<string, unknown> {
      * card. Renderer can surface it as a "+N screens" badge.
      */
     transitionCount?: number;
+    /**
+     * Discriminator for the node variant. Absent on overview/expanded/
+     * behavior-expanded cards (those use field-presence-based discrimination
+     * via `behaviorAlias`/`transitionEvent`). Set to `'trait-card'` for nodes
+     * produced by `orbitalToTraitGraph` so renderers can branch cleanly.
+     */
+    kind?: 'trait-card';
+    /**
+     * Trait-card transitions (`kind === 'trait-card'` only). One row per
+     * transition; each row is clickable and drills to L4 transition detail
+     * in cosmic. `event` is the trigger; `fromState` / `toState` mirror the
+     * underlying state-machine edge.
+     */
+    transitions?: Array<{
+        event: string;
+        fromState: string;
+        toState: string;
+    }>;
+    /**
+     * Trait-card `emits` event names (`kind === 'trait-card'` only). One
+     * source handle per entry on the right edge of the card. Drives the
+     * outgoing wire endpoints in `orbitalToTraitGraph`.
+     */
+    emits?: string[];
+    /**
+     * Trait-card `listens` event names (`kind === 'trait-card'` only). One
+     * target handle per entry on the left edge of the card. Drives the
+     * incoming wire endpoints in `orbitalToTraitGraph`.
+     */
+    listens?: string[];
+    /**
+     * Trait-card `linkedEntity` (`kind === 'trait-card'` only). Surfaced as a
+     * subtitle/badge next to the trait name so users can see what entity the
+     * trait operates on. Mirrors `Trait.linkedEntity` from the resolved schema.
+     */
+    linkedEntity?: string;
 }
 /** Data for event flow edges. */
 export interface EventEdgeData extends Record<string, unknown> {

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

@@ -22,7 +22,7 @@ export interface FlowCanvasProps {
     width?: number | string;
     height?: number | string;
     onNodeClick?: (context: {
-        level: ViewLevel | 'code';
+        level: ViewLevel | 'code' | 'transition';
         orbital: string;
         trait?: string;
         transition?: string;

package/dist/components/organisms/avl/avl-zoom-state.d.ts

@@ -4,6 +4,12 @@
  * useReducer-based state machine managing which zoom level is displayed,
  * what is selected, and animation state.
  *
+ * Shared by AvlOrbitalsCosmicZoom (2D) and Avl3DViewer (3D). The 3D
+ * viewer drills through every level (`application → orbital → trait →
+ * transition`); the 2D cosmic view skips the `'orbital'` level after
+ * COSMIC-1 (no Orbital-View screen) by dispatching `JUMP_TO_TRAIT_CIRCUIT`
+ * to land directly at `'trait'`.
+ *
  * @packageDocumentation
  */
 export type ZoomLevel = 'application' | 'orbital' | 'trait' | 'transition';
@@ -50,6 +56,12 @@ export type ZoomAction = {
 } | {
     type: 'SWITCH_TRAIT';
     trait: string;
+} | {
+    type: 'JUMP_TO_TRAIT_CIRCUIT';
+    orbital: string;
+} | {
+    type: 'SELECT_TRAIT';
+    trait: string;
 };
 export declare const initialZoomState: ZoomState;
 export declare function zoomReducer(state: ZoomState, action: ZoomAction): ZoomState;

package/dist/components/organisms/game/three/index.cjs

@@ -3707,6 +3707,22 @@ function zoomReducer(state, action) {
         selectedTransition: action.transitionIndex
       };
     }
+    case "JUMP_TO_TRAIT_CIRCUIT": {
+      if (state.level !== "application" || state.animating) return state;
+      return {
+        ...state,
+        level: "trait",
+        selectedOrbital: action.orbital,
+        selectedTrait: null,
+        selectedTransition: null,
+        animating: false,
+        animationDirection: "in",
+        animationTarget: null
+      };
+    }
+    case "SELECT_TRAIT": {
+      return { ...state, selectedTrait: action.trait };
+    }
     case "ZOOM_OUT": {
       if (state.level === "application" || state.animating) return state;
       return {
@@ -3739,7 +3755,8 @@ function zoomReducer(state, action) {
       if (state.level === "trait") {
         return {
           ...state,
-          level: "orbital",
+          level: "application",
+          selectedOrbital: null,
           selectedTrait: null,
           animating: false,
           animationTarget: null

package/dist/components/organisms/game/three/index.js

@@ -3683,6 +3683,22 @@ function zoomReducer(state, action) {
         selectedTransition: action.transitionIndex
       };
     }
+    case "JUMP_TO_TRAIT_CIRCUIT": {
+      if (state.level !== "application" || state.animating) return state;
+      return {
+        ...state,
+        level: "trait",
+        selectedOrbital: action.orbital,
+        selectedTrait: null,
+        selectedTransition: null,
+        animating: false,
+        animationDirection: "in",
+        animationTarget: null
+      };
+    }
+    case "SELECT_TRAIT": {
+      return { ...state, selectedTrait: action.trait };
+    }
     case "ZOOM_OUT": {
       if (state.level === "application" || state.animating) return state;
       return {
@@ -3715,7 +3731,8 @@ function zoomReducer(state, action) {
       if (state.level === "trait") {
         return {
           ...state,
-          level: "orbital",
+          level: "application",
+          selectedOrbital: null,
           selectedTrait: null,
           animating: false,
           animationTarget: null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "4.54.5",
+  "version": "4.54.7",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "sideEffects": [