@micheeeeel/yinyangapp 1.0.6 → 2.0.0

package/dist/types/components/controller/actions/ChildActionMenuController.d.ts

@@ -0,0 +1,83 @@
+import { IYinYangController } from "../../../interfaces/IYinYangController";
+import { IYinYangView } from "../../../interfaces/IYinYangView";
+import { type ActionDefinition } from "../../../data/yasuni_actions";
+import { ChildrenOrbitEntry } from "../utils/childrenOrbit";
+import { type Point } from "./radialItemMenu";
+type ChildActionMenuContext = {
+    orbitData: ChildrenOrbitEntry[];
+    activeActionMenuChildKey: string | null;
+    activeActionMenuActionId: string | null;
+    childActionMenuItemDistance: number;
+    childActionMenuItemScale: number;
+    childActionIconFontScale: number;
+    /** Actions filtrées pour le cutting actif (depuis yasuniCause + actionMap). */
+    actionsForActiveChild: ActionDefinition[];
+};
+export declare class ChildActionMenuController {
+    private readonly view;
+    private readonly getChildRenderedCenter;
+    private readonly refreshActionStackVisual;
+    /** Aperçu — 1er clic sur une action : affiche sa carte, ne joue rien. */
+    private readonly activateActionFromChild;
+    /** Validation — 2e clic sur l'action déjà en aperçu : l'ajoute à la pile. */
+    private readonly validateActionSelection;
+    /** Glisser une bulle vers une position précise de la pile — cœur partagé
+     *  avec le glisser-déposer depuis la hiérarchie RECHERCHE et depuis le
+     *  menu des Événements Clés (voir SearchPanelSynchronizer.startActionDrag,
+     *  entièrement générique). Retourne une poignée d'annulation, conservée
+     *  dans activeDragCancel. */
+    private readonly startActionDrag;
+    private childActionMenuGroup;
+    /** Groupe séparé pour les traits satellite → bulle, repositionné à chaque
+     *  update() juste devant children-group (voir ensureLineLayer) pour
+     *  qu'ils s'affichent derrière les satellites plutôt que par-dessus —
+     *  même technique que CoreEventMenuController.coreEventLineLayer. */
+    private childActionLineLayer;
+    private lastChildActionMenuSourceCenter;
+    /** Poignée d'annulation du glisser-déposer en cours (voir startActionDrag),
+     *  ou null si aucun glisser n'est en cours. */
+    private activeDragCancel;
+    /** Bulle survolée — sert uniquement à allumer l'impulsion de son lien
+     *  (voir linkStyleGetter) ; l'aperçu reste porté par le contexte. */
+    private hoveredActionId;
+    /** Résolveur de style des liens, reconstruit à chaque update() (il capture
+     *  le contexte courant) et rejoué au survol : rallumer une impulsion ne
+     *  doit pas relancer la chorégraphie d'ouverture. */
+    private linkStyleGetter;
+    constructor(view: IYinYangView, getChildRenderedCenter: (childController: IYinYangController) => Point | null, refreshActionStackVisual: () => void, 
+    /** Aperçu — 1er clic sur une action : affiche sa carte, ne joue rien. */
+    activateActionFromChild: (childController: IYinYangController, actionId: string, label?: string) => void, 
+    /** Validation — 2e clic sur l'action déjà en aperçu : l'ajoute à la pile. */
+    validateActionSelection: (childController: IYinYangController, actionId: string, label: string, insertAtVisibleIndex?: number | null, entryOrigin?: Point) => void, 
+    /** Glisser une bulle vers une position précise de la pile — cœur partagé
+     *  avec le glisser-déposer depuis la hiérarchie RECHERCHE et depuis le
+     *  menu des Événements Clés (voir SearchPanelSynchronizer.startActionDrag,
+     *  entièrement générique). Retourne une poignée d'annulation, conservée
+     *  dans activeDragCancel. */
+    startActionDrag: (iconUrl: string, startEvent: PointerEvent, sourceEl: Element, onDrop: (insertAtVisibleIndex: number | null, entryOrigin: Point) => void) => () => void);
+    /** Callback déclenché quand la souris entre/sort d'un cercle d'action dans le menu radial. */
+    private _onActionHoverCb?;
+    setOnActionHover(cb: (actionId: string | null, activeChildKey: string) => void): void;
+    /**
+     * Applique un highlight de survol sur le cercle d'action identifié, ou le retire si null.
+     * Le highlight est posé sur le <g> wrapper (pas sur le <circle>) pour éviter le conflit
+     * avec le filtre inline déjà présent sur le cercle.
+     */
+    highlightActionById(actionId: string | null): void;
+    /** Restyle les seuls liens (impulsion allumée/éteinte), sans toucher à leur
+     *  géométrie : le survol ne doit rien réanimer. */
+    private setHoveredAction;
+    retractAndDispose(): void;
+    clearImmediately(): void;
+    /**
+     * Starts the fold-out animation on the visible action buttons, then removes
+     * the group once every item has finished animating.  Nulls the group
+     * reference immediately so that any synchronous clearImmediately() call
+     * that follows is a no-op and won't cancel the in-flight transition.
+     */
+    animateClose(): void;
+    update(context: ChildActionMenuContext): void;
+    private ensureChildActionMenuGroup;
+    private ensureLineLayer;
+}
+export {};

package/dist/types/components/controller/actions/CoreEventMenuController.d.ts

@@ -0,0 +1,90 @@
+import { IYinYangView } from "../../../interfaces/IYinYangView";
+import type { KeyEventDefinition } from "../../../data/yasuni_key_events";
+import { type Point } from "./radialItemMenu";
+type CoreEventMenuContext = {
+    /** null/false ferme le menu (même logique que activeActionMenuChildKey côté satellite). */
+    isOpen: boolean;
+    keyEventsForActiveFacette: KeyEventDefinition[];
+    /** Id de l'événement actuellement en aperçu (carte affichée), ou null. */
+    activeKeyEventId: string | null;
+    /** Même valeur que le contrôle "Distance boutons" du groupe "Grappe Actions"
+     *  (state.menu.itemDistance) — pas de contrôle dédié : voir le calcul de
+     *  offsetDistance plus bas, qui la réutilise telle quelle. */
+    childActionMenuItemDistance: number;
+    /** Distance centre du cercle central → satellites de la facette active
+     *  (moyenne des rayons d'orbite réels, cf. buildChildrenOrbitData) — le
+     *  "connu" dont dérive offsetDistance plus bas. */
+    childrenOrbitRadius: number;
+    /** Taille des bulles — contrôle dédié "Taille boutons" du groupe
+     *  "Événements clés" (state.menu.coreEventMenuItemScale) : les Événements
+     *  Clés se dimensionnent indépendamment des boutons d'action des
+     *  satellites. */
+    coreEventMenuItemScale: number;
+    coreEventIconFontScale: number;
+    /** Ajustement fin (px) de la distance des boutons, de part et d'autre de
+     *  la longueur auto-calculée — contrôle "Distance boutons" du groupe
+     *  "Événements clés", voir state.menu.coreEventMenuDistanceOffset. */
+    coreEventMenuDistanceOffset: number;
+};
+/**
+ * Menu radial des Événements Clés, déclenché par un clic sur le cercle
+ * central (yin-yang) de la facette active — même langage visuel et même
+ * sémantique de clic que ChildActionMenuController (bulles + icône,
+ * chorégraphie D3 en éventail, 1er clic = aperçu / 2e clic sur l'item déjà
+ * actif = validation — factorisées dans radialItemMenu.ts), mais ancré sur
+ * le centre fixe de la facette plutôt que sur un satellite, et déployé à
+ * angle égal sur 360° plutôt que sur un axe source.
+ */
+export declare class CoreEventMenuController {
+    private readonly view;
+    /** Aperçu — 1er clic sur un événement : affiche sa carte, ne joue rien. */
+    private readonly previewKeyEvent;
+    /** Validation — 2e clic sur l'événement déjà en aperçu : l'ajoute à la pile
+     *  (au sommet par défaut, ou à insertAtVisibleIndex si fourni par un
+     *  glisser-déposer — voir startKeyEventDrag). */
+    private readonly validateKeyEventSelection;
+    /** Glisser une bulle vers une position précise de la pile — même cœur
+     *  partagé que ChildActionMenuController.startActionDrag (voir
+     *  SearchPanelSynchronizer.startActionDrag, entièrement générique).
+     *  Retourne une poignée d'annulation, conservée dans activeDragCancel. */
+    private readonly startKeyEventDrag;
+    private coreEventMenuGroup;
+    /** Groupe séparé pour les traits centre → bulle, abaissé au fond du
+     *  z-order (voir ensureLineLayer) pour qu'ils s'affichent derrière le
+     *  disque central et les satellites plutôt que par-dessus. */
+    private coreEventLineLayer;
+    /** Poignée d'annulation du glisser-déposer en cours (voir startKeyEventDrag),
+     *  ou null si aucun glisser n'est en cours — même rôle que
+     *  ChildActionMenuController.activeDragCancel. */
+    private activeDragCancel;
+    /** Bulle actuellement survolée — sert uniquement à allumer l'impulsion de
+     *  son lien (voir linkStyleGetter) ; l'état d'aperçu, lui, reste porté par
+     *  context.activeKeyEventId. */
+    private hoveredKeyEventId;
+    /** Résolveur de style des liens, reconstruit à chaque update() (il capture
+     *  le contexte courant) et rejoué tel quel au survol : rallumer une
+     *  impulsion ne doit pas relancer toute la chorégraphie. */
+    private linkStyleGetter;
+    constructor(view: IYinYangView, 
+    /** Aperçu — 1er clic sur un événement : affiche sa carte, ne joue rien. */
+    previewKeyEvent: (keyEvent: KeyEventDefinition) => void, 
+    /** Validation — 2e clic sur l'événement déjà en aperçu : l'ajoute à la pile
+     *  (au sommet par défaut, ou à insertAtVisibleIndex si fourni par un
+     *  glisser-déposer — voir startKeyEventDrag). */
+    validateKeyEventSelection: (keyEvent: KeyEventDefinition, insertAtVisibleIndex?: number | null, entryOrigin?: Point) => void, 
+    /** Glisser une bulle vers une position précise de la pile — même cœur
+     *  partagé que ChildActionMenuController.startActionDrag (voir
+     *  SearchPanelSynchronizer.startActionDrag, entièrement générique).
+     *  Retourne une poignée d'annulation, conservée dans activeDragCancel. */
+    startKeyEventDrag: (iconUrl: string, startEvent: PointerEvent, sourceEl: Element, onDrop: (insertAtVisibleIndex: number | null, entryOrigin: Point) => void) => () => void);
+    private _onHoverCb?;
+    setOnHover(cb: (keyEventId: string | null) => void): void;
+    clearImmediately(): void;
+    update(context: CoreEventMenuContext): void;
+    /** Restyle les seuls liens (impulsion allumée/éteinte) sans toucher à leur
+     *  géométrie : le survol ne doit rien réanimer. */
+    private setHoveredKeyEvent;
+    private ensureGroup;
+    private ensureLineLayer;
+}
+export {};

package/dist/types/components/controller/actions/radialItemMenu.d.ts

@@ -0,0 +1,117 @@
+import * as d3 from "d3";
+export type Point = {
+    x: number;
+    y: number;
+};
+export type FanLayoutMode = "arc" | "full-circle";
+export type RadialMenuItemPosition<T> = {
+    uniqueKey: string;
+    id: string;
+    x: number;
+    y: number;
+    r: number;
+    item: T;
+};
+/**
+ * Calcule la position en éventail de chaque item autour d'un centre.
+ * - mode "arc" : réparti sur ±maxAngularOffset autour de `axis` (menu
+ *   satellite — doit respecter un axe "depuis la source").
+ * - mode "full-circle" : réparti à angle égal sur les 360° (menu du
+ *   cercle central — pas d'axe source à respecter, maximise l'écart
+ *   angulaire entre bulles).
+ */
+export declare function computeFanPositions<T extends {
+    id: string;
+}>(items: T[], opts: {
+    mode: FanLayoutMode;
+    center: Point;
+    axis: number;
+    maxAngularOffset?: number;
+    offsetDistance: number;
+    itemRadius: number;
+    keyPrefix: string;
+}): RadialMenuItemPosition<T>[];
+/**
+ * Referme et retire toutes les bulles d'un menu radial (repli en
+ * éventail), utilisé à la fois quand update() ne reçoit plus de
+ * contexte actif et par les fermetures explicites (animateClose).
+ */
+export declare function closeAllRadialItems(groupNode: SVGGElement, dataRole: string, onAllClosed?: () => void): void;
+/**
+ * Chorégraphie D3 commune (data join, transition de sortie, création
+ * ligne+cercle+image à l'entrée, transition d'ouverture) — le style
+ * visuel par item (couleurs, tailles selon état actif) reste à la
+ * charge de l'appelant via un `.each()` sur la sélection retournée,
+ * les deux menus ayant des palettes distinctes.
+ */
+export declare function renderRadialItemsChoreography<T>(params: {
+    groupNode: SVGGElement;
+    dataRole: string;
+    positions: RadialMenuItemPosition<T>[];
+    exitAnimationCenter: Point;
+    enterCenter: Point;
+    getIconUrl: (id: string) => string;
+    /** Décor optionnel inséré entre la plaque (cercle) et le pictogramme, sur
+     *  la seule sélection enter() — c'est par là que le menu des Événements
+     *  Clés glisse son filigrane Yin/Yang, que le menu des actions n'a pas.
+     *  Appelé à cet endroit précis pour que le z-order (plaque → décor →
+     *  icône) tombe juste sans réordonnancement. */
+    decorateItemEnter?: (enter: d3.Selection<SVGGElement, RadialMenuItemPosition<T>, SVGGElement, unknown>) => void;
+    onItemClick: (item: T) => void;
+    onItemHoverEnter?: (item: T) => void;
+    onItemHoverLeave?: (item: T) => void;
+}): d3.Selection<SVGGElement, RadialMenuItemPosition<T>, SVGGElement, unknown>;
+/** Style d'un lien, résolu par l'appelant depuis son propre état (les deux
+ *  menus ont des palettes distinctes — ambre pour les Événements Clés,
+ *  vert/cyan pour les actions — mais la même mise en scène). */
+export type RadialItemLinkStyle = {
+    /** Teinte du faisceau. L'alpha du rgba est celui de l'extrémité BULLE :
+     *  le dégradé se charge de le ramener à zéro côté parent. */
+    color: string;
+    /** Item en aperçu : faisceau plus large et plus net. */
+    isActive?: boolean;
+    /** Cœur en pointillés (Événement Clé verrouillé). */
+    dashed?: boolean;
+    /** Impulsion qui remonte le lien — actif ou survolé uniquement. */
+    pulse?: boolean;
+};
+/**
+ * Applique le style (teinte, épaisseur, pointillés, impulsion) sur les liens
+ * déjà en place, SANS toucher à leur géométrie ni relancer d'animation
+ * d'ouverture. Séparé du rendu pour que le survol d'une bulle puisse
+ * rallumer l'impulsion de son seul lien à coût nul.
+ */
+export declare function styleRadialItemLinks<T extends {
+    id: string;
+}>(groupNode: SVGGElement | null, dataRole: string, getStyle: (d: RadialMenuItemPosition<T>) => RadialItemLinkStyle): void;
+/**
+ * Chorégraphie D3 des liens parent → item, rendus dans un groupe SÉPARÉ de
+ * celui des bulles (voir CoreEventMenuController : ce groupe est glissé plus
+ * tôt dans le z-order pour passer derrière les satellites et le disque
+ * central, alors que les bulles restent devant dans leur propre groupe).
+ * Anime directement x2/y2 des lignes : un lien entrant grandit depuis le bord
+ * du parent vers l'item, un lien sortant s'y rétracte puis disparaît — même
+ * easing/cascade que renderRadialItemsChoreography pour rester visuellement
+ * synchronisé avec les bulles. `positions: []` ferme tous les liens existants
+ * (repli complet), sans qu'un appelant ait besoin d'une fonction dédiée.
+ */
+export declare function renderRadialItemLinks<T extends {
+    id: string;
+}>(params: {
+    groupNode: SVGGElement;
+    dataRole: string;
+    positions: RadialMenuItemPosition<T>[];
+    center: Point;
+    /** Rayon du disque parent : le faisceau démarre à son bord. 0 = au centre. */
+    startRadius?: number;
+    getStyle?: (d: RadialMenuItemPosition<T>) => RadialItemLinkStyle;
+}): void;
+/**
+ * Sémantique de clic partagée par les deux menus radiaux : un premier
+ * clic sur un item prévisualise (affiche sa carte, ne joue rien) ; un
+ * second clic sur ce même item déjà actif valide (l'ajoute à la
+ * pile). Cliquer un autre item pendant qu'un aperçu est actif bascule
+ * l'aperçu sans valider — c'est simplement le cas "isAlreadyActive
+ * === false" pour ce nouvel item.
+ */
+export declare function handleRadialItemClick(isAlreadyActive: boolean, onPreview: () => void, onValidate: () => void): void;

package/dist/types/components/controller/children/ChildInteractionController.d.ts

@@ -0,0 +1,38 @@
+import { IYinYangController } from "../../../interfaces/IYinYangController";
+import { IYinYangView } from "../../../interfaces/IYinYangView";
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+type ChildOddMeta = {
+    oddId: string;
+    score: number;
+    cuttingIndex: number;
+};
+type ChildInteractionControllerDeps = {
+    view: IYinYangView;
+    getCurrentComponent: () => YinYangInternalModel["components"][number] | null;
+    getActiveChildKey: () => string | null;
+    setActiveChildKey: (childKey: string | null) => void;
+    openActionMenuFromChild: (childController: IYinYangController) => void;
+    highlightOddInChildren: (oddId: string | null) => void;
+    cancelOddHighlight: () => void;
+    syncGhostTensionFromAction: () => void;
+    renderGhostDetailsForActiveAction: () => void;
+    onUserCuttingClicked?: (childController: IYinYangController) => void;
+    /** Appelé quand la souris entre/sort d'un satellite (null = sortie). */
+    onChildHover?: (oddId: string | null, cuttingIndex?: number) => void;
+};
+export declare class ChildInteractionController {
+    private deps;
+    constructor(deps: ChildInteractionControllerDeps);
+    setChildrenHiddenState(childControllers: IYinYangController[], hidden: boolean): void;
+    attachChildToggleHandler(childController: IYinYangController, childOddMap: Map<string, ChildOddMeta>): void;
+    attachChildHoverHandler(childController: IYinYangController, childOddMap: Map<string, ChildOddMeta>): void;
+    attachBackgroundClickHandler(): void;
+    enterOddView(oddId: string): void;
+    exitOddView(): void;
+    setActiveChild(childControllers: IYinYangController[], childKey: string): void;
+    clearActiveChild(childControllers: IYinYangController[]): void;
+    animateChildren(childControllers: IYinYangController[], show: boolean, onBeforeShow?: () => void, onBeforeHide?: () => void): Promise<void>;
+    private applyChildActiveStyle;
+    private getChildOffset;
+}
+export {};

package/dist/types/components/controller/children/ChildrenOrbitService.d.ts

@@ -0,0 +1,14 @@
+import { IYinYangController } from "../../../interfaces/IYinYangController";
+import { ChildrenOrbitEntry } from "../utils/childrenOrbit";
+export declare class ChildrenOrbitService {
+    buildOrbitData(params: {
+        parentX: number;
+        parentY: number;
+        childControllers: IYinYangController[];
+        radiusScale: number;
+    }): ChildrenOrbitEntry[];
+    computeTranslation(orbitEntry: ChildrenOrbitEntry, angleOffset: number): {
+        x: number;
+        y: number;
+    };
+}

package/dist/types/components/controller/force-field/EventFieldLifecycleController.d.ts

@@ -0,0 +1,104 @@
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+import { IYinYangController } from "../../../interfaces/IYinYangController";
+import { ActionStackItem } from "../action-stack/ActionStackController";
+import { KeyEventDefinition } from "../../../data/yasuni_key_events";
+import { EventFieldRenderer, Point } from "./EventFieldRenderer";
+import { YinYangControllerState } from "../state/YinYangControllerState";
+type ChildOddMeta = {
+    oddId: string;
+    score: number;
+    cuttingIndex: number;
+};
+type EventFieldLifecycleControllerDeps = {
+    state: YinYangControllerState;
+    childOddMap: Map<string, ChildOddMeta>;
+    eventFieldRenderer: EventFieldRenderer;
+    /** Événements Clés qui pilotent le champ pour la frame courante — aperçu
+     *  RECHERCHE (un seul) ou items cochés de la pile en mode STACK (plusieurs
+     *  possibles), déjà réduits par l'appelant à un jeu qui partage UNE source
+     *  (voir YinYangController.getEventFieldKeyEvents). */
+    getActiveKeyEvents: () => KeyEventDefinition[];
+    getCurrentComponentOrUndefined: () => YinYangInternalModel["components"][number] | undefined;
+    getActiveItems: () => ActionStackItem[];
+    getChildControllers: () => IYinYangController[];
+    getGlobalGroupNode: () => SVGGElement | null;
+    getChildRenderedCenter: (childController: IYinYangController) => Point | null;
+    getComponentBorderTargetPoint: (componentId: string) => Point | null;
+    getEventFieldSource: () => {
+        center: Point | null;
+        radius: number;
+    };
+};
+/**
+ * Cycle de vie du "Champ d'événement" (souffle cœur → satellites de
+ * l'Événement Clé en aperçu ou validé) : calcul des cibles, boucle rAF,
+ * délégation au dessin. Miroir de ForceFieldLifecycleController pour le
+ * champ de force d'action — même découpage état (YinYangControllerState) /
+ * orchestration (ici) / dessin (EventFieldRenderer).
+ */
+export declare class EventFieldLifecycleController {
+    private deps;
+    private _targetsCacheKey;
+    private _targetsCacheResult;
+    constructor(deps: EventFieldLifecycleControllerDeps);
+    /**
+     * Recalcule les cibles du Champ d'événement et démarre/arrête son animation
+     * en conséquence. À appeler à chaque aperçu/validation/ouverture-fermeture
+     * du menu radial, à chaque toggle de visibilité de la pile ET à chaque
+     * bascule d'onglet RECHERCHE/STACK : la portée elle-même ne dépend pas de la
+     * pile, mais l'épaisseur du souffle distingue les satellites réellement
+     * amplifiés, qui en dépendent — et en mode STACK ce sont les événements
+     * cochés de la pile qui décident du champ tout entier.
+     */
+    updateEventField(): void;
+    /**
+     * Recalcule state.eventField.targets pour la frame courante (cache-key
+     * gated via getTargets — quasi gratuit quand rien n'a changé) et, s'il n'y
+     * a plus rien à montrer, cache le champ. Retourne false dans ce cas (rien
+     * à rendre cette frame), true sinon.
+     *
+     * Appelée aussi bien par updateEventField (points d'entrée explicites :
+     * aperçu, toggle pile, fin de switch) que par la boucle rAF de
+     * startEventFieldAnimation. Cette dernière en a besoin car
+     * currentComponentId peut changer de façon SYNCHRONE bien avant que
+     * updateEventField() ne soit rappelé : un clic sur l'arc de facette flippe
+     * ViewInitializer.currentComponentIndex dès animateToComponent(), alors
+     * que refreshChildrenForComponentSwitch() (qui, lui, rappelle
+     * updateEventField pour de vrai) n'arrive qu'~componentSwitchDurationMs
+     * plus tard, une fois les satellites de la nouvelle facette créés.
+     * getEventFieldSource() (le point de départ) réagit à ce flip dès la frame
+     * suivante puisqu'il est relu à chaque frame — sans ce recalcul ici, les
+     * CIBLES (donc les points d'arrivée) restaient l'ancien tableau pendant
+     * tout le switch : un cordon arc-à-arc incohérent (source déjà "entrant",
+     * cible encore l'ancien point distant) jusqu'à la correction tardive.
+     */
+    private refreshTargets;
+    /** Mémoïse buildEventFieldTargets : coûteux à parcourir (yasuniCause en
+     *  entier) mais dont les entrées pertinentes ne changent qu'avec la
+     *  facette, les Événements Clés actifs, ou les items de pile qui les
+     *  concernent — voir buildTargetsCacheKey, concaténée sur tout le jeu. */
+    private getTargets;
+    /**
+     * Union des portées de plusieurs Événements Clés actifs (pile STACK avec
+     * plusieurs événements cochés) : un satellite touché par deux d'entre eux
+     * ne reçoit qu'UN cordon — le renderer n'a qu'une source, deux cordons
+     * superposés se liraient comme un seul, en plus lumineux. On garde le
+     * coefficient le plus fort, celui qui décrit l'amplification réellement
+     * subie par ce satellite.
+     */
+    private mergeTargets;
+    /** Ne dépend que de ce qui peut réellement changer le résultat : la
+     *  facette courante, la taille du mapping ODD (proxy de changement de
+     *  facette, même convention que ForceFieldLifecycleController), et — parmi
+     *  les items de la pile — seulement ceux liés à CET Événement Clé (son
+     *  propre item, pour la règle de slotIndex, et les actions qu'il cible).
+     *  Les autres items de la pile n'influencent pas le champ d'événement. */
+    private buildTargetsCacheKey;
+    /** Résout les cibles courantes en points écran et pousse la frame au
+     *  renderer — appelé une fois par updateEventField (état) et à chaque
+     *  frame par startEventFieldAnimation (orbite + pulsation). */
+    private updateEventFieldVisual;
+    private startEventFieldAnimation;
+    private stopEventFieldAnimation;
+}
+export {};

package/dist/types/components/controller/force-field/EventFieldRenderer.d.ts

@@ -0,0 +1,86 @@
+export type Point = {
+    x: number;
+    y: number;
+};
+/** Segment cœur → cible déjà résolu en points écran — la résolution
+ *  logique (quel satellite, quelle facette) vit dans eventFieldTargets.ts,
+ *  ce renderer ne fait que dessiner. */
+export type EventFieldRenderSegment = {
+    end: Point;
+    /** Bonus de score de l'Événement Clé — pilote l'épaisseur du souffle. */
+    scoreBonus: number;
+};
+/**
+ * Chorégraphie du "Champ d'événement" : un souffle annulaire. Le cœur du
+ * yin/yang (le disque central du lobe de l'orientation courante, pas le
+ * centre géométrique du symbole) émet des anneaux concentriques ; chaque
+ * anneau allume au passage le segment de cordon qu'il traverse, puis éclate
+ * en onde de choc en atteignant le satellite amplifié.
+ *
+ * Les anneaux sont partagés par toutes les cibles — un seul souffle,
+ * plusieurs impacts — ce qui dit visuellement ce que fait un Événement Clé :
+ * quelque chose se produit au niveau de la facette et irradie vers les
+ * satellites concernés.
+ *
+ * Volontairement distinct du beam laser rectiligne et continu des champs de
+ * force d'action (ForceFieldRenderer) : la distinction porte sur la
+ * grammaire temporelle (émission rythmée vs flux continu) autant que sur la
+ * teinte, elle survit donc à un changement de palette.
+ */
+export declare class EventFieldRenderer {
+    private group;
+    private rings;
+    private layers;
+    private coreHalo;
+    /** setTimeout id du fondu de sortie en cours, ou null — voir hide(). */
+    private _hideTimeoutId;
+    /** requestAnimationFrame id de la rétraction géométrique en cours — voir retractGeometry(). */
+    private _retractFrameId;
+    hasActiveGroup(): boolean;
+    ensureElements(params: {
+        globalGroupNode: SVGGElement;
+        requiredCount: number;
+    }): void;
+    /**
+     * Fondu de sortie : au lieu de retirer le groupe instantanément (clear()),
+     * ramène son opacité à 0 sur fieldFadeOutDurationMs puis le retire
+     * réellement — même grammaire de disparition que ForceFieldRenderer.hide().
+     * Idempotent : un appel alors qu'un fondu est déjà en cours ne fait rien de
+     * plus (le clear() en attente suffit).
+     */
+    hide(): void;
+    /**
+     * Rétraction géométrique : ramène chaque cordon vers le cœur (ou l'arc de
+     * bordure en mode entrant), inverse exact de la croissance animatedEnd de
+     * updateVisual (même courbe lue à l'envers : d3.easeCubicOut(1 - t)).
+     * Repart de _prevCord — la géométrie du dernier frame réellement rendu —
+     * donc indépendante de tout state externe : continue même si la cible
+     * (satellite, Événement Clé actif) a déjà disparu entre temps. headAura/
+     * headCore suivent la pointe rétractée : leur opacité a un plancher non
+     * nul (0.3 / 0.6 × revealEase dans updateVisual, visibles même hors flash
+     * d'impact) — les laisser figés à l'ancienne cible les détacherait
+     * visiblement du cordon en train de se rétracter sous eux. Seuls les
+     * anneaux / capsules / onde de choc restent figés sur leur dernière pose
+     * et s'effacent avec le fondu d'opacité du groupe posé par hide().
+     */
+    private retractGeometry;
+    clear(): void;
+    updateVisual(params: {
+        /** Centre du cœur — disque central du lobe yin OU yang selon
+         *  l'orientation de la facette courante, jamais le centre du symbole. */
+        sourceCenter: Point | null;
+        /** Rayon de ce disque : les cordons partent de son bord et les anneaux
+         *  naissent à sa circonférence, pas d'un point. */
+        sourceRadius: number;
+        segments: EventFieldRenderSegment[];
+        /** Temps écoulé en secondes depuis le début de l'animation. */
+        phase: number;
+        /** performance.now() du dernier souffle qui a (ré)apparu — undefined ou
+         *  déjà écoulé = plein régime immédiat. Pilote la croissance cœur → cible
+         *  à l'apparition, même convention que ForceFieldRenderer (revealStartedAt
+         *  / revealEase) : sans elle le cordon surgissait déjà à pleine longueur
+         *  et pleine opacité, contrastant avec le beam d'action qui se dessine
+         *  progressivement. */
+        revealStartedAt?: number;
+    }): void;
+}

package/dist/types/components/controller/force-field/ForceFieldComputationService.d.ts

@@ -0,0 +1,50 @@
+import { type PropagatedActionEdge } from "../../../utils/actionPropagation";
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+import { CauseGraph } from "../../../interfaces/ICauseGraph";
+import { PropagationLayersConfig } from "../../../interfaces/IPropagationLayers";
+import { ChildrenOrbitEntry } from "../utils/childrenOrbit";
+import { ForceFieldLink, ForceFieldLinkDetail } from "./types";
+/** Single source of truth for turning a raw propagation edge into the
+ *  enriched ForceFieldLinkDetail the UI consumes (rationale, layer
+ *  summaries…) — shared by build(), buildFromSource(), and any other caller
+ *  that needs to map edges from computeActionPropagationDetails/
+ *  propagateForceFieldActionInComponent without re-deriving this metadata. */
+export declare function mapPropagatedEdgeToDetail(edge: PropagatedActionEdge, componentId: string): ForceFieldLinkDetail;
+export declare class ForceFieldComputationService {
+    build(params: {
+        orbitData: ChildrenOrbitEntry[];
+        sourceChildIndex: number;
+        childOddMap: Map<string, {
+            oddId: string;
+            score: number;
+            cuttingIndex: number;
+        }>;
+        component: YinYangInternalModel["components"][number] | null;
+        allComponents: YinYangInternalModel["components"] | undefined;
+        actionDelta: number;
+        actionPropagationFactor: number;
+        interconnectionGraph: CauseGraph;
+        propagationLayers: PropagationLayersConfig;
+    }): {
+        links: ForceFieldLink[];
+        allLinkDetails: ForceFieldLinkDetail[];
+    } | null;
+    /**
+     * Variante de build() qui accepte directement sourceOddId + sourceCuttingId,
+     * sans avoir besoin de orbitData/childOddMap. Utilisée pour les actions
+     * cross-composantes où ces structures ne sont pas disponibles.
+     */
+    buildFromSource(params: {
+        sourceOddId: string;
+        sourceCuttingId: number | undefined;
+        component: YinYangInternalModel["components"][number];
+        allComponents: YinYangInternalModel["components"] | undefined;
+        actionDelta: number;
+        actionPropagationFactor: number;
+        interconnectionGraph: CauseGraph;
+        propagationLayers: PropagationLayersConfig;
+    }): {
+        links: ForceFieldLink[];
+        allLinkDetails: ForceFieldLinkDetail[];
+    } | null;
+}