@almadar/runtime 2.7.0 → 3.0.1

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ClientEffectHandlers.ts","../src/PayloadValidator.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Client Effect Handlers Factory\n *\n * Creates the standard effect handler set for client-side trait execution.\n * Platform-agnostic — works with any UI framework that provides the required interfaces.\n *\n * @packageDocumentation\n */\n\nimport type { EffectHandlers, EventPayload, PatternProps } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Minimal event bus interface required by the factory.\n */\nexport interface ClientEventBus {\n    emit: (type: string, payload?: EventPayload) => void;\n}\n\n/**\n * Slot setter interface for render-ui effects.\n * The factory doesn't know about React state — it just calls this function.\n */\nexport interface SlotSetter {\n    /** Accumulate a pattern into the pending slot map */\n    addPattern: (slot: string, pattern: unknown, props?: PatternProps) => void;\n    /** Mark a slot for clearing */\n    clearSlot: (slot: string) => void;\n}\n\n/**\n * Options for creating client effect handlers.\n */\nexport interface CreateClientEffectHandlersOptions {\n    /** Event bus for emit effects */\n    eventBus: ClientEventBus;\n    /** Slot setter for render-ui effects */\n    slotSetter: SlotSetter;\n    /** Navigate function for navigate effects */\n    navigate?: (path: string, params?: { [key: string]: string }) => void;\n    /** Notify function for notification effects */\n    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\n/**\n * Create client-side effect handlers for trait state machine execution.\n *\n * Client handles: emit, renderUI, navigate, notify\n * Server handles: persist, set, callService (logged as warnings on client)\n *\n * @example\n * ```ts\n * const handlers = createClientEffectHandlers({\n *   eventBus,\n *   slotSetter: {\n *     addPattern: (slot, pattern, props) => pendingSlots.get(slot)?.push({ pattern, props }),\n *     clearSlot: (slot) => pendingSlots.set(slot, []),\n *   },\n *   navigate: (path) => router.push(path),\n *   notify: (msg, type) => toast[type](msg),\n * });\n * ```\n */\nexport function createClientEffectHandlers(\n    options: CreateClientEffectHandlersOptions\n): EffectHandlers {\n    const { eventBus, slotSetter, navigate, notify } = options;\n\n    return {\n        emit: (event: string, payload?: EventPayload) => {\n            const prefixedEvent = event.startsWith('UI:') ? event : `UI:${event}`;\n            eventBus.emit(prefixedEvent, { payload });\n        },\n\n        persist: async () => {\n            console.warn('[ClientEffectHandlers] persist is server-side only, ignored on client');\n        },\n\n        set: () => {\n            console.warn('[ClientEffectHandlers] set is server-side only, ignored on client');\n        },\n\n        callService: async () => {\n            console.warn('[ClientEffectHandlers] callService is server-side only, ignored on client');\n            return {};\n        },\n\n        renderUI: (slot: string, pattern: unknown, props?: PatternProps) => {\n            if (pattern === null) {\n                slotSetter.clearSlot(slot);\n                return;\n            }\n            slotSetter.addPattern(slot, pattern, props);\n        },\n\n        navigate: navigate ?? ((path: string) => {\n            console.warn('[ClientEffectHandlers] No navigate handler, ignoring:', path);\n        }),\n\n        notify: notify ?? ((msg: string, type?: string) => {\n            console.log(`[ClientEffectHandlers] notify (${type}):`, msg);\n        }),\n    };\n}\n","/**\n * PayloadValidator - Cross-Trait Payload Shape Validation (RCG-10)\n *\n * Validates that listener `payloadMapping` references match the emitter's\n * payload field names. Catches mismatches like `@payload.task_id` when the\n * emitter defines `taskId`.\n *\n * @packageDocumentation\n */\n\nimport type { TraitDefinition, EventPayload } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Emit declaration from a trait.\n */\ninterface EmitDeclaration {\n    event: string;\n    payload?: Array<{ name: string; type?: string }>;\n}\n\n/**\n * Payload validation error.\n */\nexport interface PayloadMismatch {\n    /** Listening trait name */\n    listenerTrait: string;\n    /** Emitting trait name */\n    emitterTrait: string;\n    /** Event name */\n    event: string;\n    /** The payload field referenced in the listener's payloadMapping */\n    referencedField: string;\n    /** Available fields from the emitter's payload declaration */\n    availableFields: string[];\n}\n\n// ============================================================================\n// Validation\n// ============================================================================\n\n/**\n * Validate that all listener payloadMapping references match emitter payload fields.\n *\n * @param traits - All trait definitions in the schema\n * @param emits - Emit declarations per trait (traitName → EmitDeclaration[])\n * @returns Array of payload mismatches (empty if all valid)\n *\n * @example\n * ```ts\n * const mismatches = validatePayloadShapes(traits, emitsMap);\n * for (const m of mismatches) {\n *   console.warn(\n *     `Trait \"${m.listenerTrait}\" references @payload.${m.referencedField} ` +\n *     `for event \"${m.event}\" but emitter \"${m.emitterTrait}\" only declares: ` +\n *     `${m.availableFields.join(', ')}`\n *   );\n * }\n * ```\n */\nexport function validatePayloadShapes(\n    traits: TraitDefinition[],\n    emits: Map<string, EmitDeclaration[]>\n): PayloadMismatch[] {\n    const mismatches: PayloadMismatch[] = [];\n\n    // Build event→emitter lookup: event name → { traitName, payload fields }\n    const emitIndex = new Map<string, { traitName: string; fields: string[] }>();\n    for (const [traitName, declarations] of emits) {\n        for (const decl of declarations) {\n            const fields = decl.payload?.map((p) => p.name) ?? [];\n            emitIndex.set(decl.event, { traitName, fields });\n        }\n    }\n\n    // Check each listener's payloadMapping references\n    for (const trait of traits) {\n        if (!trait.listens) continue;\n\n        for (const listener of trait.listens) {\n            const emitter = emitIndex.get(listener.event);\n            if (!emitter) continue; // No emitter found — separate validation concern\n\n            if (!listener.payloadMapping) continue;\n\n            // Extract @payload.X references from payloadMapping values\n            const payloadRefs = extractPayloadReferences(listener.payloadMapping);\n\n            for (const ref of payloadRefs) {\n                if (!emitter.fields.includes(ref)) {\n                    mismatches.push({\n                        listenerTrait: trait.name,\n                        emitterTrait: emitter.traitName,\n                        event: listener.event,\n                        referencedField: ref,\n                        availableFields: emitter.fields,\n                    });\n                }\n            }\n        }\n    }\n\n    return mismatches;\n}\n\n/**\n * Extract payload field references from a payloadMapping object.\n * Finds all `@payload.fieldName` patterns and returns the field names.\n */\nfunction extractPayloadReferences(mapping: EventPayload): string[] {\n    const refs: string[] = [];\n\n    function collect(value: unknown): void {\n        if (typeof value === 'string') {\n            const match = value.match(/^@payload\\.(\\w+)$/);\n            if (match) {\n                refs.push(match[1]);\n            }\n        } else if (typeof value === 'object' && value !== null) {\n            if (Array.isArray(value)) {\n                value.forEach(collect);\n            } else {\n                Object.values(value as EventPayload).forEach(collect);\n            }\n        }\n    }\n\n    Object.values(mapping).forEach(collect);\n    return [...new Set(refs)];\n}\n\n/**\n * Build emit declarations map from trait definitions.\n * Extracts emits from transitions that use the `emit` effect.\n *\n * Note: This is a heuristic — it parses emit effects from transitions.\n * For full accuracy, the schema should include explicit `emits` declarations.\n */\nexport function buildEmitsFromTraits(\n    traits: TraitDefinition[],\n    explicitEmits?: Map<string, EmitDeclaration[]>\n): Map<string, EmitDeclaration[]> {\n    // Start with explicit emits if provided\n    const result = new Map<string, EmitDeclaration[]>(explicitEmits ?? []);\n\n    for (const trait of traits) {\n        if (result.has(trait.name)) continue; // Explicit declarations take precedence\n\n        const emitDecls: EmitDeclaration[] = [];\n        for (const transition of trait.transitions) {\n            if (!transition.effects) continue;\n\n            for (const effect of transition.effects) {\n                if (!Array.isArray(effect)) continue;\n                if (effect[0] === 'emit' && typeof effect[1] === 'string') {\n                    const event = effect[1] as string;\n                    // Payload is in effect[2] if present\n                    const payloadObj = effect[2] as EventPayload | undefined;\n                    const payload = payloadObj\n                        ? Object.keys(payloadObj).map((name) => ({ name }))\n                        : undefined;\n\n                    // Avoid duplicates\n                    if (!emitDecls.some((d) => d.event === event)) {\n                        emitDecls.push({ event, payload });\n                    }\n                }\n            }\n        }\n\n        if (emitDecls.length > 0) {\n            result.set(trait.name, emitDecls);\n        }\n    }\n\n    return result;\n}\n"]}
+{"version":3,"sources":["../src/ClientEffectHandlers.ts","../src/PayloadValidator.ts","../src/composition/index.ts","../src/composition/event-wiring.ts","../src/composition/layout-strategy.ts","../src/composition/compose-behaviors.ts","../src/composition/pipe.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Client Effect Handlers Factory\n *\n * Creates the standard effect handler set for client-side trait execution.\n * Platform-agnostic — works with any UI framework that provides the required interfaces.\n *\n * @packageDocumentation\n */\n\nimport type { EffectHandlers, EventPayload, PatternProps } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Minimal event bus interface required by the factory.\n */\nexport interface ClientEventBus {\n    emit: (type: string, payload?: EventPayload) => void;\n}\n\n/**\n * Slot setter interface for render-ui effects.\n * The factory doesn't know about React state — it just calls this function.\n */\nexport interface SlotSetter {\n    /** Accumulate a pattern into the pending slot map */\n    addPattern: (slot: string, pattern: unknown, props?: PatternProps) => void;\n    /** Mark a slot for clearing */\n    clearSlot: (slot: string) => void;\n}\n\n/**\n * Options for creating client effect handlers.\n */\nexport interface CreateClientEffectHandlersOptions {\n    /** Event bus for emit effects */\n    eventBus: ClientEventBus;\n    /** Slot setter for render-ui effects */\n    slotSetter: SlotSetter;\n    /** Navigate function for navigate effects */\n    navigate?: (path: string, params?: { [key: string]: string }) => void;\n    /** Notify function for notification effects */\n    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\n/**\n * Create client-side effect handlers for trait state machine execution.\n *\n * Client handles: emit, renderUI, navigate, notify\n * Server handles: persist, set, callService (logged as warnings on client)\n *\n * @example\n * ```ts\n * const handlers = createClientEffectHandlers({\n *   eventBus,\n *   slotSetter: {\n *     addPattern: (slot, pattern, props) => pendingSlots.get(slot)?.push({ pattern, props }),\n *     clearSlot: (slot) => pendingSlots.set(slot, []),\n *   },\n *   navigate: (path) => router.push(path),\n *   notify: (msg, type) => toast[type](msg),\n * });\n * ```\n */\nexport function createClientEffectHandlers(\n    options: CreateClientEffectHandlersOptions\n): EffectHandlers {\n    const { eventBus, slotSetter, navigate, notify } = options;\n\n    return {\n        emit: (event: string, payload?: EventPayload) => {\n            const prefixedEvent = event.startsWith('UI:') ? event : `UI:${event}`;\n            eventBus.emit(prefixedEvent, { payload });\n        },\n\n        persist: async () => {\n            console.warn('[ClientEffectHandlers] persist is server-side only, ignored on client');\n        },\n\n        set: () => {\n            console.warn('[ClientEffectHandlers] set is server-side only, ignored on client');\n        },\n\n        callService: async () => {\n            console.warn('[ClientEffectHandlers] callService is server-side only, ignored on client');\n            return {};\n        },\n\n        renderUI: (slot: string, pattern: unknown, props?: PatternProps) => {\n            if (pattern === null) {\n                slotSetter.clearSlot(slot);\n                return;\n            }\n            slotSetter.addPattern(slot, pattern, props);\n        },\n\n        navigate: navigate ?? ((path: string) => {\n            console.warn('[ClientEffectHandlers] No navigate handler, ignoring:', path);\n        }),\n\n        notify: notify ?? ((msg: string, type?: string) => {\n            console.log(`[ClientEffectHandlers] notify (${type}):`, msg);\n        }),\n    };\n}\n","/**\n * PayloadValidator - Cross-Trait Payload Shape Validation (RCG-10)\n *\n * Validates that listener `payloadMapping` references match the emitter's\n * payload field names. Catches mismatches like `@payload.task_id` when the\n * emitter defines `taskId`.\n *\n * @packageDocumentation\n */\n\nimport type { TraitDefinition, EventPayload } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Emit declaration from a trait.\n */\ninterface EmitDeclaration {\n    event: string;\n    payload?: Array<{ name: string; type?: string }>;\n}\n\n/**\n * Payload validation error.\n */\nexport interface PayloadMismatch {\n    /** Listening trait name */\n    listenerTrait: string;\n    /** Emitting trait name */\n    emitterTrait: string;\n    /** Event name */\n    event: string;\n    /** The payload field referenced in the listener's payloadMapping */\n    referencedField: string;\n    /** Available fields from the emitter's payload declaration */\n    availableFields: string[];\n}\n\n// ============================================================================\n// Validation\n// ============================================================================\n\n/**\n * Validate that all listener payloadMapping references match emitter payload fields.\n *\n * @param traits - All trait definitions in the schema\n * @param emits - Emit declarations per trait (traitName → EmitDeclaration[])\n * @returns Array of payload mismatches (empty if all valid)\n *\n * @example\n * ```ts\n * const mismatches = validatePayloadShapes(traits, emitsMap);\n * for (const m of mismatches) {\n *   console.warn(\n *     `Trait \"${m.listenerTrait}\" references @payload.${m.referencedField} ` +\n *     `for event \"${m.event}\" but emitter \"${m.emitterTrait}\" only declares: ` +\n *     `${m.availableFields.join(', ')}`\n *   );\n * }\n * ```\n */\nexport function validatePayloadShapes(\n    traits: TraitDefinition[],\n    emits: Map<string, EmitDeclaration[]>\n): PayloadMismatch[] {\n    const mismatches: PayloadMismatch[] = [];\n\n    // Build event→emitter lookup: event name → { traitName, payload fields }\n    const emitIndex = new Map<string, { traitName: string; fields: string[] }>();\n    for (const [traitName, declarations] of emits) {\n        for (const decl of declarations) {\n            const fields = decl.payload?.map((p) => p.name) ?? [];\n            emitIndex.set(decl.event, { traitName, fields });\n        }\n    }\n\n    // Check each listener's payloadMapping references\n    for (const trait of traits) {\n        if (!trait.listens) continue;\n\n        for (const listener of trait.listens) {\n            const emitter = emitIndex.get(listener.event);\n            if (!emitter) continue; // No emitter found — separate validation concern\n\n            if (!listener.payloadMapping) continue;\n\n            // Extract @payload.X references from payloadMapping values\n            const payloadRefs = extractPayloadReferences(listener.payloadMapping);\n\n            for (const ref of payloadRefs) {\n                if (!emitter.fields.includes(ref)) {\n                    mismatches.push({\n                        listenerTrait: trait.name,\n                        emitterTrait: emitter.traitName,\n                        event: listener.event,\n                        referencedField: ref,\n                        availableFields: emitter.fields,\n                    });\n                }\n            }\n        }\n    }\n\n    return mismatches;\n}\n\n/**\n * Extract payload field references from a payloadMapping object.\n * Finds all `@payload.fieldName` patterns and returns the field names.\n */\nfunction extractPayloadReferences(mapping: EventPayload): string[] {\n    const refs: string[] = [];\n\n    function collect(value: unknown): void {\n        if (typeof value === 'string') {\n            const match = value.match(/^@payload\\.(\\w+)$/);\n            if (match) {\n                refs.push(match[1]);\n            }\n        } else if (typeof value === 'object' && value !== null) {\n            if (Array.isArray(value)) {\n                value.forEach(collect);\n            } else {\n                Object.values(value as EventPayload).forEach(collect);\n            }\n        }\n    }\n\n    Object.values(mapping).forEach(collect);\n    return [...new Set(refs)];\n}\n\n/**\n * Build emit declarations map from trait definitions.\n * Extracts emits from transitions that use the `emit` effect.\n *\n * Note: This is a heuristic — it parses emit effects from transitions.\n * For full accuracy, the schema should include explicit `emits` declarations.\n */\nexport function buildEmitsFromTraits(\n    traits: TraitDefinition[],\n    explicitEmits?: Map<string, EmitDeclaration[]>\n): Map<string, EmitDeclaration[]> {\n    // Start with explicit emits if provided\n    const result = new Map<string, EmitDeclaration[]>(explicitEmits ?? []);\n\n    for (const trait of traits) {\n        if (result.has(trait.name)) continue; // Explicit declarations take precedence\n\n        const emitDecls: EmitDeclaration[] = [];\n        for (const transition of trait.transitions) {\n            if (!transition.effects) continue;\n\n            for (const effect of transition.effects) {\n                if (!Array.isArray(effect)) continue;\n                if (effect[0] === 'emit' && typeof effect[1] === 'string') {\n                    const event = effect[1] as string;\n                    // Payload is in effect[2] if present\n                    const payloadObj = effect[2] as EventPayload | undefined;\n                    const payload = payloadObj\n                        ? Object.keys(payloadObj).map((name) => ({ name }))\n                        : undefined;\n\n                    // Avoid duplicates\n                    if (!emitDecls.some((d) => d.event === event)) {\n                        emitDecls.push({ event, payload });\n                    }\n                }\n            }\n        }\n\n        if (emitDecls.length > 0) {\n            result.set(trait.name, emitDecls);\n        }\n    }\n\n    return result;\n}\n","/**\n * Composition Module\n *\n * Runtime-side TypeScript composition layer for behavior/* operators.\n *\n * Composition is normally a compile-time concept, evaluated by the Rust\n * compiler pass before code generation. The runtime ships an equivalent\n * TypeScript implementation so dev-mode hot reload, agent-driven dynamic\n * composition, and the legacy `composeBehaviors()` callers all have a\n * usable in-process implementation. The handlers are wired into\n * `EffectExecutor` as optional handlers (`composeBehaviors`,\n * `applyEventWiring`, `detectLayoutStrategy`, `pipeBehaviors`) so\n * consumers that do not need composition pay no cost.\n *\n * @packageDocumentation\n */\n\n// Compose behaviors (main entry point)\nexport {\n    type ComposeBehaviorsInput,\n    type ComposeBehaviorsResult,\n    composeBehaviors,\n} from './compose-behaviors.js';\n\n// Event wiring\nexport { type EventWiringEntry, applyEventWiring } from './event-wiring.js';\n\n// Layout strategy detection\nexport { type LayoutStrategy, detectLayoutStrategy } from './layout-strategy.js';\n\n// Pipe (left-to-right behavior pipeline)\nexport { type PipeStep, pipeBehaviors } from './pipe.js';\n","/**\n * Event Wiring\n *\n * Applies cross-orbital event wiring to orbital definitions.\n * Adds emits/listens declarations to traits so they can communicate\n * across orbital boundaries.\n *\n * @packageDocumentation\n */\n\nimport type {\n    OrbitalDefinition,\n    Trait,\n    TraitEventContract,\n    TraitEventListener,\n} from '@almadar/core';\nimport { isInlineTrait } from '@almadar/core';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * A single event wiring entry connecting two traits across orbitals.\n */\nexport interface EventWiringEntry {\n    /** Source trait name or orbital name */\n    from: string;\n    /** Event name (UPPER_SNAKE_CASE) */\n    event: string;\n    /** Target trait name or orbital name */\n    to: string;\n    /** Event to trigger on the listener side */\n    triggers: string;\n}\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\n/**\n * Find a trait by name across all orbitals.\n * Only inline traits can be mutated; string/ref traits are skipped.\n * Returns the inline Trait object if found, or null.\n */\nfunction findInlineTrait(\n    orbitals: OrbitalDefinition[],\n    name: string,\n): Trait | null {\n    for (const orbital of orbitals) {\n        for (const traitRef of orbital.traits) {\n            if (isInlineTrait(traitRef) && traitRef.name === name) {\n                return traitRef;\n            }\n        }\n    }\n    return null;\n}\n\n/**\n * Check if an emit already exists in the list.\n * @internal\n */\nfunction hasEmit(emits: TraitEventContract[], event: string): boolean {\n    return emits.some((e) => e.event === event);\n}\n\n/**\n * Check if a listen already exists in the list.\n * @internal\n */\nfunction hasListen(\n    listens: TraitEventListener[],\n    event: string,\n    triggers: string,\n): boolean {\n    return listens.some((l) => l.event === event && l.triggers === triggers);\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Apply event wiring to orbital definitions.\n *\n * For each wiring entry:\n * 1. Find the source trait and add an external emit (if not already present)\n * 2. Find the target trait and add an external listen (if not already present)\n *\n * Returns a new array of orbitals with wiring applied (deep-cloned).\n */\nexport function applyEventWiring(\n    orbitals: OrbitalDefinition[],\n    wiring: EventWiringEntry[],\n): OrbitalDefinition[] {\n    // Deep clone to avoid mutating input\n    const cloned: OrbitalDefinition[] = JSON.parse(\n        JSON.stringify(orbitals),\n    ) as OrbitalDefinition[];\n\n    for (const entry of wiring) {\n        // Wire the source: add emit\n        const sourceTrait = findInlineTrait(cloned, entry.from);\n        if (sourceTrait) {\n            if (!sourceTrait.emits) {\n                sourceTrait.emits = [];\n            }\n            if (!hasEmit(sourceTrait.emits, entry.event)) {\n                sourceTrait.emits.push({\n                    event: entry.event,\n                    scope: 'external',\n                });\n            }\n        }\n\n        // Wire the target: add listen\n        const targetTrait = findInlineTrait(cloned, entry.to);\n        if (targetTrait) {\n            if (!targetTrait.listens) {\n                targetTrait.listens = [];\n            }\n            if (!hasListen(targetTrait.listens, entry.event, entry.triggers)) {\n                targetTrait.listens.push({\n                    event: entry.event,\n                    triggers: entry.triggers,\n                    scope: 'external',\n                });\n            }\n        }\n    }\n\n    return cloned;\n}\n","/**\n * Layout Strategy Detection\n *\n * Auto-detects the best layout strategy for a composed application\n * based on the number of orbitals and their event wiring topology.\n *\n * @packageDocumentation\n */\n\nimport type { OrbitalDefinition } from '@almadar/core';\nimport type { EventWiringEntry } from './event-wiring.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Layout strategy for the composed application.\n *\n * - 'single': One orbital, one page\n * - 'tabs': 2-4 orbitals with no sequential chain\n * - 'sidebar': 5+ orbitals (navigation-heavy)\n * - 'dashboard': Single page with all orbitals visible\n * - 'wizard-flow': Sequential event chain detected (A -> B -> C)\n */\nexport type LayoutStrategy =\n    | 'sidebar'\n    | 'tabs'\n    | 'dashboard'\n    | 'wizard-flow'\n    | 'single';\n\n// ============================================================================\n// Chain Detection\n// ============================================================================\n\n/**\n * Detect whether the event wiring forms a sequential chain.\n *\n * A sequential chain exists when orbital A's `from` feeds into B's `to`,\n * and B's `from` feeds into C's `to`, forming A -> B -> C.\n *\n * We build a directed graph from wiring entries and look for a chain\n * that covers 3+ nodes (the minimum for a meaningful wizard flow).\n */\nfunction hasSequentialChain(wiring: EventWiringEntry[]): boolean {\n    if (wiring.length < 2) {\n        return false;\n    }\n\n    // Build adjacency: from -> Set<to>\n    const adjacency = new Map<string, Set<string>>();\n    const allTargets = new Set<string>();\n\n    for (const entry of wiring) {\n        let targets = adjacency.get(entry.from);\n        if (!targets) {\n            targets = new Set<string>();\n            adjacency.set(entry.from, targets);\n        }\n        targets.add(entry.to);\n        allTargets.add(entry.to);\n    }\n\n    // Find roots (nodes that are sources but never targets)\n    const roots: string[] = [];\n    for (const from of adjacency.keys()) {\n        if (!allTargets.has(from)) {\n            roots.push(from);\n        }\n    }\n\n    // If no clear root, try all sources\n    const starts = roots.length > 0 ? roots : [...adjacency.keys()];\n\n    // Walk from each start and measure chain length\n    for (const start of starts) {\n        let current = start;\n        let length = 1;\n        const visited = new Set<string>([current]);\n\n        while (true) {\n            const nexts = adjacency.get(current);\n            if (!nexts || nexts.size === 0) break;\n\n            // Follow the first unvisited successor (linear chain)\n            let advanced = false;\n            for (const next of nexts) {\n                if (!visited.has(next)) {\n                    visited.add(next);\n                    current = next;\n                    length++;\n                    advanced = true;\n                    break;\n                }\n            }\n\n            if (!advanced) break;\n        }\n\n        // A chain of 3+ nodes qualifies as wizard-flow\n        if (length >= 3) {\n            return true;\n        }\n    }\n\n    return false;\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Detect the best layout strategy based on orbital count and event wiring.\n *\n * Heuristic:\n * 1. Sequential event chain detected -> 'wizard-flow'\n * 2. 1 orbital -> 'single'\n * 3. 2-4 orbitals -> 'tabs'\n * 4. 5+ orbitals -> 'sidebar'\n */\nexport function detectLayoutStrategy(\n    orbitals: OrbitalDefinition[],\n    eventWiring?: EventWiringEntry[],\n): LayoutStrategy {\n    // Check for sequential chain first (takes priority)\n    if (eventWiring && eventWiring.length > 0 && hasSequentialChain(eventWiring)) {\n        return 'wizard-flow';\n    }\n\n    const count = orbitals.length;\n\n    if (count <= 1) {\n        return 'single';\n    }\n\n    if (count <= 4) {\n        return 'tabs';\n    }\n\n    return 'sidebar';\n}\n","/**\n * Compose Behaviors\n *\n * Main entry point for composing multiple orbital definitions into\n * a single OrbitalSchema application. Handles event wiring, layout\n * strategy detection, and page generation.\n *\n * @packageDocumentation\n */\n\nimport type { OrbitalDefinition, OrbitalSchema, Page } from '@almadar/core';\nimport type { EventWiringEntry } from './event-wiring.js';\nimport { applyEventWiring } from './event-wiring.js';\nimport type { LayoutStrategy } from './layout-strategy.js';\nimport { detectLayoutStrategy } from './layout-strategy.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Input for composing behaviors into an application.\n */\nexport interface ComposeBehaviorsInput {\n    /** Application name */\n    appName: string;\n    /** Orbital definitions to compose */\n    orbitals: OrbitalDefinition[];\n    /** Layout strategy override, or 'auto' to detect */\n    layoutStrategy?: LayoutStrategy | 'auto';\n    /** Cross-orbital event wiring */\n    eventWiring?: EventWiringEntry[];\n    /** Optional entity name mappings (original -> renamed) */\n    entityMappings?: Record<string, string>;\n}\n\n/**\n * Result of composing behaviors.\n */\nexport interface ComposeBehaviorsResult {\n    /** The composed OrbitalSchema */\n    schema: OrbitalSchema;\n    /** Layout metadata */\n    layout: { strategy: LayoutStrategy; pageCount: number };\n    /** Wiring metadata */\n    wiring: { connections: number };\n}\n\n// ============================================================================\n// Page Generation\n// ============================================================================\n\nfunction toKebabCase(name: string): string {\n    return name\n        .replace(/([a-z])([A-Z])/g, '$1-$2')\n        .replace(/[\\s_]+/g, '-')\n        .toLowerCase();\n}\n\n/**\n * Generate pages for each orbital based on the layout strategy.\n *\n * For strategies that produce one page per orbital (sidebar, tabs, wizard-flow),\n * each orbital gets a page at `/<kebab-name>` with `isInitial` on the first.\n *\n * For 'dashboard', all orbitals share a single page.\n * For 'single', the lone orbital gets a single root page.\n */\nfunction generatePages(\n    orbitals: OrbitalDefinition[],\n    strategy: LayoutStrategy,\n): Page[] {\n    switch (strategy) {\n        case 'single': {\n            const orbital = orbitals[0];\n            const name = orbital?.name ?? 'Main';\n            return [\n                {\n                    name: `${name}Page`,\n                    path: '/',\n                    isInitial: true,\n                    primaryEntity: getEntityName(orbital),\n                },\n            ];\n        }\n\n        case 'dashboard': {\n            return [\n                {\n                    name: 'DashboardPage',\n                    path: '/',\n                    viewType: 'dashboard',\n                    isInitial: true,\n                },\n            ];\n        }\n\n        case 'sidebar':\n        case 'tabs':\n        case 'wizard-flow': {\n            return orbitals.map((orbital, index) => ({\n                name: `${orbital.name}Page`,\n                path: index === 0 ? '/' : `/${toKebabCase(orbital.name)}`,\n                isInitial: index === 0,\n                primaryEntity: getEntityName(orbital),\n            }));\n        }\n    }\n}\n\n/**\n * Extract entity name from an orbital definition.\n * Handles both inline entities and string references.\n */\nfunction getEntityName(orbital: OrbitalDefinition | undefined): string | undefined {\n    if (!orbital) return undefined;\n    const entity = orbital.entity;\n    if (typeof entity === 'string') {\n        // Reference like \"Alias.entity\" - extract the alias as entity name\n        return entity.replace('.entity', '');\n    }\n    return entity.name;\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Compose multiple orbital definitions into a single application schema.\n *\n * Steps:\n * 1. Apply event wiring (adds emits/listens to traits)\n * 2. Detect or use provided layout strategy\n * 3. Generate pages based on the strategy\n * 4. Build the final OrbitalSchema\n */\nexport function composeBehaviors(\n    input: ComposeBehaviorsInput,\n): ComposeBehaviorsResult {\n    const {\n        appName,\n        orbitals: rawOrbitals,\n        layoutStrategy: strategyInput,\n        eventWiring,\n    } = input;\n\n    // Step 1: Apply event wiring\n    const wiredOrbitals =\n        eventWiring && eventWiring.length > 0\n            ? applyEventWiring(rawOrbitals, eventWiring)\n            : rawOrbitals;\n\n    // Step 2: Determine layout strategy\n    const strategy: LayoutStrategy =\n        !strategyInput || strategyInput === 'auto'\n            ? detectLayoutStrategy(wiredOrbitals, eventWiring)\n            : strategyInput;\n\n    // Step 3: Generate pages\n    const pages = generatePages(wiredOrbitals, strategy);\n\n    // Step 4: Assign generated pages to orbitals (merge, don't replace existing)\n    const orbitalsWithPages = wiredOrbitals.map((orbital, index) => {\n        // If the orbital already has pages, keep them\n        if (orbital.pages && orbital.pages.length > 0) {\n            return orbital;\n        }\n\n        // Assign the generated page for this orbital\n        const page = strategy === 'dashboard' || strategy === 'single'\n            ? pages[0]\n            : pages[index];\n\n        return {\n            ...orbital,\n            pages: page ? [page] : [],\n        };\n    });\n\n    // Step 5: Build the schema\n    const schema: OrbitalSchema = {\n        name: appName,\n        version: '1.0.0',\n        orbitals: orbitalsWithPages,\n    };\n\n    return {\n        schema,\n        layout: {\n            strategy,\n            pageCount: pages.length,\n        },\n        wiring: {\n            connections: eventWiring?.length ?? 0,\n        },\n    };\n}\n","/**\n * Pipe Behaviors\n *\n * Left-to-right composition. Each step receives the previous result as its\n * first argument and returns the value handed to the next step.\n *\n * @packageDocumentation\n */\n\n/**\n * A single step in a behavior pipeline.\n */\nexport type PipeStep<I, O> = (input: I) => O;\n\n/**\n * Apply a series of transformation steps to a seed value, left to right.\n * Each step receives the previous step's output as its first argument.\n *\n * @example\n * ```ts\n * pipeBehaviors(1, (n) => n + 1, (n) => n * 10); // -> 20\n * ```\n */\nexport function pipeBehaviors<T>(\n    seed: T,\n    ...steps: Array<PipeStep<unknown, unknown>>\n): unknown {\n    let current: unknown = seed;\n    for (const step of steps) {\n        current = step(current);\n    }\n    return current;\n}\n"]}

package/dist/{types-CvYnmqkg.d.ts → types-CM6txTNy.d.ts}

@@ -176,6 +176,20 @@ interface EffectHandlers {
     }) => void;
     /** Atomic: execute inner effects as a transaction */
     atomic?: (effects: unknown[]) => Promise<void>;
+    /** Compose multiple orbitals into one schema. Compile-time only. */
+    composeBehaviors?: (config: {
+        appName: string;
+        orbitals: unknown[];
+        layoutStrategy?: string;
+        eventWiring?: unknown[];
+        entityMappings?: Record<string, string>;
+    }) => Promise<unknown> | unknown;
+    /** Apply cross-orbital event wiring. Compile-time only. */
+    applyEventWiring?: (orbitals: unknown[], wiring: unknown[]) => Promise<unknown[]> | unknown[];
+    /** Auto-detect layout strategy. Compile-time only. */
+    detectLayoutStrategy?: (orbitals: unknown[], wiring?: unknown[]) => Promise<string> | string;
+    /** Left-to-right behavior pipeline. Compile-time only. */
+    pipeBehaviors?: (seed: unknown, ...steps: Array<(prev: unknown) => unknown>) => Promise<unknown> | unknown;
     /** Watch file system for changes matching glob pattern */
     osWatchFiles?: (glob: string, options: {
         recursive?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/runtime",
-  "version": "2.7.0",
+  "version": "3.0.1",
   "description": "Interpreted runtime for Almadar orbital applications (OrbitalServerRuntime)",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,7 +38,7 @@
   "dependencies": {
     "@almadar/evaluator": ">=2.5.4",
     "@almadar/operators": ">=2.1.3",
-    "@almadar/core": ">=2.13.0",
+    "@almadar/core": ">=4.2.0",
     "@faker-js/faker": "^9.3.0"
   },
   "peerDependencies": {