@almadar/ui 5.125.0 → 5.127.0

package/dist/avl/index.d.cts

@@ -0,0 +1,1859 @@
+import * as React from 'react';
+import React__default from 'react';
+import { JsonObject, JsonValue, OrbitalSchema, Expression, UISlot, EntityData, EditFocus, EventPayload, ThemeDefinition } from '@almadar/core';
+import { Node, Edge, NodeProps, EdgeProps } from '@xyflow/react';
+import { AnyPatternConfig } from '@almadar/core/patterns';
+import { useDraggable } from '@dnd-kit/core';
+
+/**
+ * Almadar Visual Language (AVL) shared types.
+ *
+ * Every AVL atom renders a `<g>` element (not `<svg>`) and accepts
+ * AvlBaseProps for positioning and styling within a parent SVG.
+ */
+interface AvlBaseProps {
+    x?: number;
+    y?: number;
+    color?: string;
+    opacity?: number;
+    className?: string;
+}
+type AvlEffectType = 'render-ui' | 'set' | 'persist' | 'fetch' | 'emit' | 'navigate' | 'notify' | 'call-service' | 'spawn' | 'despawn' | 'do' | 'if' | 'log';
+type AvlFieldTypeKind = 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'object' | 'array';
+type AvlPersistenceKind = 'persistent' | 'runtime' | 'singleton' | 'instance';
+type AvlOperatorNamespace = 'arithmetic' | 'comparison' | 'logic' | 'string' | 'collection' | 'time' | 'control' | 'async';
+declare const AVL_OPERATOR_COLORS: Record<AvlOperatorNamespace, string>;
+declare const AVL_FIELD_TYPE_SHAPES: Record<AvlFieldTypeKind, string>;
+type StateRole = 'initial' | 'terminal' | 'hub' | 'error' | 'default';
+declare const STATE_COLORS: Record<StateRole, {
+    fill: string;
+    border: string;
+}>;
+type EffectCategory = 'ui' | 'data' | 'communication' | 'lifecycle' | 'control';
+declare const EFFECT_CATEGORY_COLORS: Record<EffectCategory, {
+    color: string;
+    bg: string;
+}>;
+declare const EFFECT_TYPE_TO_CATEGORY: Record<AvlEffectType, EffectCategory>;
+declare const CONNECTION_COLORS: {
+    readonly forward: {
+        readonly color: "#1E293B";
+        readonly width: 2;
+        readonly dash: "none";
+    };
+    readonly backward: {
+        readonly color: "#94A3B8";
+        readonly width: 1.5;
+        readonly dash: "6 3";
+    };
+    readonly selfLoop: {
+        readonly color: "#CBD5E1";
+        readonly width: 1;
+        readonly dash: "3 2";
+    };
+    readonly emitListen: {
+        readonly color: "#F97316";
+        readonly width: 1.5;
+        readonly dash: "4 3";
+    };
+};
+declare function getStateRole(name: string, isInitial?: boolean, isTerminal?: boolean, transitionCount?: number, maxTransitionCount?: number): StateRole;
+
+interface AvlOrbitalProps {
+    cx?: number;
+    cy?: number;
+    r?: number;
+    label?: string;
+    color?: string;
+    opacity?: number;
+    className?: string;
+}
+declare const AvlOrbital: React__default.FC<AvlOrbitalProps>;
+
+interface AvlEntityProps extends AvlBaseProps {
+    r?: number;
+    fieldCount?: number;
+    persistence?: AvlPersistenceKind;
+    label?: string;
+}
+declare const AvlEntity: React__default.FC<AvlEntityProps>;
+
+interface AvlTraitProps {
+    cx?: number;
+    cy?: number;
+    rx?: number;
+    ry?: number;
+    rotation?: number;
+    label?: string;
+    color?: string;
+    opacity?: number;
+    className?: string;
+}
+declare const AvlTrait: React__default.FC<AvlTraitProps>;
+
+interface AvlPageProps extends AvlBaseProps {
+    size?: number;
+    label?: string;
+}
+declare const AvlPage: React__default.FC<AvlPageProps>;
+
+interface AvlApplicationProps extends AvlBaseProps {
+    width?: number;
+    height?: number;
+    label?: string;
+}
+declare const AvlApplication: React__default.FC<AvlApplicationProps>;
+
+interface AvlStateProps extends AvlBaseProps {
+    name?: string;
+    isInitial?: boolean;
+    isTerminal?: boolean;
+    width?: number;
+    height?: number;
+    /** V2: Role-based fill color. When set, overrides monochrome rendering. */
+    role?: StateRole;
+    /** V2: Number of transitions touching this state. Drives proportional width. */
+    transitionCount?: number;
+}
+declare const AvlState: React__default.FC<AvlStateProps>;
+
+interface AvlTransitionProps {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    curved?: boolean;
+    /** Center point to curve away from (curves outward if provided). */
+    curveAwayFrom?: {
+        x: number;
+        y: number;
+    };
+    label?: string;
+    color?: string;
+    opacity?: number;
+    className?: string;
+}
+declare const AvlTransition: React__default.FC<AvlTransitionProps>;
+
+interface AvlEventProps extends AvlBaseProps {
+    size?: number;
+    label?: string;
+}
+declare const AvlEvent: React__default.FC<AvlEventProps>;
+
+interface AvlGuardProps extends AvlBaseProps {
+    size?: number;
+    label?: string;
+}
+declare const AvlGuard: React__default.FC<AvlGuardProps>;
+
+interface AvlEffectProps extends AvlBaseProps {
+    effectType: AvlEffectType;
+    size?: number;
+    label?: string;
+    /** V2: Render a category-colored background circle behind the icon. */
+    showBackground?: boolean;
+}
+declare const AvlEffect: React__default.FC<AvlEffectProps>;
+
+interface AvlFieldProps extends AvlBaseProps {
+    /** Angle in radians from entity center. */
+    angle?: number;
+    length?: number;
+    required?: boolean;
+    label?: string;
+}
+declare const AvlField: React__default.FC<AvlFieldProps>;
+
+interface AvlFieldTypeProps extends AvlBaseProps {
+    kind: AvlFieldTypeKind;
+    size?: number;
+    label?: string;
+}
+declare const AvlFieldType: React__default.FC<AvlFieldTypeProps>;
+
+interface AvlBindingProps {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    label?: string;
+    color?: string;
+    opacity?: number;
+    className?: string;
+}
+declare const AvlBinding: React__default.FC<AvlBindingProps>;
+
+interface AvlPersistenceProps extends AvlBaseProps {
+    kind: AvlPersistenceKind;
+    size?: number;
+    label?: string;
+}
+declare const AvlPersistence: React__default.FC<AvlPersistenceProps>;
+
+interface AvlOperatorProps extends AvlBaseProps {
+    name: string;
+    namespace?: AvlOperatorNamespace;
+    size?: number;
+}
+declare const AvlOperator: React__default.FC<AvlOperatorProps>;
+
+interface AvlSExprProps extends AvlBaseProps {
+    width?: number;
+    height?: number;
+    label?: string;
+}
+declare const AvlSExpr: React__default.FC<AvlSExprProps>;
+
+interface AvlLiteralProps extends AvlBaseProps {
+    value: string;
+    size?: number;
+}
+declare const AvlLiteral: React__default.FC<AvlLiteralProps>;
+
+interface AvlBindingRefProps extends AvlBaseProps {
+    path: string;
+    size?: number;
+}
+declare const AvlBindingRef: React__default.FC<AvlBindingRefProps>;
+
+interface AvlStateMachineState {
+    name: string;
+    isInitial?: boolean;
+    isTerminal?: boolean;
+}
+interface AvlStateMachineTransition {
+    from: string;
+    to: string;
+    event?: string;
+    guard?: string;
+    effects?: AvlEffectType[];
+}
+interface AvlStateMachineProps {
+    states: AvlStateMachineState[];
+    transitions: AvlStateMachineTransition[];
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+declare const AvlStateMachine: React__default.FC<AvlStateMachineProps>;
+
+interface AvlOrbitalUnitTrait {
+    name: string;
+    color?: string;
+}
+interface AvlOrbitalUnitPage {
+    name: string;
+}
+interface AvlOrbitalUnitProps {
+    entityName: string;
+    fields?: number;
+    persistence?: AvlPersistenceKind;
+    traits: AvlOrbitalUnitTrait[];
+    pages: AvlOrbitalUnitPage[];
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+declare const AvlOrbitalUnit: React__default.FC<AvlOrbitalUnitProps>;
+
+interface AvlClosedCircuitState {
+    name: string;
+}
+interface AvlClosedCircuitTransition {
+    from: string;
+    to: string;
+    event?: string;
+    guard?: string;
+    effects?: AvlEffectType[];
+}
+interface AvlClosedCircuitProps {
+    states: AvlClosedCircuitState[];
+    transitions: AvlClosedCircuitTransition[];
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+declare const AvlClosedCircuit: React__default.FC<AvlClosedCircuitProps>;
+
+interface AvlEmitListenProps {
+    emitter: {
+        name: string;
+        fields?: number;
+    };
+    listener: {
+        name: string;
+        fields?: number;
+    };
+    eventName?: string;
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+declare const AvlEmitListen: React__default.FC<AvlEmitListenProps>;
+
+interface AvlSlotMapSlot {
+    name: string;
+    /** Manual position overrides. Omit for auto-layout. */
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+interface AvlSlotMapProps {
+    slots: AvlSlotMapSlot[];
+    pageWidth?: number;
+    pageHeight?: number;
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+declare const AvlSlotMap: React__default.FC<AvlSlotMapProps>;
+
+interface AvlExprTreeNode {
+    label: string;
+    type: 'operator' | 'literal' | 'binding';
+    children?: AvlExprTreeNode[];
+}
+interface AvlExprTreeProps {
+    expression: AvlExprTreeNode;
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+declare const AvlExprTree: React__default.FC<AvlExprTreeProps>;
+
+interface AvlTransitionLaneEffect {
+    type: AvlEffectType | string;
+}
+interface AvlTransitionLaneProps {
+    event: string;
+    guard?: string;
+    effects: AvlTransitionLaneEffect[];
+    width: number;
+    x?: number;
+    y?: number;
+    isBackward?: boolean;
+    isSelfLoop?: boolean;
+    color?: string;
+    onTransitionClick?: () => void;
+}
+declare const AvlTransitionLane: React__default.FC<AvlTransitionLaneProps>;
+
+interface AvlSwimLaneProps {
+    listenedEvents: string[];
+    emittedEvents: string[];
+    centerWidth: number;
+    height: number;
+    color?: string;
+    children: React__default.ReactNode;
+}
+declare const AvlSwimLane: React__default.FC<AvlSwimLaneProps>;
+
+/**
+ * AvlBehaviorGlyph - Visual identity for a behavior.
+ *
+ * Generates a unique glyph from behavior properties:
+ * - Core shape = persistence type
+ * - Spokes = field count
+ * - Rings = state count
+ * - Markers = effect types used
+ * - Color = domain hue
+ * - Composition = child glyphs + event wiring (molecule/organism)
+ */
+
+declare const DOMAIN_COLORS: Record<string, string>;
+type BehaviorLevel = 'atom' | 'molecule' | 'organism';
+type GlyphSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+interface BehaviorGlyphChild {
+    name: string;
+    fieldCount?: number;
+    stateCount?: number;
+    persistence?: AvlPersistenceKind;
+    effectTypes?: AvlEffectType[];
+}
+interface BehaviorGlyphConnection {
+    from: string;
+    to: string;
+    event: string;
+}
+interface AvlBehaviorGlyphProps {
+    /** Behavior name */
+    name: string;
+    /** Composition level */
+    level?: BehaviorLevel;
+    /** Domain for color coding */
+    domain?: string;
+    /** Override color (otherwise derived from domain) */
+    color?: string;
+    /** Entity field count (drives spoke count) */
+    fieldCount?: number;
+    /** State count (drives ring count) */
+    stateCount?: number;
+    /** Persistence type (drives core shape) */
+    persistence?: AvlPersistenceKind;
+    /** Effect types used (drives markers on rings) */
+    effectTypes?: AvlEffectType[];
+    /** Child behaviors for molecule/organism composition */
+    children?: BehaviorGlyphChild[];
+    /** Event connections between children (organism level) */
+    connections?: BehaviorGlyphConnection[];
+    /** Size preset */
+    size?: GlyphSize;
+    /** Show text labels */
+    showLabels?: boolean;
+    /** Animate orbital rings */
+    animated?: boolean;
+    /** Additional className */
+    className?: string;
+    /** Click handler */
+    onClick?: () => void;
+}
+declare const AvlBehaviorGlyph: React__default.FC<AvlBehaviorGlyphProps>;
+
+/**
+ * AVL layout utilities for positioning atoms in composed diagrams.
+ */
+/** Distribute N points evenly around a ring.
+ *  Handles edge cases: 1 state (centered), 2 states (horizontal). */
+declare function ringPositions(cx: number, cy: number, r: number, count: number, startAngle?: number): Array<{
+    x: number;
+    y: number;
+    angle: number;
+}>;
+/** Create an SVG arc path between two angles on a circle. */
+declare function arcPath(cx: number, cy: number, r: number, startAngle: number, endAngle: number): string;
+/** Distribute N points radially from a center. */
+declare function radialPositions(cx: number, cy: number, innerR: number, outerR: number, count: number, startAngle?: number): Array<{
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    angle: number;
+}>;
+/** Simple grid layout: position items in columns and rows. */
+declare function gridPositions(startX: number, startY: number, cols: number, cellWidth: number, cellHeight: number, count: number): Array<{
+    x: number;
+    y: number;
+    col: number;
+    row: number;
+}>;
+/** Compute a quadratic bezier control point offset perpendicular to the line. */
+declare function curveControlPoint(x1: number, y1: number, x2: number, y2: number, offset: number): {
+    cpx: number;
+    cpy: number;
+};
+
+/**
+ * AVL Schema Parser
+ *
+ * Pure functions that transform an OrbitalSchema into structured data
+ * for each zoom level of the Cosmic Zoom visualization.
+ *
+ * Imports all types from @almadar/core.
+ *
+ * @packageDocumentation
+ */
+
+interface SerializedEffect extends JsonObject {
+    type: string;
+    args: JsonValue[];
+}
+interface ApplicationOrbitalData {
+    name: string;
+    entityName: string;
+    fieldCount: number;
+    persistence: string;
+    traitNames: string[];
+    pageNames: string[];
+    position: {
+        x: number;
+        y: number;
+    };
+}
+interface CrossLink {
+    emitterOrbital: string;
+    listenerOrbital: string;
+    eventName: string;
+    emitterTrait: string;
+    listenerTrait: string;
+}
+interface ApplicationLevelData {
+    orbitals: ApplicationOrbitalData[];
+    crossLinks: CrossLink[];
+}
+interface FieldInfo extends JsonObject {
+    name: string;
+    type: string;
+    required: boolean;
+    hasDefault: boolean;
+}
+interface OrbitalTraitInfo extends JsonObject {
+    name: string;
+    stateCount: number;
+    eventCount: number;
+    transitionCount: number;
+    emits: string[];
+    listens: string[];
+}
+interface OrbitalPageInfo extends JsonObject {
+    name: string;
+    route: string;
+}
+interface ExternalLink extends JsonObject {
+    targetOrbital: string;
+    eventName: string;
+    direction: string;
+    traitName: string;
+}
+interface OrbitalLevelData {
+    name: string;
+    entity: {
+        name: string;
+        fields: FieldInfo[];
+        persistence: string;
+    };
+    traits: OrbitalTraitInfo[];
+    pages: OrbitalPageInfo[];
+    externalLinks: ExternalLink[];
+}
+interface TraitStateInfo extends JsonObject {
+    name: string;
+    isInitial: boolean | null;
+    isTerminal: boolean | null;
+}
+interface TraitTransitionInfo extends JsonObject {
+    from: string;
+    to: string;
+    event: string;
+    guard: JsonValue | null;
+    effects: SerializedEffect[];
+    index: number;
+}
+interface TraitLevelData extends JsonObject {
+    name: string;
+    linkedEntity: string;
+    states: TraitStateInfo[];
+    transitions: TraitTransitionInfo[];
+    emittedEvents: string[];
+    listenedEvents: string[];
+}
+interface ExprTreeNode {
+    label: string;
+    type: 'operator' | 'literal' | 'binding';
+    children?: ExprTreeNode[];
+}
+interface SlotTarget {
+    name: string;
+    pattern: string;
+}
+interface TransitionLevelData {
+    from: string;
+    to: string;
+    event: string;
+    guard: ExprTreeNode | null;
+    effects: ExprTreeNode[];
+    slotTargets: SlotTarget[];
+}
+/**
+ * Parse the application-level view: all orbitals with cross-orbital links.
+ */
+declare function parseApplicationLevel(schema: OrbitalSchema): ApplicationLevelData;
+/**
+ * Parse a single orbital's detail view.
+ */
+declare function parseOrbitalLevel(schema: OrbitalSchema, orbitalName: string): OrbitalLevelData | null;
+/**
+ * Parse a trait's state machine for the detail view.
+ */
+declare function parseTraitLevel(schema: OrbitalSchema, orbitalName: string, traitName: string): TraitLevelData | null;
+/**
+ * Parse a single transition for the detail view.
+ */
+declare function parseTransitionLevel(schema: OrbitalSchema, orbitalName: string, traitName: string, transitionIndex: number): TransitionLevelData | null;
+
+/**
+ * AVL Canvas Types
+ *
+ * Types for the unified AVL + Flow canvas. These define the data shapes
+ * for React Flow nodes and edges that render AVL primitives.
+ */
+
+/** The four zoom bands of the unified AVL canvas. */
+type ZoomBand = 'system' | 'module' | 'behavior' | 'detail';
+/** Thresholds for zoom band transitions (React Flow viewport zoom). */
+declare const ZOOM_BAND_THRESHOLDS: {
+    readonly system: readonly [0.1, 0.4];
+    readonly module: readonly [0.4, 1];
+    readonly behavior: readonly [1, 2.5];
+    readonly detail: readonly [2.5, 5];
+};
+/** Data carried by every orbital node in the unified canvas. */
+interface AvlNodeData extends JsonObject {
+    orbitalName: string;
+    entityName: string;
+    persistence: string;
+    fields: FieldInfo[];
+    traits: OrbitalTraitInfo[];
+    pages: OrbitalPageInfo[];
+    traitDetails: {
+        [k: string]: TraitLevelData;
+    };
+    externalLinks: ExternalLink[];
+}
+/** Data carried by edges in the unified canvas. */
+interface AvlEdgeData extends JsonObject {
+    edgeKind: string;
+    event: string | null;
+    fromTrait: string | null;
+    toTrait: string | null;
+}
+
+/** Determine which zoom band the current viewport zoom falls into. */
+declare function computeZoomBand(zoom: number): ZoomBand;
+/**
+ * Compute progress (0..1) within a zoom band.
+ * Useful for crossfade transitions between bands.
+ */
+declare function zoomProgress(zoom: number, band: ZoomBand): number;
+/** Context providing the current zoom band to all node components. */
+declare const ZoomBandContext: React.Context<ZoomBand>;
+/** Hook to read the current zoom band. */
+declare function useZoomBand(): ZoomBand;
+
+/**
+ * AVL Flow Converter
+ *
+ * Converts an OrbitalSchema into React Flow nodes and edges
+ * for the unified AVL canvas. Reuses the existing AVL schema parser.
+ */
+
+/**
+ * Transform an OrbitalSchema into React Flow nodes and edges.
+ * Pre-parses all orbital and trait details for responsive zoom.
+ */
+declare function schemaToFlowGraph(schema: OrbitalSchema): {
+    nodes: Node<AvlNodeData>[];
+    edges: Edge<AvlEdgeData>[];
+};
+
+/**
+ * AVL ELK Layout
+ *
+ * Shared ELK-based layout engine for state machines. Extracted from
+ * AvlTraitScene so both the V2 scene renderer and the V3 BehaviorView
+ * can share the same layout computation.
+ */
+
+interface LayoutNode {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    isInitial?: boolean;
+    isTerminal?: boolean;
+    role: StateRole;
+    transitionCount: number;
+}
+interface LayoutEdge {
+    id: string;
+    from: string;
+    to: string;
+    event: string;
+    effects: Array<{
+        type: string;
+    }>;
+    guard: boolean;
+    guardExpr?: string;
+    index: number;
+    labelX: number;
+    labelY: number;
+    labelW: number;
+    labelH: number;
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+    isSelf: boolean;
+    isBackward: boolean;
+}
+interface ElkLayout {
+    nodes: LayoutNode[];
+    edges: LayoutEdge[];
+    width: number;
+    height: number;
+}
+declare function computeTraitLayout(data: TraitLevelData): Promise<ElkLayout>;
+declare function edgePath(points: Array<{
+    x: number;
+    y: number;
+}>): string;
+
+/**
+ * SystemNode — Compact orbital node for the system zoom band (0.1x-0.4x).
+ *
+ * Renders miniature AVL primitives: entity glyph, field-type dots,
+ * state chain (role-colored dots), and page squares.
+ */
+
+interface SystemNodeProps {
+    data: AvlNodeData;
+}
+declare const SystemNode: React__default.FC<SystemNodeProps>;
+
+/**
+ * MiniStateMachine — Inline simplified state machine for the ModuleCard.
+ *
+ * Renders a compact left-to-right flow of AvlState nodes connected
+ * by AvlTransition arrows, with AvlEffect icons below.
+ * No ELK layout needed — uses simple horizontal positioning.
+ */
+
+interface MiniStateMachineProps {
+    data: TraitLevelData;
+    className?: string;
+}
+declare const MiniStateMachine: React__default.FC<MiniStateMachineProps>;
+
+/**
+ * ModuleCard — Structured card for the module zoom band (0.4x-1.0x).
+ *
+ * Renders AVL primitives inside a card container:
+ * - Entity section: AvlEntity glyph + AvlPersistence + AvlFieldType grid
+ * - Trait sections: MiniStateMachine per trait + AvlEffect icons + emit/listen indicators
+ * - Pages section: AvlPage squares with route labels
+ */
+
+/**
+ * ModuleCard — a card summarizing one course module or lesson with progress
+ * and entry point.
+ *
+ * @capabilities course module card, lesson card, curriculum unit card, learning-path step card
+ */
+interface ModuleCardProps {
+    data: AvlNodeData;
+}
+/**
+ * Self-contained ModuleCard. The connection `<Handle>`s need the ReactFlow store,
+ * so standalone they'd throw ("no zustand provider as an ancestor"). When this
+ * card isn't already a flow node (`useNodeId() === null`) it bundles its own
+ * `<ReactFlowProvider>` so it renders anywhere; inside `<FlowCanvas>` it's a real
+ * node and renders raw (no nested provider). The provider is an implementation
+ * detail, never a precondition for using the component.
+ */
+declare const ModuleCard: React__default.FC<ModuleCardProps>;
+
+/**
+ * BehaviorView — Full state machine for the behavior zoom band (1.0x-2.5x).
+ *
+ * Uses ELK layout from avl-elk-layout.ts. Renders AvlState, AvlTransitionLane,
+ * and AvlSwimLane inside an inline SVG within a React Flow node.
+ */
+
+interface BehaviorViewProps {
+    data: AvlNodeData;
+}
+declare const BehaviorView: React__default.FC<BehaviorViewProps>;
+
+/**
+ * DetailView — Transition specification card for the detail zoom band (2.5x-5.0x).
+ *
+ * Renders a spec card with: from/to AvlState nodes, AvlEvent trigger,
+ * AvlGuard diamond, numbered AvlEffect icons with binding paths,
+ * and AvlFieldType shapes.
+ */
+
+interface DetailViewProps {
+    data: AvlNodeData;
+}
+declare const DetailView: React__default.FC<DetailViewProps>;
+
+/**
+ * AvlOrbitalNode — Single React Flow node type for the unified AVL canvas.
+ *
+ * Reads the current ZoomBand from context and renders the appropriate
+ * sub-component: SystemNode, ModuleCard, BehaviorView, or DetailView.
+ *
+ * Using a single node type (instead of switching types per zoom band)
+ * prevents React from unmounting/remounting nodes on zoom changes.
+ */
+
+declare const AvlOrbitalNode: React__default.FC<NodeProps>;
+
+/**
+ * AvlTransitionEdge — React Flow edge for state machine transitions.
+ *
+ * Bezier path with event label at midpoint. Guard diamond and effect
+ * dot indicators shown inline. Forward transitions are solid dark,
+ * backward transitions are dashed lighter.
+ */
+
+interface AvlTransitionEdgeData {
+    [key: string]: string | boolean | undefined;
+    event: string;
+    hasGuard?: boolean;
+    hasEffects?: boolean;
+}
+type AvlTransitionFlowEdge = Edge<AvlTransitionEdgeData, 'transition'>;
+declare const AvlTransitionEdge: React__default.FC<EdgeProps<AvlTransitionFlowEdge>>;
+
+/**
+ * AvlEventWireEdge — React Flow edge for emit/listen event wiring.
+ *
+ * Dashed orange Bezier path with event name label at midpoint.
+ * Uses AVL CONNECTION_COLORS.emitListen styling.
+ */
+
+interface AvlEventWireEdgeData {
+    [key: string]: string | boolean | undefined;
+    event: string;
+    compatible?: boolean;
+}
+type AvlEventWireFlowEdge = Edge<AvlEventWireEdgeData, 'eventWire'>;
+declare const AvlEventWireEdge: React__default.FC<EdgeProps<AvlEventWireFlowEdge>>;
+
+/**
+ * AvlBackwardEdge — Dashed backward/retry transition edge.
+ *
+ * Uses CONNECTION_COLORS.backward styling: dashed, lighter color.
+ */
+
+declare const AvlBackwardEdge: React__default.FC<EdgeProps>;
+
+/**
+ * AvlPageEdge — Thin solid page-reference edge.
+ *
+ * Slate colored, 1px, used for page-to-trait references.
+ */
+
+declare const AvlPageEdge: React__default.FC<EdgeProps>;
+
+/**
+ * AvlBindingEdge — Dotted violet binding edge with @ marker.
+ *
+ * Used for data binding connections. Dotted line at 1px with
+ * a small @ label at the midpoint.
+ */
+
+declare const AvlBindingEdge: React__default.FC<EdgeProps>;
+
+/**
+ * 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.
+ */
+
+/**
+ * The navigation levels of the FlowCanvas.
+ *
+ * - `overview` (L1) — one card per orbital, showing the orbital's composed
+ *   render-ui at INIT.
+ * - `expanded` (L2) — one card per organism-authored transition + one
+ *   grouped card per imported-behavior alias.
+ * - `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.
+ */
+type ViewLevel = 'overview' | 'expanded' | 'behavior-expanded' | 'trait-expanded';
+/**
+ * Screen size preset for OrbPreview rendering inside nodes.
+ *
+ * Aligned with the four-breakpoint responsiveness audit:
+ *   mobile  — phone portrait  (≤640px)
+ *   tablet  — iPad / small landscape (641–1024px)
+ *   laptop  — 13–15" notebook (1025–1440px)
+ *   wide    — desktop / monitor (≥1441px)
+ *
+ * Preset widths are representative viewport widths within each range; the
+ * preview renders at exactly this width so the embedded UI experiences
+ * the same media-query / container-query behavior it would at the real
+ * viewport. `minHeight` only floors the preview frame; vertical sizing is
+ * content-driven (BrowserPlayground height="auto").
+ */
+type ScreenSize = 'mobile' | 'tablet' | 'laptop' | 'wide';
+/**
+ * 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.
+ */
+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;
+    /** 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. */
+interface RenderUIEntry {
+    slot: UISlot | string;
+    pattern: AnyPatternConfig;
+}
+/** Data for a preview node (used at both overview and expanded levels). */
+interface PreviewNodeData {
+    [key: string]: string | number | boolean | string[] | Expression | null | RenderUIEntry[] | PatternEventSource[] | Array<{
+        event: string;
+        fromState: string;
+        toState: string;
+    }> | OrbitalSchema | EntityData | undefined;
+    /** 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[];
+    /** 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). */
+    effectTypes?: string[];
+    /** Guard expression (for overlay). */
+    guard?: Expression | null;
+    entityName?: string;
+    persistence?: string;
+    fieldCount?: number;
+    traitCount?: number;
+    pageRoutes?: string[];
+    /**
+     * Generation status for this orbital. When `'running'`, the overview node
+     * renders a spinner overlay + accent border so the user can see which
+     * orbital the coordinator is currently dispatching to. Other states are
+     * available so consumers can also paint success/error treatments
+     * (e.g. green border on completion, red on failure). Default is `'idle'`.
+     *
+     * Set by FlowCanvasProps.orbitalStatus and threaded through the converter.
+     * Future expansion: hover over a `'running'` node to surface the subagent
+     * trace inline.
+     */
+    status?: 'idle' | 'running' | 'success' | 'error';
+    /**
+     * The `OrbitalSchema.name` this node was derived from. The reserved value
+     * `'__design_system__'` identifies nodes belonging to the Design System
+     * tab's synthesized catalog schema, so downstream event handlers can route
+     * mutation events to the project theme manifest instead of the project's
+     * orbital schema. Unset for project orbitals — handlers treat absence as
+     * "project schema".
+     */
+    sourceSchemaName?: string;
+    /**
+     * Set when this L2 card represents a grouped imported-behavior bucket
+     * (one card per `uses[]` alias instead of one per transition). The alias
+     * comes from `Trait.sourceBehavior.alias` populated by the inline phase.
+     * Double-clicking such a card drills into L3 (`behavior-expanded`) to
+     * see that alias's transitions.
+     *
+     * Absent on organism-authored transition cards and L1 overview cards.
+     */
+    behaviorAlias?: string;
+    /**
+     * Human-readable behavior name for a grouped imported-behavior card
+     * (e.g. `'std/behaviors/std-stat-card'`). Comes from
+     * `Trait.sourceBehavior.behavior`. Renderer surfaces it as a label.
+     */
+    behaviorName?: string;
+    /**
+     * How many transitions are collapsed into this grouped imported-behavior
+     * 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;
+    /** Full parsed schema threaded to node renderers (e.g. TraitCardNode). */
+    _fullSchema?: OrbitalSchema;
+    /** Mock entity data for the orbital preview. */
+    _mockData?: EntityData;
+}
+/** Data for event flow edges. */
+interface EventEdgeData {
+    [key: string]: string | boolean | undefined;
+    /** 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;
+}
+
+/**
+ * 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.
+ */
+
+/**
+ * Build a React Flow graph for the overview level.
+ * Each orbital gets one node showing its INIT transition's UI.
+ */
+declare function schemaToOverviewGraph(schema: OrbitalSchema, mockData?: EntityData, behaviorMeta?: Record<string, {
+    layer: string;
+}>, layoutHint?: 'pipeline' | 'grid', orbitalStatus?: Record<string, PreviewNodeData['status']>, screenSize?: ScreenSize): {
+    nodes: Node<PreviewNodeData>[];
+    edges: Edge<EventEdgeData>[];
+};
+/**
+ * Build a React Flow graph for the L2 (expanded) level.
+ *
+ * Organism-authored traits (no `sourceBehavior` metadata) emit one
+ * transition card per render-ui-bearing transition (the historical
+ * behavior). Imported traits (cloned by the inline phase from `uses[]`)
+ * collapse into one grouped card per `sourceBehavior.alias`, so the user
+ * sees `Stats`, `Graphs`, `Layout`, etc. as single cards rather than 9
+ * anonymous `INIT` peers (STUDIO-1). Drill into a grouped card to reach
+ * L3 (`orbitalAliasToExpandedGraph`).
+ */
+declare function orbitalToExpandedGraph(schema: OrbitalSchema, orbitalName: string, mockData?: EntityData, screenSize?: ScreenSize): {
+    nodes: Node<PreviewNodeData>[];
+    edges: Edge<EventEdgeData>[];
+};
+
+/**
+ * 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.
+ */
+
+declare const OrbPreviewNode: React__default.NamedExoticComponent<NodeProps>;
+
+/**
+ * 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.
+ */
+
+declare const EventFlowEdge: React__default.NamedExoticComponent<EdgeProps>;
+
+/**
+ * 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)
+ */
+
+/** Serializable payload field — mirrors EventPayloadField from @almadar/core. */
+interface SerializedPayloadField extends JsonObject {
+    name: string;
+    type: string;
+    required: boolean | null;
+    description: string | null;
+}
+/** Serializable behavior glyph child — mirrors BehaviorGlyphChild from AvlBehaviorGlyph. */
+interface SerializedGlyphChild extends JsonObject {
+    name: string;
+    fieldCount: number | null;
+    stateCount: number | null;
+    persistence: string | null;
+    effectTypes: string[];
+}
+/** Serializable behavior glyph connection — mirrors BehaviorGlyphConnection from AvlBehaviorGlyph. */
+interface SerializedGlyphConnection extends JsonObject {
+    from: string;
+    to: string;
+    event: string;
+}
+/** Extended view level adding 'behavior' to the existing overview/expanded. */
+type ComposeViewLevel = 'behavior' | 'overview' | 'expanded';
+/** An event that can be wired between behaviors. */
+interface ConnectableEvent extends JsonObject {
+    /** Event name (e.g., "ADD_TO_CART"). */
+    event: string;
+    /** Typed payload fields if declared. */
+    payloadFields: SerializedPayloadField[] | null;
+    /** Vertical position hint (0..1) for handle placement on the node. */
+    positionHint: number;
+}
+/** Data for a BehaviorComposeNode in React Flow. */
+interface BehaviorComposeNodeData extends JsonObject {
+    /** Behavior name from registry (e.g., "std-cart"). */
+    behaviorName: string;
+    /** Composition level: atom, molecule, organism. */
+    level: string;
+    /** Domain for color coding (e.g., "commerce"). */
+    domain: string | null;
+    /** Layer classification (e.g., "Domain", "UI Patterns"). */
+    layer: string | null;
+    /** Primary entity name (e.g., "CartItem"). */
+    entityName: string;
+    /** Number of states in the behavior. */
+    stateCount: number;
+    /** Number of entity fields. */
+    fieldCount: number | null;
+    /** Persistence kind. */
+    persistence: string | null;
+    /** Effect types used by this behavior. */
+    effectTypes: string[] | null;
+    /** Child behaviors for molecule/organism glyphs. */
+    children: SerializedGlyphChild[] | null;
+    /** Connections between children (for organism glyphs). */
+    connections: SerializedGlyphConnection[] | null;
+    /** Events this behavior can emit (source handles). */
+    connectableEvents: ConnectableEvent[];
+    /** Behaviors this is composable with (for palette hints). */
+    composableWith: string[] | null;
+    /** Names of orbitals produced by this behavior (for drill-down). */
+    orbitalNames: string[];
+}
+/** Edge data for behavior-level wiring. */
+interface BehaviorWireEdgeData extends JsonObject {
+    /** 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: SerializedPayloadField[] | null;
+}
+/** Mapping from behavior name to its metadata + produced orbitals. */
+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?: string;
+    /** Effect types used. */
+    effectTypes?: string[];
+    /** Child behaviors (molecule/organism). */
+    children?: SerializedGlyphChild[];
+    /** Connections between children (organism). */
+    connections?: SerializedGlyphConnection[];
+    /** Events available for wiring. */
+    connectableEvents: ConnectableEvent[];
+    /** Compatible behavior names. */
+    composableWith?: string[];
+    /** Orbital names produced by this behavior (for drill-down mapping). */
+    orbitalNames: string[];
+}
+
+/**
+ * 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).
+ */
+
+declare const BehaviorComposeNode: React__default.NamedExoticComponent<NodeProps>;
+
+/**
+ * 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).
+ */
+
+/**
+ * Build a React Flow graph for behavior-level composition.
+ * Each behavior entry becomes one BehaviorComposeNode.
+ */
+declare function behaviorsToComposeGraph(entries: BehaviorCanvasEntry[], wires: BehaviorWireEdgeData[], layoutHint?: 'pipeline' | 'grid'): {
+    nodes: Node<BehaviorComposeNodeData>[];
+    edges: Edge<BehaviorWireEdgeData>[];
+};
+/** Registry record shape (matches behaviors-registry.json entries). */
+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: {
+        [k: string]: Array<{
+            name: string;
+            type: string;
+            required?: boolean;
+        }>;
+    };
+    composableWith: string[];
+}
+/**
+ * Convert a registry entry to a BehaviorCanvasEntry.
+ * Maps connectableEvents + eventPayloads into typed ConnectableEvent[].
+ */
+declare function registryEntryToCanvasEntry(entry: BehaviorRegistryRecord, orbitalNames: string[]): BehaviorCanvasEntry;
+
+/**
+ * Build an `EditFocus` from a clicked element's `data-orb-*` address (stamped by
+ * UISlotRenderer). The owning orbital is read from the DOM (`data-orb-orbital`,
+ * walking up via `closest` when the clicked node itself doesn't carry it); since
+ * `EditFocus.orbital` is required, returns `null` when it can't be resolved.
+ */
+declare function deriveEditFocusFromElement(el: HTMLElement): EditFocus | null;
+
+/**
+ * useCanvasDnd — drag/drop primitives for the AVL canvas surface.
+ *
+ * Shares the sensor stack + collision waterfall with `useDataDnd` (both
+ * import from `hooks/useAlmadarDndCollision`); diverges on drop semantics
+ * because palette → canvas is a cursor-resolved tree insert, not a
+ * sortable-list reorder.
+ *
+ * Pointer-sensor based so it works inside React Flow nodes (the native
+ * HTML5 DnD path was swallowed by React Flow's pan/zoom handlers).
+ *
+ * Event contract (defaults — overridable via `CanvasDndProvider.onDrop`):
+ *   - On drag start: emits `UI:DRAG_START` { kind, data }
+ *   - On drag end:   emits `UI:DRAG_END`   { kind, data }
+ *   - On 'pattern' drop:   emits `UI:PATTERN_DROP`  { patternType, containerNode, parentPath?, index? }
+ *   - On 'behavior' drop:  emits `UI:BEHAVIOR_DROP` { behaviorName, containerNode }
+ *
+ * The `onDrop` callback lets consumers route OTHER payload kinds (e.g.
+ * `'pattern-instance'` for in-canvas reorder of an existing pattern) to
+ * their own bus events or schema mutations. Reorder semantics belong in
+ * the consumer because they touch the SExpr tree directly — this primitive
+ * only resolves payload + target + cursor and hands them off.
+ */
+
+/**
+ * Drag kinds the canvas understands. Open-ended `string` so consumers can
+ * introduce new kinds (e.g. `'pattern-instance'` for in-canvas reorder of an
+ * existing pattern) without touching this file — the provider's defaults
+ * cover `'pattern'` and `'behavior'`; everything else routes through the
+ * consumer's `onDrop`.
+ */
+type CanvasDragKind = 'pattern' | 'behavior' | (string & {});
+/**
+ * Payload carried by a draggable. For `'pattern'` tiles `data` is
+ * `{ type: string }`, for `'behavior'` tiles `{ name: string }`. For consumer
+ * kinds (e.g. `'pattern-instance'`) the shape is whatever the consumer
+ * agrees on with its own `onDrop`.
+ */
+interface CanvasDragPayload {
+    kind: CanvasDragKind;
+    data: EventPayload;
+}
+/**
+ * Orbital/trait/transition context a drop will mutate.
+ *
+ * Has an explicit `[key: string]: string | undefined` index signature so it
+ * structurally matches `EventPayload` — required because we pass the whole
+ * object as a field on the `UI:PATTERN_DROP` payload.
+ */
+interface CanvasContainerNode {
+    orbitalName?: string;
+    traitName?: string;
+    transitionEvent?: string;
+    [key: string]: string | undefined;
+}
+/** Drop-target metadata stored on each droppable's `data` field. */
+interface CanvasDropTarget {
+    /**
+     * `l1` = outer orbital frame (overview level).
+     * `l2` = render-ui slot inside an expanded orbital.
+     * `wrapper` = page-level catch-all fired when nothing inner caught the drop.
+     */
+    level: 'l1' | 'l2' | 'wrapper' | (string & {});
+    /** Full or partial container context this drop will mutate. */
+    containerNode: CanvasContainerNode;
+    /**
+     * Optional resolver called at drop time to derive `parentPath` + `index`
+     * from the pointer's final client position. L2 slots use this to walk the
+     * DOM under their `contentRef` and find the nearest `data-accepts-children`
+     * container plus the cursor-relative insertion index.
+     */
+    resolvePath?: (cursor: {
+        x: number;
+        y: number;
+    }) => {
+        parentPath: string;
+        index: number;
+    } | null;
+}
+interface CanvasDropEvent {
+    payload: CanvasDragPayload;
+    target: CanvasDropTarget;
+    /** Final pointer client position, when dnd-kit could compute it. */
+    cursor: {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Resolved insertion path/index from `target.resolvePath(cursor)`. Null
+     * when the target has no resolver or the cursor was unavailable.
+     */
+    resolved: {
+        parentPath: string;
+        index: number;
+    } | null;
+}
+interface UseCanvasDraggableArgs {
+    /** Unique id (per-tile). dnd-kit uses this to track the active drag. */
+    id: string;
+    payload: CanvasDragPayload;
+    disabled?: boolean;
+}
+interface UseCanvasDraggableResult {
+    setNodeRef: (node: HTMLElement | null) => void;
+    attributes: ReturnType<typeof useDraggable>['attributes'];
+    listeners: ReturnType<typeof useDraggable>['listeners'];
+    isDragging: boolean;
+    /** Spread on the tile — live transform + grab cursor + touch-action. */
+    style: React__default.CSSProperties;
+}
+declare function useCanvasDraggable({ id, payload, disabled, }: UseCanvasDraggableArgs): UseCanvasDraggableResult;
+interface UseCanvasDroppableArgs {
+    id: string;
+    target: CanvasDropTarget;
+    /** Which drag kinds this zone accepts. Defaults to ['pattern','behavior']. */
+    accepts?: readonly CanvasDragKind[];
+    disabled?: boolean;
+}
+interface UseCanvasDroppableResult {
+    setNodeRef: (node: HTMLElement | null) => void;
+    isOver: boolean;
+}
+declare function useCanvasDroppable({ id, target, accepts, disabled, }: UseCanvasDroppableArgs): UseCanvasDroppableResult;
+interface CanvasDndProviderProps {
+    children: React__default.ReactNode;
+    /**
+     * Override the default drop behavior. The default emits `UI:PATTERN_DROP`
+     * / `UI:BEHAVIOR_DROP` based on payload kind. Pass an `onDrop` to route
+     * additional kinds (e.g. `'pattern-instance'` reorder) elsewhere, or to
+     * mutate schema directly without going through the bus.
+     *
+     * Return `true` from `onDrop` to suppress the default emit; return
+     * `false`/`undefined` to fall through to defaults after running your code.
+     */
+    onDrop?: (drop: CanvasDropEvent) => boolean | void;
+    /**
+     * Renders the floating preview that follows the cursor during a drag.
+     * @dnd-kit moves the source DOM node via CSS transform, which gets clipped
+     * by any ancestor with `overflow: hidden|auto|scroll` (e.g. a scrollable
+     * palette column). Returning a node here mounts a portal-attached overlay
+     * outside the clip so the user always sees what they're dragging.
+     *
+     * Receives the active payload (or null between drags) and returns the
+     * preview element — typically the same JSX the tile renders inline.
+     */
+    renderOverlay?: (payload: CanvasDragPayload | null) => React__default.ReactNode;
+}
+/**
+ * Wraps a canvas subtree in one DndContext + sensors + collision waterfall.
+ * Every `useCanvasDraggable` / `useCanvasDroppable` inside this provider
+ * participates in the same drag session.
+ */
+declare function CanvasDndProvider({ children, onDrop, renderOverlay, }: CanvasDndProviderProps): React__default.ReactElement;
+
+/**
+ * OrbInspector
+ *
+ * Universal contextual inspector for .orb programs. Built into FlowCanvas.
+ * Two tabs: Inspector (contextual sections) and Code (.orb syntax view).
+ *
+ * Inspector shows different sections based on what was clicked:
+ *   - Orbital header → entity fields, traits, pages
+ *   - Pattern element → pattern props, entity (if entity-aware), transition (if fires event)
+ *   - Transition node → state diagram, guard, effects, render-ui source
+ *
+ * Code tab shows the .orb representation of the selected context.
+ *
+ * When `editable` is true, inspector fields become inputs.
+ */
+
+interface OrbInspectorProps {
+    node: PreviewNodeData;
+    schema: OrbitalSchema;
+    editable?: boolean;
+    /**
+     * Studio persona viewing the inspector. Controls tab visibility (Code is
+     * architect-only, Styles is universal) and section visibility (Entity,
+     * raw guard, raw effects are architect-only). Default `'builder'` matches
+     * pre-Phase-2 behavior except for the new Styles tab, which every persona
+     * gets.
+     */
+    userType?: 'builder' | 'designer' | 'architect';
+    /**
+     * Project theme tokens (Design System tab only). When provided AND the
+     * selection originates from the synthesized `__design_system__` schema,
+     * the Styles tab renders an editable token-row list; edits emit
+     * `UI:PROP_CHANGE` with `propName: '__token__.<group>.<key>'` and the
+     * page-level dispatcher routes them to `themeManifest.setToken`.
+     */
+    themeManifest?: ThemeDefinition;
+    onSchemaChange?: (schema: OrbitalSchema) => void;
+    onClose: () => void;
+}
+declare function OrbInspector({ node, schema, editable, userType, themeManifest, onSchemaChange, onClose }: OrbInspectorProps): React__default.ReactElement;
+declare namespace OrbInspector {
+    var displayName: string;
+}
+
+/**
+ * FlowCanvas — V3 UI Projection Canvas
+ *
+ * The canvas IS the app. Nodes show rendered UI thumbnails from
+ * render-ui effects. Edges show events connecting screens.
+ *
+ * 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).
+ */
+
+interface FlowCanvasProps {
+    schema: OrbitalSchema | string;
+    mockData?: EntityData;
+    className?: string;
+    width?: number | string;
+    height?: number | string;
+    onNodeClick?: (context: {
+        level: ViewLevel | 'code' | 'transition';
+        orbital: string;
+        trait?: string;
+        transition?: string;
+    }) => void;
+    onLevelChange?: (level: ViewLevel, orbital?: string) => void;
+    /**
+     * GAP-52: fired when the user double-clicks an orbital. Consumers (e.g. the
+     * builder workspace) use this as the trigger to enter cosmic mode
+     * (`AvlOrbitalsCosmicZoom`) for the focused orbital.
+     *
+     * The level at which this fires is controlled by `cosmicEntryLevel` (default
+     * `'expanded'`). At `'expanded'` the existing overview→expanded drill is
+     * preserved — the callback fires only on the second double-click. At
+     * `'overview'` the callback fires on the FIRST double-click and the existing
+     * drill is suppressed for that interaction. `'both'` fires at either level.
+     *
+     * The callback runs unconditionally — persona / permission gating is the
+     * consumer's responsibility.
+     */
+    onOrbitalDoubleClick?: (orbital: string) => void;
+    /**
+     * GAP-53: which level the `onOrbitalDoubleClick` callback fires at.
+     * - `'expanded'` (default, non-breaking) — fires only at L2 expanded; the
+     *   first overview double-click still drills overview→expanded.
+     * - `'overview'` — fires at L1 overview on the FIRST double-click. The
+     *   overview→expanded drill is suppressed when the callback is provided.
+     * - `'both'` — fires at either level.
+     */
+    cosmicEntryLevel?: 'expanded' | 'overview' | 'both';
+    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. */
+    onSchemaChange?: (schema: OrbitalSchema) => void;
+    /** Called when the user presses Delete/Backspace with a pattern selected. */
+    onPatternDelete?: (context: {
+        patternId: string;
+        nodeData: PreviewNodeData;
+    }) => void;
+    /** Called when the user drags from a source handle to a target handle (event wiring). */
+    onEventWire?: (wire: {
+        eventName: string;
+        sourceOrbital: string;
+        targetOrbital: string;
+        sourceTraitName?: string;
+        targetTraitName?: string;
+    }) => void;
+    /** Behavior layer metadata for node styling (layer color bands). */
+    behaviorMeta?: Record<string, {
+        layer: string;
+    }>;
+    /**
+     * Per-orbital generation status. Keyed by orbital name. Drives the spinner
+     * + accent border treatment on the overview node and (future) the hover
+     * trace surface. Defaults to `'idle'` for missing entries. Consumers
+     * derive this from agent subagent_start/complete SSE events.
+     */
+    orbitalStatus?: Record<string, PreviewNodeData['status']>;
+    /**
+     * Hover handler for overview-level orbital nodes. Fires with the orbital
+     * name on enter and `null` on leave. Reserved for the upcoming trace
+     * tooltip: consumers will use it to anchor a popover that shows the
+     * subagent's live trace + reasoning for the hovered orbital.
+     */
+    onOrbitalHover?: (orbitalName: string | null) => void;
+    /** 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. */
+    focusTarget?: {
+        type: string;
+        name: string;
+    };
+    /** @deprecated Not used in V3. */
+    color?: string;
+    /** @deprecated Not used in V3. */
+    animated?: boolean;
+    /** @deprecated Not used in V3. */
+    initialTrait?: string;
+    /** @deprecated Not used in V3. */
+    stateCoverage?: Record<string, string>;
+    /**
+     * Studio persona viewing the canvas. Drives `OrbInspector` tab/section
+     * visibility — designers and builders hide the raw `code` tab and the
+     * architect-only Entity / raw-guard / raw-effects sections; architects see
+     * everything. Default `'builder'` preserves pre-Phase-2 behavior.
+     */
+    userType?: 'builder' | 'designer' | 'architect';
+    /**
+     * Project theme tokens (Design System tab only). Forwarded to `OrbInspector`
+     * so the Styles tab can render an editable token list when the selection
+     * originates from the synthesized `__design_system__` schema.
+     */
+    themeManifest?: ThemeDefinition;
+}
+declare const FlowCanvas: React__default.FC<FlowCanvasProps>;
+
+/**
+ * ZoomBreadcrumb — HTML overlay showing current zoom band context.
+ *
+ * Positioned absolute top-left of the FlowCanvas.
+ * Shows AVL primitive icons inline with breadcrumb segments.
+ */
+
+interface ZoomBreadcrumbProps {
+    band: ZoomBand;
+    applicationName?: string;
+    orbitalName?: string;
+    traitName?: string;
+    eventName?: string;
+}
+declare const ZoomBreadcrumb: React__default.FC<ZoomBreadcrumbProps>;
+
+/**
+ * ZoomLegend — Collapsible HTML overlay showing AVL primitives
+ * relevant to the current zoom band.
+ */
+
+interface ZoomLegendProps {
+    band: ZoomBand;
+}
+declare const ZoomLegend: React__default.FC<ZoomLegendProps>;
+
+/**
+ * AVL Cosmic Zoom State Machine
+ *
+ * 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
+ */
+type ZoomLevel = 'application' | 'orbital' | 'trait' | 'transition';
+
+/**
+ * AvlCosmicZoom — Interactive Orbital Visualization
+ *
+ * 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.
+ */
+
+interface AvlCosmicZoomProps {
+    /** The orbital schema (parsed object or JSON string) */
+    schema: OrbitalSchema | string;
+    /** CSS class for the outer container */
+    className?: string;
+    /** Primary color for the visualization */
+    color?: string;
+    /** Enable animations (default: true) */
+    animated?: boolean;
+    /** Pre-select an orbital on mount */
+    initialOrbital?: string;
+    /** Pre-select a trait on mount */
+    initialTrait?: string;
+    /** Callback when zoom level changes */
+    onZoomChange?: (level: ZoomLevel, context: {
+        orbital?: string;
+        trait?: string;
+    }) => void;
+    /** Container width */
+    width?: number | string;
+    /** Container height */
+    height?: number | string;
+    /** Coverage data for verification overlay */
+    stateCoverage?: Record<string, 'covered' | 'uncovered' | 'partial'>;
+    /** Dynamic focus target. Changes animate the zoom to the specified orbital/trait. */
+    focusTarget?: {
+        type: 'orbital' | 'trait';
+        name: string;
+    };
+}
+declare const AvlCosmicZoom: React__default.FC<AvlCosmicZoomProps>;
+
+/**
+ * AvlOrbitalsCosmicZoom — Orbital Interaction Visualization
+ *
+ * Composed organism: renders AvlOrbitalUnit molecules positioned on a canvas,
+ * connected by cross-orbital event wire arrows. No React Flow dependency.
+ * Designed for documentation use.
+ *
+ * Composition:
+ *   - AvlOrbitalUnit (molecule) for each orbital
+ *   - SVG overlay for event wires between orbitals
+ *   - Click to select an orbital and show info panel
+ *
+ * @packageDocumentation
+ */
+
+interface AvlOrbitalsCosmicZoomProps {
+    /** The orbital schema (parsed object or JSON string) */
+    schema: OrbitalSchema | string;
+    /** CSS class for the outer container */
+    className?: string;
+    /** Primary color for the visualization */
+    color?: string;
+    /** Enable animations (default: true) */
+    animated?: boolean;
+    /** Container width */
+    width?: number | string;
+    /** Container height */
+    height?: number | string;
+    /**
+     * GAP-52: name of the orbital to highlight with a persistent ring/glow.
+     * Independent from user-driven selection (click). Used by the builder workspace
+     * when entering cosmic mode from a focused orbital — the focused orbital is
+     * highlighted while the user can still click any other orbital to select it.
+     */
+    highlightedOrbital?: string;
+    /**
+     * GAP-55: fired when the user clicks an orbital tile. Consumers (e.g. the
+     * builder workspace) use this as the trigger to drill INTO the clicked
+     * orbital — typically by switching back to the canvas tab and opening the
+     * clicked orbital at L2 expanded. Local `selected` toggle (visual highlight +
+     * info panel) still fires regardless of whether the callback is provided.
+     */
+    onOrbitalSelect?: (orbital: string) => void;
+    /**
+     * GAP-54: minimum zoom factor when scroll-wheel zooming. Default 0.4.
+     */
+    minZoom?: number;
+    /**
+     * GAP-54: maximum zoom factor when scroll-wheel zooming. Default 3.
+     */
+    maxZoom?: number;
+}
+declare const AvlOrbitalsCosmicZoom: React__default.FC<AvlOrbitalsCosmicZoomProps>;
+
+/**
+ * AvlTraitScene V2 - Zoom Level 3
+ *
+ * Left-to-right horizontal flow with color-coded states,
+ * transition lanes, and swim lanes for emit/listen events.
+ */
+
+interface AvlTraitSceneProps {
+    data: TraitLevelData;
+    color?: string;
+    onTransitionClick?: (transitionIndex: number, position: {
+        x: number;
+        y: number;
+    }) => void;
+}
+declare const AvlTraitScene: React__default.FC<AvlTraitSceneProps>;
+
+/**
+ * AvlTransitionScene V2 - Zoom Level 4
+ *
+ * Card layout replacing vertical waterfall.
+ * Reads like a spec card: from → to, trigger, guard, effects.
+ */
+
+interface AvlTransitionSceneProps {
+    data: TransitionLevelData;
+    color?: string;
+}
+declare const AvlTransitionScene: React__default.FC<AvlTransitionSceneProps>;
+
+/**
+ * AvlClickTarget
+ *
+ * Transparent SVG rect overlay that makes AVL atoms clickable.
+ * AVL atoms render <g> elements which don't natively support
+ * bounding-box click events. This wrapper adds an invisible
+ * rect with pointer events and optional hover glow.
+ *
+ * @packageDocumentation
+ */
+
+interface AvlClickTargetProps {
+    /** Bounding box position */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Click handler */
+    onClick: () => void;
+    /** Hover callback */
+    onHover?: (hovering: boolean) => void;
+    /** Cursor style (default: pointer) */
+    cursor?: string;
+    /** Glow color on hover */
+    glowColor?: string;
+    /** Accessible label */
+    label?: string;
+    /** Children (the AVL atoms to render on top) */
+    children: React__default.ReactNode;
+}
+declare const AvlClickTarget: React__default.FC<AvlClickTargetProps>;
+
+export { AVL_FIELD_TYPE_SHAPES, AVL_OPERATOR_COLORS, type ApplicationLevelData, AvlApplication, type AvlApplicationProps, AvlBackwardEdge, type AvlBaseProps, AvlBehaviorGlyph, type AvlBehaviorGlyphProps, AvlBinding, AvlBindingEdge, type AvlBindingProps, AvlBindingRef, type AvlBindingRefProps, AvlClickTarget, type AvlClickTargetProps, AvlClosedCircuit, type AvlClosedCircuitProps, type AvlClosedCircuitState, type AvlClosedCircuitTransition, AvlCosmicZoom, type AvlCosmicZoomProps, type AvlEdgeData, AvlEffect, type AvlEffectProps, type AvlEffectType, AvlEmitListen, type AvlEmitListenProps, AvlEntity, type AvlEntityProps, AvlEvent, type AvlEventProps, AvlEventWireEdge, type AvlEventWireEdgeData, AvlExprTree, type AvlExprTreeNode, type AvlExprTreeProps, AvlField, type AvlFieldProps, AvlFieldType, type AvlFieldTypeKind, type AvlFieldTypeProps, AvlGuard, type AvlGuardProps, AvlLiteral, type AvlLiteralProps, type AvlNodeData, AvlOperator, type AvlOperatorNamespace, type AvlOperatorProps, AvlOrbital, AvlOrbitalNode, type AvlOrbitalProps, AvlOrbitalUnit, type AvlOrbitalUnitPage, type AvlOrbitalUnitProps, type AvlOrbitalUnitTrait, AvlOrbitalsCosmicZoom, type AvlOrbitalsCosmicZoomProps, AvlPage, AvlPageEdge, type AvlPageProps, AvlPersistence, type AvlPersistenceKind, type AvlPersistenceProps, AvlSExpr, type AvlSExprProps, AvlSlotMap, type AvlSlotMapProps, type AvlSlotMapSlot, AvlState, AvlStateMachine, type AvlStateMachineProps, type AvlStateMachineState, type AvlStateMachineTransition, type AvlStateProps, AvlSwimLane, type AvlSwimLaneProps, AvlTrait, type AvlTraitProps, AvlTraitScene, type AvlTraitSceneProps, AvlTransition, AvlTransitionEdge, type AvlTransitionEdgeData, AvlTransitionLane, type AvlTransitionLaneProps, type AvlTransitionProps, AvlTransitionScene, type AvlTransitionSceneProps, type BehaviorCanvasEntry, BehaviorComposeNode, type BehaviorComposeNodeData, type BehaviorGlyphChild, type BehaviorGlyphConnection, type BehaviorLevel, type BehaviorRegistryRecord, BehaviorView, type BehaviorWireEdgeData, CONNECTION_COLORS, type CanvasContainerNode, CanvasDndProvider, type CanvasDndProviderProps, type CanvasDragKind, type CanvasDragPayload, type CanvasDropEvent, type CanvasDropTarget, type ComposeViewLevel, type ConnectableEvent, type CrossLink, DOMAIN_COLORS, DetailView, EFFECT_CATEGORY_COLORS, EFFECT_TYPE_TO_CATEGORY, type EffectCategory, type ElkLayout, type EventEdgeData, EventFlowEdge, FlowCanvas, type FlowCanvasProps, type GlyphSize, type LayoutEdge, type LayoutNode, MiniStateMachine, ModuleCard, OrbInspector, type OrbInspectorProps, OrbPreviewNode, type OrbitalLevelData, type PatternEventSource, type PreviewNodeData, type RenderUIEntry, STATE_COLORS, type StateRole, SystemNode, type TraitLevelData, type TransitionLevelData, type UseCanvasDraggableArgs, type UseCanvasDraggableResult, type UseCanvasDroppableArgs, type UseCanvasDroppableResult, type ViewLevel, ZOOM_BAND_THRESHOLDS, type ZoomBand, ZoomBandContext, ZoomBreadcrumb, type ZoomBreadcrumbProps, ZoomLegend, type ZoomLegendProps, type ZoomLevel, arcPath, behaviorsToComposeGraph, computeTraitLayout, computeZoomBand, curveControlPoint, deriveEditFocusFromElement, edgePath, getStateRole, gridPositions, orbitalToExpandedGraph, parseApplicationLevel, parseOrbitalLevel, parseTraitLevel, parseTransitionLevel, radialPositions, registryEntryToCanvasEntry, ringPositions, schemaToFlowGraph, schemaToOverviewGraph, useCanvasDraggable, useCanvasDroppable, useZoomBand, zoomProgress };