@almadar/ui 2.34.1 → 2.35.0

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

@@ -0,0 +1,13 @@
+/**
+ * EventFlowEdge
+ *
+ * React Flow edge for the V3 FlowCanvas. Shows the event name and
+ * optionally the trigger element (button label) that fires it.
+ *
+ * When the edge originates from a specific event source handle,
+ * the label shows "Button Label \u2192 EVENT" to make the connection
+ * between UI element and transition clear.
+ */
+import React from 'react';
+import { type EdgeProps } from '@xyflow/react';
+export declare const EventFlowEdge: React.NamedExoticComponent<EdgeProps>;

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

@@ -0,0 +1,38 @@
+/**
+ * OrbPreviewNode
+ *
+ * React Flow node that renders a real OrbPreview inside it.
+ * The canvas is always live and editable (like Figma). Clicking any
+ * rendered UI element selects its pattern and shows props in the
+ * TransitionPanel. No edit mode toggle needed.
+ *
+ * The header is the drag handle for React Flow. The content area
+ * passes clicks through to the pattern elements.
+ */
+import React from 'react';
+import { type NodeProps } from '@xyflow/react';
+import type { PreviewNodeData, ScreenSize } from './avl-preview-types';
+export declare const ScreenSizeContext: React.Context<ScreenSize>;
+/** Selected pattern info, emitted when user clicks a UI element in the node. */
+export interface SelectedPattern {
+    /** The pattern type (e.g., "button", "input", "stack"). */
+    patternType: string;
+    /** The DOM element's data-pattern-id if available. */
+    patternId?: string;
+    /** The node this pattern belongs to. */
+    nodeData: PreviewNodeData;
+    /** The source trait for this slot content. */
+    sourceTrait?: string;
+    /** Bounding rect relative to the node for floating inspector positioning. */
+    rect?: {
+        top: number;
+        left: number;
+        width: number;
+        height: number;
+    };
+}
+export declare const PatternSelectionContext: React.Context<{
+    selected: SelectedPattern | null;
+    select: (pattern: SelectedPattern | null) => void;
+}>;
+export declare const OrbPreviewNode: React.NamedExoticComponent<NodeProps>;

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

@@ -0,0 +1,35 @@
+/**
+ * AVL Preview Converter
+ *
+ * Extracts render-ui pattern configs from OrbitalSchema transitions
+ * and builds React Flow graphs for the two FlowCanvas levels:
+ *   - Overview: one node per orbital (INIT transition UI)
+ *   - Expanded: one node per UI state within an orbital
+ *
+ * Key feature: detects interactive elements (buttons, links) inside
+ * patterns that fire events. These become per-element source handles
+ * so edges connect from the specific trigger element to the target screen.
+ *
+ * Uses @almadar/core types for schema-level constructs.
+ */
+import type { Node, Edge } from '@xyflow/react';
+import type { OrbitalSchema } from '@almadar/core';
+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[]>): {
+    nodes: Node<PreviewNodeData>[];
+    edges: Edge<EventEdgeData>[];
+};
+/**
+ * Build a React Flow graph for the expanded level.
+ * Each transition with a render-ui effect gets a node.
+ * Edges connect from the specific button/pattern that fires the event
+ * to the target screen node.
+ */
+export declare function orbitalToExpandedGraph(schema: OrbitalSchema, orbitalName: string, mockData?: Record<string, unknown[]>): {
+    nodes: Node<PreviewNodeData>[];
+    edges: Edge<EventEdgeData>[];
+};

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

@@ -0,0 +1,108 @@
+/**
+ * AVL Preview Types
+ *
+ * Types for the V3 FlowCanvas: UI projection mode.
+ * Nodes show rendered UI thumbnails, edges show events.
+ * Two levels: overview (one node per orbital) and expanded (one node per UI state).
+ *
+ * Uses @almadar/core types for schema-level constructs.
+ */
+import type { Expression, UISlot } from '@almadar/core';
+/** The two navigation levels of the FlowCanvas. */
+export type ViewLevel = 'overview' | 'expanded';
+/** Screen size preset for OrbPreview rendering inside nodes. */
+export type ScreenSize = 'mobile' | 'tablet' | 'desktop';
+/** Width for each screen size preset. Height is auto (expands to fit content). */
+export declare const SCREEN_SIZE_PRESETS: Record<ScreenSize, {
+    width: number;
+    minHeight: number;
+    label: string;
+    icon: string;
+}>;
+/**
+ * An interactive element inside a render-ui pattern that fires an event.
+ * For example, a button with `event: "CHECKOUT"` is an event source.
+ * These are used to draw edges from the specific trigger element to the
+ * target screen, making the prototype flow concrete.
+ */
+export interface PatternEventSource {
+    /** The event name fired by this element (e.g., "CHECKOUT"). */
+    event: string;
+    /** The pattern type of the trigger element (e.g., "button", "link", "icon-button"). */
+    patternType: string;
+    /** Human label if available (e.g., "Checkout", "Submit"). */
+    label?: string;
+    /**
+     * Path within the pattern tree (e.g., "children.2" means third child).
+     * Used to position the handle near the trigger element.
+     */
+    path: string;
+    /** Vertical position hint (0..1) for handle placement on the node. */
+    positionHint: number;
+}
+/** A slot + pattern config pair extracted from a render-ui effect. */
+export interface RenderUIEntry {
+    slot: UISlot | string;
+    pattern: Record<string, unknown>;
+}
+/** Data for a preview node (used at both overview and expanded levels). */
+export interface PreviewNodeData extends Record<string, unknown> {
+    /** Orbital this node belongs to. */
+    orbitalName: string;
+    /** Trait name (only at expanded level). */
+    traitName?: string;
+    /** State name after this transition fires (expanded level). */
+    stateName?: string;
+    /** Event that triggers this transition (expanded level). */
+    transitionEvent?: string;
+    /** From state (expanded level). */
+    fromState?: string;
+    /** To state (expanded level). */
+    toState?: string;
+    /**
+     * Render-ui patterns extracted from the transition's effects.
+     * Each entry is a slot + pattern config pair.
+     */
+    patterns: RenderUIEntry[];
+    /**
+     * Interactive elements within the patterns that fire events.
+     * Each one becomes a source handle on the node, allowing edges
+     * to connect from the specific button/link to the target screen.
+     */
+    eventSources: PatternEventSource[];
+    /** State role for visual indicator. */
+    stateRole?: 'initial' | 'terminal' | 'hub' | 'error' | 'default';
+    /** All effect types on this transition (for overlay). */
+    effectTypes?: string[];
+    /** Guard expression (for overlay). */
+    guard?: Expression | null;
+    entityName?: string;
+    persistence?: string;
+    fieldCount?: number;
+    traitCount?: number;
+    pageRoutes?: string[];
+}
+/** Data for event flow edges. */
+export interface EventEdgeData extends Record<string, unknown> {
+    /** The event name displayed on the edge. */
+    event: string;
+    /** Source state name (expanded level). */
+    fromState?: string;
+    /** Target state name (expanded level). */
+    toState?: string;
+    /** Whether this is a backward/retry transition. */
+    isBackward?: boolean;
+    /** Whether this is a cross-orbital event wire (overview level). */
+    isCrossOrbital?: boolean;
+    /** Source trait (for cross-orbital wires). */
+    fromTrait?: string;
+    /** Target trait (for cross-orbital wires). */
+    toTrait?: string;
+    /**
+     * The pattern type that triggers this event (e.g., "button").
+     * Displayed on the edge label for context.
+     */
+    triggerPatternType?: string;
+    /** The trigger element's label (e.g., "Checkout"). */
+    triggerLabel?: string;
+}

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

@@ -23,6 +23,10 @@ export { AvlEventWireEdge, type AvlEventWireEdgeData, type AvlEventWireFlowEdge
 export { AvlBackwardEdge } from './AvlBackwardEdge';
 export { AvlPageEdge } from './AvlPageEdge';
 export { AvlBindingEdge } from './AvlBindingEdge';
+export { type ViewLevel, type PreviewNodeData, type EventEdgeData, type PatternEventSource, type RenderUIEntry, type ScreenSize, SCREEN_SIZE_PRESETS } from './avl-preview-types';
+export { schemaToOverviewGraph, orbitalToExpandedGraph } from './avl-preview-converter';
+export { OrbPreviewNode, ScreenSizeContext } from './OrbPreviewNode';
+export { EventFlowEdge } from './EventFlowEdge';
 export { Avl3DOrbitalNode, type Avl3DOrbitalNodeProps } from './Avl3DOrbitalNode';
 export { Avl3DCrossWire, type Avl3DCrossWireProps } from './Avl3DCrossWire';
 export { Avl3DEntityCore, type Avl3DEntityCoreProps } from './Avl3DEntityCore';

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

@@ -1,9 +1,9 @@
 /**
- * AvlCosmicZoom — Interactive Zoomable Orbital Visualization
+ * AvlCosmicZoom — Interactive Orbital Visualization
  *
- * V3: Delegates to FlowCanvas, which renders AVL primitives inside
- * React Flow nodes with continuous semantic zoom. The Props interface
- * is preserved for backward compatibility with callers.
+ * V3: Delegates to FlowCanvas. Nodes are live OrbPreview renders
+ * of each orbital/transition. Two-level navigation (overview + expanded).
+ * Props interface preserved for backward compatibility with callers.
  */
 import React from 'react';
 import type { OrbitalSchema } from '@almadar/core';

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

@@ -1,32 +1,47 @@
 /**
- * FlowCanvas — Unified AVL + Flow canvas organism.
+ * FlowCanvas — V3 UI Projection Canvas
  *
- * One React Flow canvas with continuous semantic zoom. AVL primitives
- * render inside React Flow nodes. The ZoomBandContext drives node
- * rendering at different zoom levels.
+ * The canvas IS the app. Nodes show rendered UI thumbnails from
+ * render-ui effects. Edges show events connecting screens.
  *
- * Replaces both AvlCosmicZoom (SVG viewer) and OrbitalFlow (Flow editor).
+ * Two navigation levels:
+ *   Level 1 (Overview): One node per orbital showing INIT UI
+ *   Level 2 (Expanded): One node per UI state within an orbital
+ *
+ * Double-click to expand an orbital. Click a node for code callback.
+ * Escape to go back. AVL overlays on hover (future).
  */
 import React from 'react';
 import type { OrbitalSchema } from '@almadar/core';
-import type { ZoomLevel } from './avl-zoom-state';
+import type { ViewLevel } from '../../molecules/avl/avl-preview-types';
 export interface FlowCanvasProps {
     schema: OrbitalSchema | string;
+    mockData?: Record<string, unknown[]>;
     className?: string;
-    color?: string;
-    animated?: boolean;
     width?: number | string;
     height?: number | string;
-    onZoomChange?: (level: ZoomLevel, context: {
-        orbital?: string;
+    onNodeClick?: (context: {
+        level: ViewLevel | 'code';
+        orbital: string;
         trait?: string;
+        transition?: string;
     }) => void;
+    onLevelChange?: (level: ViewLevel, orbital?: string) => void;
+    initialOrbital?: string;
+    /** @deprecated Use onNodeClick instead. Kept for AvlCosmicZoom compat. */
+    onZoomChange?: (level: string, context: Record<string, string | undefined>) => void;
+    /** @deprecated Not used in V3. */
     focusTarget?: {
-        type: 'orbital' | 'trait';
+        type: string;
         name: string;
     };
-    initialOrbital?: string;
+    /** @deprecated Not used in V3. */
+    color?: string;
+    /** @deprecated Not used in V3. */
+    animated?: boolean;
+    /** @deprecated Not used in V3. */
     initialTrait?: string;
-    stateCoverage?: Record<string, 'covered' | 'uncovered' | 'partial'>;
+    /** @deprecated Not used in V3. */
+    stateCoverage?: Record<string, string>;
 }
 export declare const FlowCanvas: React.FC<FlowCanvasProps>;

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

@@ -0,0 +1,20 @@
+/**
+ * TransitionPanel
+ *
+ * Shows the .orb transition details for a selected node in FlowCanvas.
+ * Built entirely with AVL primitives (AvlState, AvlEvent, AvlGuard,
+ * AvlEffect, AvlFieldType) so the developer learns the visual language
+ * while reading the code behind a screen.
+ *
+ * Renders in a side panel that appears when a node is clicked at Level 2.
+ */
+import React from 'react';
+import type { PreviewNodeData } from '../../molecules/avl/avl-preview-types';
+export interface TransitionPanelProps {
+    node: PreviewNodeData;
+    onClose: () => void;
+}
+export declare function TransitionPanel({ node, onClose }: TransitionPanelProps): React.ReactElement;
+export declare namespace TransitionPanel {
+    var displayName: string;
+}

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

@@ -97,7 +97,7 @@ var Camera3D = React21.forwardRef(
         newCamera = new THREE6__namespace.PerspectiveCamera(fov, viewport.aspect, 0.1, 1e3);
       }
       newCamera.position.copy(initialPosition.current);
-      newCamera.lookAt(initialTarget.current);
+      newCamera.lookAt(initialTarget.current.x, initialTarget.current.y, initialTarget.current.z);
       set({ camera: newCamera });
       if (mode === "top-down") {
         newCamera.position.set(0, 20 / zoom, 0);
@@ -128,7 +128,7 @@ var Camera3D = React21.forwardRef(
       },
       reset: () => {
         camera.position.copy(initialPosition.current);
-        camera.lookAt(initialTarget.current);
+        camera.lookAt(initialTarget.current.x, initialTarget.current.y, initialTarget.current.z);
         if (controlsRef.current) {
           controlsRef.current.target.copy(initialTarget.current);
           controlsRef.current.update();
@@ -147,7 +147,7 @@ var Camera3D = React21.forwardRef(
         ref: controlsRef,
         camera,
         enabled: enableOrbit,
-        target: initialTarget.current,
+        target: [initialTarget.current.x, initialTarget.current.y, initialTarget.current.z],
         minDistance,
         maxDistance,
         maxPolarAngle,
@@ -4204,7 +4204,7 @@ var Avl3DCrossWire = ({
   }, [from, to]);
   return /* @__PURE__ */ jsxRuntime.jsxs("group", { children: [
     /* @__PURE__ */ jsxRuntime.jsxs("mesh", { children: [
-      /* @__PURE__ */ jsxRuntime.jsx("tubeGeometry", { args: tubeArgs }),
+      /* @__PURE__ */ jsxRuntime.jsx("tubeGeometry", { args: [tubeArgs[0], tubeArgs[1], tubeArgs[2], tubeArgs[3], tubeArgs[4]] }),
       /* @__PURE__ */ jsxRuntime.jsx(
         "meshStandardMaterial",
         {
@@ -4917,7 +4917,7 @@ var Avl3DTransitionArc = ({
           document.body.style.cursor = "auto";
         },
         children: [
-          /* @__PURE__ */ jsxRuntime.jsx("tubeGeometry", { args: tubeArgs }),
+          /* @__PURE__ */ jsxRuntime.jsx("tubeGeometry", { args: [tubeArgs[0], tubeArgs[1], tubeArgs[2], tubeArgs[3], tubeArgs[4]] }),
           /* @__PURE__ */ jsxRuntime.jsx(
             "meshStandardMaterial",
             {
@@ -5502,7 +5502,7 @@ function CameraController2({ targetPosition, targetLookAt, animated }) {
         isAnimating.current = true;
       } else {
         camera.position.copy(targetPosVec.current);
-        camera.lookAt(targetLookVec.current);
+        camera.lookAt(targetLookVec.current.x, targetLookVec.current.y, targetLookVec.current.z);
       }
     }
   }, [targetPosition, targetLookAt, animated, camera]);

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

@@ -73,7 +73,7 @@ var Camera3D = forwardRef(
         newCamera = new THREE6.PerspectiveCamera(fov, viewport.aspect, 0.1, 1e3);
       }
       newCamera.position.copy(initialPosition.current);
-      newCamera.lookAt(initialTarget.current);
+      newCamera.lookAt(initialTarget.current.x, initialTarget.current.y, initialTarget.current.z);
       set({ camera: newCamera });
       if (mode === "top-down") {
         newCamera.position.set(0, 20 / zoom, 0);
@@ -104,7 +104,7 @@ var Camera3D = forwardRef(
       },
       reset: () => {
         camera.position.copy(initialPosition.current);
-        camera.lookAt(initialTarget.current);
+        camera.lookAt(initialTarget.current.x, initialTarget.current.y, initialTarget.current.z);
         if (controlsRef.current) {
           controlsRef.current.target.copy(initialTarget.current);
           controlsRef.current.update();
@@ -123,7 +123,7 @@ var Camera3D = forwardRef(
         ref: controlsRef,
         camera,
         enabled: enableOrbit,
-        target: initialTarget.current,
+        target: [initialTarget.current.x, initialTarget.current.y, initialTarget.current.z],
         minDistance,
         maxDistance,
         maxPolarAngle,
@@ -4180,7 +4180,7 @@ var Avl3DCrossWire = ({
   }, [from, to]);
   return /* @__PURE__ */ jsxs("group", { children: [
     /* @__PURE__ */ jsxs("mesh", { children: [
-      /* @__PURE__ */ jsx("tubeGeometry", { args: tubeArgs }),
+      /* @__PURE__ */ jsx("tubeGeometry", { args: [tubeArgs[0], tubeArgs[1], tubeArgs[2], tubeArgs[3], tubeArgs[4]] }),
       /* @__PURE__ */ jsx(
         "meshStandardMaterial",
         {
@@ -4893,7 +4893,7 @@ var Avl3DTransitionArc = ({
           document.body.style.cursor = "auto";
         },
         children: [
-          /* @__PURE__ */ jsx("tubeGeometry", { args: tubeArgs }),
+          /* @__PURE__ */ jsx("tubeGeometry", { args: [tubeArgs[0], tubeArgs[1], tubeArgs[2], tubeArgs[3], tubeArgs[4]] }),
           /* @__PURE__ */ jsx(
             "meshStandardMaterial",
             {
@@ -5478,7 +5478,7 @@ function CameraController2({ targetPosition, targetLookAt, animated }) {
         isAnimating.current = true;
       } else {
         camera.position.copy(targetPosVec.current);
-        camera.lookAt(targetLookVec.current);
+        camera.lookAt(targetLookVec.current.x, targetLookVec.current.y, targetLookVec.current.z);
       }
     }
   }, [targetPosition, targetLookAt, animated, camera]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "2.34.1",
+  "version": "2.35.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",
@@ -84,6 +84,11 @@
       "import": "./dist/avl/index.js",
       "require": "./dist/avl/index.cjs"
     },
+    "./illustrations": {
+      "types": "./dist/avl/index.d.ts",
+      "import": "./dist/avl/index.js",
+      "require": "./dist/avl/index.cjs"
+    },
     "./flow": {
       "types": "./dist/flow/index.d.ts",
       "import": "./dist/flow/index.js",