@micheeeeel/yinyangapp 2.5.1 → 2.6.0

package/dist/types/components/controller/action-stack/ActionStackController.d.ts

@@ -47,11 +47,46 @@ export declare class ActionStackController {
         maxDeltaMultiplier?: number;
         direction?: "forward" | "backward";
     }): void;
+    /**
+     * Guide de placement d'un prérequis : un clic sur un prérequis absent de la
+     * pile (carte combo en mode STACK) ouvre RECHERCHE sur cette action et
+     * mémorise ici le contexte du combo. Dès que l'utilisateur glisse cette
+     * action vers la pile, les barres de position du combo réapparaissent —
+     * sans avoir à déposer puis recliquer sur la carte combo.
+     */
+    private _prereqDragGuide;
+    /** Vrai pendant un glisser guidé : les re-rendus du panneau (bascule
+     *  RECHERCHE → STACK) ne doivent pas effacer les barres en plein geste. */
+    private _prereqDragGuideActive;
+    setPrereqDragGuide(actionId: string, context: Parameters<ActionStackController["highlightComboContext"]>[0]): void;
+    /** Début du glisser de `actionId` vers la pile : affiche les barres du
+     *  combo mémorisé si cette action en est le prérequis. Retourne l'item de
+     *  pile portant le combo (pour réafficher son bloc), ou null. */
+    beginPrereqDragGuide(actionId: string): string | null;
+    /** Guide en cours de glisser : action glissée et item portant le combo. */
+    getActivePrereqDragGuide(): {
+        actionId: string;
+        sourceItemId: string;
+    } | null;
+    /**
+     * Historique slot-paddé (cf. getSlotPaddedActionIds) que verrait l'item
+     * `anchorItemId` si `insertedActionId` était déposé à l'emplacement
+     * actuellement survolé — même arithmétique d'insertion avec décalage que
+     * ActionStackState.addItem, sans muter la pile. null hors zone de dépôt.
+     */
+    getPriorIdsIfInsertedAtPreview(anchorItemId: string, insertedActionId: string): string[] | null;
+    /** Fin du glisser (dépôt ou abandon). Les barres restent affichées ; un
+     *  dépôt consomme le guide, un abandon le garde pour un nouvel essai. */
+    endPrereqDragGuide(dropped: boolean): void;
     /** Efface le surlignage combo et restaure l'apparence normale du stack. */
     clearComboHighlight(): void;
     setBlockHighlightCallback(cb: (id: string | null) => void): void;
     setSatelliteHighlightCallback(cb: (id: string | null) => void): void;
     getItemById(id: string): ActionStackItem | undefined;
+    /** Même effet qu'un clic sur le libellé de l'item (selectSatelliteForItem) :
+     *  sélection de son satellite ou de sa Facette, focus — ou défocus s'il
+     *  était déjà en focus. Sert aux bulles du diagramme en mode STACK. */
+    selectItemAsFromLabel(stackItemId: string): void;
     highlightByStackItemId(id: string | null): void;
     /** Focus persistant (miroir du bloc en focus dans le panneau) — survit aux
      *  re-rendus, updateVisual relisant _focusedItemId. */

package/dist/types/components/controller/action-stack/ActionStackManager.d.ts

@@ -92,6 +92,15 @@ export declare class ActionStackManager {
     getWeightDeltaByComponentOddCutting(): Map<string, number>;
     clearWeightPreview(): void;
     resetLastComboResults(): void;
+    /**
+     * Résultats combo d'une action. En mode STACK, ils tiennent compte de la
+     * pile (résultats de l'item s'il est empilé, sinon évaluation en haut de
+     * pile). En mode RECHERCHE, l'action est montrée BRUTE : la pile est
+     * ignorée (historique vide), ses prérequis apparaissent donc non joués,
+     * même s'ils sont empilés — seul le mode STACK fait jouer la pile.
+     * Exception : une sécurisation y est évaluée protecteurs supposés joués
+     * (×1), sinon elle serait toujours à ×0 et masquerait la propagation.
+     */
     computeComboResultsForAction(actionId: string): ComboResult[] | undefined;
     validateActionSelection(childController: IYinYangController, actionId: string, label: string, insertAtVisibleIndex?: number | null, entryOrigin?: {
         x: number;

package/dist/types/components/controller/action-stack/StackFocusController.d.ts

@@ -0,0 +1,105 @@
+import { IYinYangController } from "../../../interfaces/IYinYangController";
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+import { ChildrenOrbitEntry } from "../utils/childrenOrbit";
+import { ChildActionMenuController } from "../actions/ChildActionMenuController";
+import { ActionStackController, ActionStackItem } from "./ActionStackController";
+import { ForceFieldDetailsPanel } from "../force-field/ForceFieldDetailsPanel";
+import { YinYangControllerState } from "../state/YinYangControllerState";
+import { PropagationAnimator } from "../force-field/PropagationAnimator";
+import { OddViewManager } from "../odd/OddViewManager";
+export type StackFocusControllerDeps = {
+    actionStackController: ActionStackController;
+    buildChildrenOrbitData: () => ChildrenOrbitEntry[];
+    buildForceFieldSourceIndicesFromStackItems: (items: ActionStackItem[]) => number[];
+    childActionMenuController: ChildActionMenuController;
+    getChildControllers: () => IYinYangController[];
+    childOddMap: Map<string, {
+        oddId: string;
+        score: number;
+        cuttingIndex: number;
+    }>;
+    forceFieldDetailsPanel: ForceFieldDetailsPanel;
+    getAllComponents: () => YinYangInternalModel["components"];
+    getCurrentComponentOrUndefined: () => YinYangInternalModel["components"][number] | undefined;
+    oddViewManager: OddViewManager;
+    propagationAnimator: PropagationAnimator;
+    state: YinYangControllerState;
+    updateChildActionMenu: (orbitData: ChildrenOrbitEntry[]) => void;
+};
+/** Focus et emphase d'un élément de pile : satellite source mis en valeur,
+ *  identité de la source pour l'atténuation du champ, bulle d'action en focus. */
+export declare class StackFocusController {
+    private deps;
+    constructor(deps: StackFocusControllerDeps);
+    /** Focus persistant — null pour l'effacer. */
+    setFocusedStackItem(stackItemId: string | null): void;
+    /**
+     * Clic sur le libellé d'un item déjà en focus, alors que son bloc est
+     * visible dans le panneau (satellite porteur sélectionné) : désactive le
+     * focus et retourne true — l'appelant n'a alors ni navigation ni scroll à
+     * faire. Si le bloc n'est pas visible (l'utilisateur a navigué ailleurs
+     * entre-temps), le clic redevient une sélection normale : false.
+     */
+    toggleStackItemFocusFromStack(stackItemId: string): boolean;
+    /** Aperçu par survol — null à la sortie, qui retombe sur le focus. */
+    setStackItemEmphasisPreview(stackItemId: string | null): void;
+    /**
+     * Point d'accroche unique de la mise en valeur du satellite source de
+     * l'action portant l'emphase (aperçu ?? focus). Réutilise pour l'instant
+     * le glow de highlightOddByStackItemId (ou le segment de bordure si la
+     * source est dans une autre facette) — l'anneau animé viendra ici.
+     * `clearIfNone` : sans emphase, efface la mise en valeur (sorties de
+     * survol, défocus) ; false pour les simples re-applications (satellites
+     * recréés, fin d'un survol de satellite) afin de ne pas écraser d'autres
+     * highlights en cours.
+     */
+    applyFocusedSourceHighlight(clearIfNone?: boolean): void;
+    /** Memo à une entrée de resolveEmphasisSourceChildIndex (lu chaque frame). */
+    private _emphasisSourceMemo;
+    /**
+     * Index orbital du satellite source de l'action portant l'emphase, ou null
+     * si rien ne doit être atténué : hors mode STACK (un aperçu RECHERCHE ne
+     * doit pas hériter d'un focus STACK résiduel), item absent, Événement Clé
+     * (pas de champ de force), ou source dans une autre facette (tout reste
+     * plein, la bordure source est surlignée par highlightOddByStackItemId).
+     * Résolution par oddId + cuttingIndex (buildForceFieldSourceIndicesFromStackItems),
+     * robuste au rebuild de childOddMap ; la clé du memo suit la convention de
+     * ForceFieldLifecycleController._buildPropCacheKey.
+     */
+    resolveEmphasisSourceChildIndex(): number | null;
+    /** Identité stable (sourceOriginKey) du satellite source d'un item de la
+     *  pile — null pour un Événement Clé ou une facette introuvable. */
+    stackItemSourceOriginKey(item: ActionStackItem): string | null;
+    private _emphasisKeyMemo;
+    /** Clé de la source de l'action portant l'emphase (aperçu ?? focus), quelle
+     *  que soit sa facette ; null hors STACK ou sans emphase. Lue à chaque frame. */
+    resolveEmphasisSourceOriginKey(): string | null;
+    /** Memo à une entrée de resolveFocusedActionSource (lu à chaque update du menu). */
+    private _focusSourceMemo;
+    /**
+     * Action en focus (focus persistant seulement, pas l'aperçu par survol —
+     * une bulle qui apparaît/disparaît au survol serait du bruit), résolue en
+     * (actionId, clé et index orbital du satellite source) dans la facette
+     * courante. null hors mode STACK, sans focus, pour un Événement Clé, ou si
+     * la source vit dans une autre facette.
+     */
+    resolveFocusedActionSource(): {
+        actionId: string;
+        sourceKey: string;
+        sourceIndex: number;
+    } | null;
+    /**
+     * Point de départ « bulle » du champ de force de l'action en focus : la
+     * bulle de son action dans le menu radial si le satellite source est celui
+     * sélectionné, sinon la bulle détachée posée sur la source. null si
+     * aucune bulle n'est visible (le champ démarre alors au satellite).
+     */
+    resolveFocusBubbleStub(): {
+        sourceChildIndex: number;
+        center: {
+            x: number;
+            y: number;
+        };
+    } | null;
+    highlightOddByStackItemId(stackItemId: string | null): void;
+}

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

@@ -1,5 +1,5 @@
 import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
-import { type PropagatedActionEdge } from "../../../utils/actionPropagation";
+import { type PropagatedActionEdge, type PropagationTruncation } from "../../../utils/actionPropagation";
 import { ForceFieldLink } from "../force-field/types";
 export type ProjectedCuttingState = {
     cuttingId: number;
@@ -17,6 +17,12 @@ export type GhostProjectionResult = {
 export type SequentialActionProjectionInput = {
     sourceOddId: string;
     sourceCuttingIndex: number;
+    /** Bouclier de stabilité (points d'état) que cette action crée sur son
+     *  satellite source une fois résolue — issu de ses slots de stabilisation
+     *  déclenchés (voir stabilityShieldFromResults). Actif pour toutes les
+     *  résolutions suivantes de la séquence, jamais consommé ; le plus fort
+     *  remplace le précédent sur un même satellite. */
+    shield?: number;
 };
 export type EmptyGhostProjectionState = {
     projectedGhostTensionByOddId: null;
@@ -30,10 +36,31 @@ export declare function projectGhostStateForIncomingLinks(params: {
     incomingLinks: ForceFieldLink[];
 }): GhostProjectionResult | null;
 export type ActionSequenceStateSnapshot = Map<string, Map<number, number>>;
+/** Réduction appliquée par un bouclier de stabilité lors d'une étape :
+ *  le satellite recevait `aggregated` (total négatif direct + propagé),
+ *  il ne reçoit finalement que `applied`. */
+export type ShieldAbsorption = {
+    oddId: string;
+    cuttingId: number;
+    shield: number;
+    aggregated: number;
+    applied: number;
+};
+/**
+ * Bouclier de stabilité sur UNE résolution : pour chaque satellite protégé,
+ * la variation de toute l'étape (état projeté − état de départ) agrège déjà
+ * le delta direct et tous les chemins propagés ; le bouclier réduit ce
+ * total une seule fois — jamais chaque contribution séparément, jamais
+ * au-delà de 0. Mute `projectedStates` et rend les réductions appliquées.
+ */
+export declare function applyStabilityShieldsToResolution(startStates: Record<string, Record<number, number>>, projectedStates: Record<string, Record<number, number>>, activeShields: Map<string, Map<number, number>>): ShieldAbsorption[];
 export type ActionSequenceStepInfo = {
     actionIndex: number;
     action: SequentialActionProjectionInput;
     effectiveDelta: number;
+    /** Boucliers ayant réduit une contribution négative de cette étape — vide
+     *  si aucun satellite protégé n'a été touché négativement. */
+    shieldAbsorptions: ShieldAbsorption[];
     /** Clone of the fractional accumulator just before this step is applied. */
     statesBefore: ActionSequenceStateSnapshot;
     /** Clone of the fractional accumulator just after this step is applied. */
@@ -44,13 +71,16 @@ export type ActionSequenceStepInfo = {
      *  callers build a descriptive breakdown (e.g. UI badges) that's guaranteed
      *  consistent with the state diff, without re-running propagation. */
     edges: PropagatedActionEdge[];
+    /** Passes locales interrompues par la garde technique pendant cette étape
+     *  (PROP-01) — vide si la résolution est complète. Un appelant qui affiche
+     *  l'étape doit signaler un résultat partiel plutôt que le taire. */
+    truncations: PropagationTruncation[];
 };
 export declare function projectGhostStateForActionSequence(params: {
     component: YinYangInternalModel["components"][number] | undefined;
     allComponents: YinYangInternalModel["components"] | undefined;
     actions: SequentialActionProjectionInput[];
     actionDelta: number;
-    actionPropagationFactor: number;
     /** Delta effectif par action (index-aligné sur `actions`). Quand fourni,
      *  remplace `actionDelta` pour chaque action individuellement. */
     actionDeltas?: number[];
@@ -67,7 +97,6 @@ export declare function projectGhostStateForComponent(params: {
     sourceOddId: string | undefined;
     sourceCuttingIndex: number;
     actionDelta: number;
-    actionPropagationFactor: number;
 }): GhostProjectionResult | null;
 export declare function getOriginalComponentTension(component: YinYangInternalModel["components"][number] | undefined): number | null;
 export declare function getOriginalOddTension(component: YinYangInternalModel["components"][number] | undefined, oddId: string): number | null;

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

@@ -23,14 +23,18 @@ type ChildActionMenuContext = {
     childActionIconFontScale: number;
     /** Actions filtrées pour le cutting actif (depuis yasuniCause + actionMap). */
     actionsForActiveChild: ActionDefinition[];
+    /** Mode STACK : la seule bulle déployée est celle de l'item en focus, et
+     *  son clic vaut clic sur le libellé de cet item dans la pile (ni aperçu,
+     *  ni glisser). null hors STACK. */
+    onStackBubbleClick: (() => void) | null;
 };
 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. */
+    /** Aperçu — 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. */
+    /** Validation — dépôt d'une bulle glissée sur la pile : l'y ajoute. */
     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
@@ -68,9 +72,9 @@ export declare class ChildActionMenuController {
     /** Centre de la bulle détachée si elle porte `actionId`, sinon null. */
     getDetachedCenter(actionId: string): Point | null;
     constructor(view: IYinYangView, getChildRenderedCenter: (childController: IYinYangController) => Point | null, refreshActionStackVisual: () => void, 
-    /** Aperçu — 1er clic sur une action : affiche sa carte, ne joue rien. */
+    /** Aperçu — 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. */
+    /** Validation — dépôt d'une bulle glissée sur la pile : l'y ajoute. */
     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

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

@@ -1,5 +1,5 @@
 import { IYinYangView } from "../../../interfaces/IYinYangView";
-import type { KeyEventDefinition } from "../../../data/yasuni_key_events";
+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). */
@@ -30,18 +30,18 @@ type CoreEventMenuContext = {
  * 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
+ * chorégraphie D3 en éventail factorisée dans radialItemMenu.ts ; clic =
+ * aperçu, glisser vers la pile = validation), 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). */
+    /** Clic sur une bulle — aperçu, ou focus de son item de pile en STACK
+     *  (voir KeyEventController.onKeyEventBubbleClick). */
+    private readonly onKeyEventClick;
+    /** Validation — dépôt d'une bulle glissée sur la pile : l'y ajoute à
+     *  insertAtVisibleIndex (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
@@ -66,11 +66,11 @@ export declare class CoreEventMenuController {
      *  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). */
+    /** Clic sur une bulle — aperçu, ou focus de son item de pile en STACK
+     *  (voir KeyEventController.onKeyEventBubbleClick). */
+    onKeyEventClick: (keyEvent: KeyEventDefinition) => void, 
+    /** Validation — dépôt d'une bulle glissée sur la pile : l'y ajoute à
+     *  insertAtVisibleIndex (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

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

@@ -0,0 +1,192 @@
+import { IYinYangView } from "../../../interfaces/IYinYangView";
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+import { type KeyEventDefinition } from "../../../data/yasuni_key_events";
+import { ChildrenOrbitEntry } from "../utils/childrenOrbit";
+import { CoreEventMenuController } from "./CoreEventMenuController";
+import { ActionStackController } from "../action-stack/ActionStackController";
+import { ForceFieldDetailsPanel } from "../force-field/ForceFieldDetailsPanel";
+import { EventFieldRenderer } from "../force-field/EventFieldRenderer";
+import { YinYangControllerState } from "../state/YinYangControllerState";
+import { ComponentTitlePresenter } from "../labels/ComponentTitlePresenter";
+import { ControllerSession } from "../state/ControllerSession";
+import type { ControllerUiCallbacks } from "../state/ControllerUiCallbacks";
+import { EventFieldLifecycleController } from "../force-field/EventFieldLifecycleController";
+import { ActionStackManager } from "../action-stack/ActionStackManager";
+export type KeyEventControllerDeps = {
+    actionStackController: ActionStackController;
+    actionStackManager: ActionStackManager;
+    animateChildrenHide: () => void;
+    buildChildrenOrbitData: () => ChildrenOrbitEntry[];
+    closeChildActionMenu: () => void;
+    coreEventMenuController: CoreEventMenuController;
+    eventFieldLifecycleController: EventFieldLifecycleController;
+    eventFieldRenderer: EventFieldRenderer;
+    forceFieldDetailsPanel: ForceFieldDetailsPanel;
+    getComponentBorderTargetPoint: (componentId: string) => {
+        x: number;
+        y: number;
+    } | null;
+    getCurrentComponentOrUndefined: () => YinYangInternalModel["components"][number] | undefined;
+    navigateToPrereqAction: (actionId: string) => void;
+    prepareForComponentSwitch: (targetComponentId: string) => void;
+    session: ControllerSession;
+    state: YinYangControllerState;
+    titlePresenter: ComponentTitlePresenter;
+    ui: ControllerUiCallbacks;
+    view: IYinYangView;
+};
+/** Événements Clés : menu radial du cœur, aperçu de carte, champ
+ *  d'événement et ajout à la pile. */
+export declare class KeyEventController {
+    private deps;
+    constructor(deps: KeyEventControllerDeps);
+    /**
+     * Appelé par YinYangDrawer quand le petit cercle "œil" du lobe dominant
+     * (yin ou yang, selon Composante.orientation) est cliqué — jamais l'autre
+     * lobe, jamais un satellite (garde déjà appliquée côté YinYangDrawer, même
+     * principe que onDiagramOddArcClicked pour les arcs ODD). Ouvre/ferme le
+     * menu radial des Événements Clés de la facette active.
+     */
+    onCoreEventNucleusClicked(): void;
+    notifyKeyEventMenuState(open: boolean): void;
+    private toggleCoreEventMenu;
+    /**
+     * Fermeture du Champ d'événement : l'Événement Clé en aperçu et les bulles
+     * du menu cœur — chemin unique partagé par la fermeture de facette
+     * (closeCurrentComposante) et par l'exclusivité action/événement
+     * (openActionMenuFromChild). No-op si rien n'est ouvert.
+     *
+     * hide() d'abord pour la rétraction immédiate du souffle (le geste
+     * d'ouverture joué à l'envers — cf. prepareForComponentSwitch),
+     * updateCoreEventMenu() ensuite pour replier les bulles et laisser
+     * refreshTargets constater qu'il n'y a plus rien à dessiner. La carte du
+     * panneau RECHERCHE part avec : elle décrit l'Événement Clé qu'on vient de
+     * retirer du diagramme, et rien ne garantit qu'un autre bloc prenne sa
+     * place (ouvrir un satellite n'affiche qu'un descriptif, pas un bloc).
+     */
+    closeKeyEventField(): void;
+    updateCoreEventMenu(): void;
+    /**
+     * Événements Clés qui pilotent le Champ d'événement en ce moment — source
+     * unique de vérité pour EventFieldLifecycleController (cibles) comme pour
+     * getEventFieldSource (point d'émission).
+     *
+     * Deux régimes, mêmes règles de priorité que le champ de force d'action :
+     * un APERÇU (clic sur une bulle du menu cœur ou sur l'entrée de l'arbre
+     * RECHERCHE) prend toujours la main — c'est le geste que l'utilisateur
+     * vient de faire, quel que soit l'onglet ; sinon, en mode STACK, ce sont
+     * les Événements Clés COCHÉS de la pile qui décident, exactement comme les
+     * actions cochées y décident des champs de force. En mode RECHERCHE sans
+     * aperçu, rien : la pile n'a pas voix au chapitre.
+     *
+     * Le renderer n'a qu'une source (le souffle part d'UN point, voir
+     * EventFieldRenderer), donc on ne renvoie jamais qu'un jeu d'événements
+     * partageant la même : ceux nés de la facette courante partent tous de son
+     * cœur et se cumulent ; à défaut, on retombe sur le plus récent des
+     * événements distants qui atteignent cette facette (mode entrant, source =
+     * l'arc de sa facette d'origine).
+     */
+    getEventFieldKeyEvents(): KeyEventDefinition[];
+    /**
+     * Point d'émission du Champ d'événement : le CŒUR du yin/yang, c'est-à-dire
+     * le disque central du lobe correspondant à l'orientation de la facette
+     * courante — le cœur noir du yang sur une facette Yang, le cœur blanc du
+     * yin sur une facette Yin. Ce n'est PAS le centre géométrique du symbole :
+     * les deux lobes ont des rayons qui varient avec le score, donc le cœur se
+     * déplace le long de l'axe vertical au fil de la partie, d'où la
+     * relecture de la géométrie à chaque frame. Injecté dans
+     * EventFieldLifecycleController (getEventFieldSource), rappelé à chaque
+     * frame de son animation.
+     *
+     * `geometry.yin/yang.centerY` est la position CANONIQUE (pré-rotation) :
+     * pendant une rotation Yin/Yang (AnimationsMngr), le cœur visible se
+     * déplace via un `transform` écrit à même `graphElementGroup` à chaque
+     * frame, sans jamais toucher `geometry`. On lit donc la position réelle
+     * via getLiveLobeCoreCenter plutôt que la géométrie statique, pour que les
+     * anneaux du champ d'événement suivent le cœur qui tourne au lieu de
+     * naître à une origine figée.
+     */
+    getEventFieldSource(): {
+        center: {
+            x: number;
+            y: number;
+        } | null;
+        radius: number;
+    };
+    /**
+     * Résout un point porté par `lobeGroup` (coordonnées locales, ici le
+     * centre canonique du cœur) dans le repère de globalGroup — celui où
+     * EventFieldRenderer dessine (voir EventFieldLifecycleController,
+     * getGlobalGroupNode). Passe par les CTM SVG plutôt que de reparser
+     * l'attribut `transform` (comme getChildRenderedCenter le fait pour une
+     * simple translation) : le transform posé sur graphElementGroup pendant
+     * une rotation combine rotate ET translate, et cette composition suit
+     * fidèlement AnimationsMngr sans dépendre de sa formule exacte — un
+     * changement futur de celle-ci n'a pas besoin d'être répercuté ici.
+     */
+    private getLiveLobeCoreCenter;
+    /**
+     * Rejoue l'aperçu d'un Événement Clé depuis une navigation Recherche
+     * (historique précédent/suivant) — pendant minimal de searchNavigateToAction,
+     * sans mise au point du diagramme (pas de satellite/facette à recentrer,
+     * l'entrée d'arbre dédiée est hors scope pour l'instant).
+     */
+    searchNavigateToKeyEvent(keyEventId: string): void;
+    /**
+     * Rétablit le Champ d'événement d'un Événement Clé DÉJÀ affiché à droite —
+     * pendant de restoreActionDiagramState pour les événements, utilisé au
+     * retour en mode RECHERCHE (voir PanelManager.resyncDiagramToMasterPanel).
+     *
+     * Volontairement plus étroit que previewKeyEvent : ni carte redessinée, ni
+     * notification de navigation (donc pas d'entrée d'historique en double) —
+     * le panneau montre déjà cet événement, c'est le diagramme qui le rattrape.
+     * On garde en revanche l'exclusivité action/événement : les deux champs ne
+     * cohabitent jamais.
+     *
+     * Si la facette courante n'est plus celle de l'événement (l'utilisateur a
+     * navigué ailleurs pendant le mode STACK), on revient d'abord sur sa facette
+     * d'origine — mêmes gestes que searchSetKeyEventMenuOpen : l'aperçu survit
+     * au switch (prepareForComponentSwitch le garde vivant, destination =
+     * origine) et le menu cœur se redéploie à l'arrivée avec sa bulle active.
+     */
+    restoreKeyEventDiagramState(keyEventId: string): void;
+    /**
+     * Dépli/repli du groupe "Événements Clés" depuis la hiérarchie RECHERCHE —
+     * pendant exact du clic sur le cœur du yin/yang (onCoreEventNucleusClicked),
+     * pour que l'arbre et le diagramme montrent le même menu déployé : ouvrir le
+     * groupe déploie les bulles de la facette, le refermer les rétracte (même
+     * règle que le dépli d'un Satellite, qui déploie ses boutons d'Action).
+     *
+     * Le repli passe par closeKeyEventField plutôt que par le toggle : il doit
+     * aussi emporter l'Événement Clé en aperçu (et sa carte), sinon une bulle
+     * validée resterait allumée sous un groupe replié.
+     */
+    searchSetKeyEventMenuOpen(componentIndex: number, open: boolean): void;
+    /** Ouverture idempotente du menu cœur — no-op s'il est déjà déployé (le
+     *  toggle le refermerait). */
+    openCoreEventMenu(): void;
+    /** Seul point de mutation de activeKeyEventId — resynchronise la ligne
+     *  Événement Clé du titre (voir getCurrentSatelliteTitle) à chaque
+     *  changement, exactement comme setActiveChildKey le fait pour le
+     *  satellite. */
+    setActiveKeyEventId(keyEventId: string | null): void;
+    /**
+     * Clic sur une bulle du menu cœur. En STACK : clic sur le libellé de son
+     * item de pile — celui en focus s'il s'agit de cet événement, sinon le
+     * plus récent ; rien s'il n'est pas dans la pile. Ailleurs : aperçu.
+     */
+    onKeyEventBubbleClick(keyEvent: KeyEventDefinition): void;
+    /** Aperçu — 1er clic sur un Événement Clé : affiche sa carte descriptive
+     *  dans le panneau Recherche, ne joue rien (même principe que
+     *  activateActionFromChild côté satellite). */
+    previewKeyEvent(keyEvent: KeyEventDefinition): void;
+    /** Validation — glisser une bulle (menu radial ou arbre RECHERCHE)
+     *  jusqu'à une position précise de la pile (voir startKeyEventDrag, même
+     *  mécanisme que validateActionSelection côté satellite). Sans
+     *  insertAtVisibleIndex, l'item est ajouté au sommet — le menu radial
+     *  reste ouvert, pour enchaîner d'autres choix. */
+    validateKeyEventSelection(keyEvent: KeyEventDefinition, insertAtVisibleIndex?: number | null, entryOrigin?: {
+        x: number;
+        y: number;
+    }): void;
+}

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

@@ -106,12 +106,3 @@ export declare function renderRadialItemLinks<T extends {
     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/ChildrenBuilder.d.ts

@@ -0,0 +1,95 @@
+import { IYinYangView } from "../../../interfaces/IYinYangView";
+import { IYinYangController } from "../../../interfaces/IYinYangController";
+import { IYinYangAppFactory } from "../../../interfaces/IYinYangAppFactory";
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+import { type ActionDefinition } from "../../../data/yasuni_actions";
+import { ChildrenOrbitEntry } from "../utils/childrenOrbit";
+import { YinYangControllerState } from "../state/YinYangControllerState";
+import { StackFocusController } from "../action-stack/StackFocusController";
+import { ComponentTitlePresenter } from "../labels/ComponentTitlePresenter";
+import type { ControllerUiCallbacks } from "../state/ControllerUiCallbacks";
+import { ChildrenOrbitManager } from "../odd/ChildrenOrbitManager";
+export type ChildrenBuilderDeps = {
+    animateChildren: (show: boolean) => Promise<void>;
+    applyChildrenOrbitTransforms: (angleOffset: number, orbitData?: ChildrenOrbitEntry[]) => void;
+    attachBackgroundClickHandler: () => void;
+    attachChildHoverHandler: (childController: IYinYangController) => void;
+    attachChildToggleHandler: (childController: IYinYangController) => void;
+    getChildControllers: () => IYinYangController[];
+    childOddMap: Map<string, {
+        oddId: string;
+        score: number;
+        cuttingIndex: number;
+    }>;
+    childrenOrbitManager: ChildrenOrbitManager;
+    clearChildren: () => void;
+    factory: IYinYangAppFactory;
+    getAllComponents: () => YinYangInternalModel["components"];
+    getCurrentComponent: () => YinYangInternalModel["components"][number] | null;
+    getCurrentComponentOrUndefined: () => YinYangInternalModel["components"][number] | undefined;
+    getKey: () => string;
+    renderOppositeChildrenForceField: (orbitData?: ChildrenOrbitEntry[], angleOffset?: number) => void;
+    getRotationState: () => {
+        clockWise: boolean;
+        durationMs: number;
+        rampMs: number;
+    } | null;
+    setChildrenHiddenState: (hidden: boolean) => void;
+    stackFocus: StackFocusController;
+    startChildrenOrbit: (durationMs: number) => void;
+    state: YinYangControllerState;
+    titlePresenter: ComponentTitlePresenter;
+    ui: ControllerUiCallbacks;
+    view: IYinYangView;
+};
+/** Création des satellites (contrôleurs enfants) d'une facette, mise à
+ *  l'échelle pour tenir dans le cercle, et actions proposées par satellite. */
+export declare class ChildrenBuilder {
+    private deps;
+    constructor(deps: ChildrenBuilderDeps);
+    /**
+     * Creates child instances of the YinYang pattern using the model's data.
+     * Each child is generated based on the small circle data.
+     */
+    createYinYangChildren(): void;
+    /** Both distance and size are fixed relative to the facette's uniform
+     *  baseline radius, independent of any satellite's own weight-scaled
+     *  radius — mirrors ChildActionMenuController's action cluster geometry. */
+    private getChildActionClusterReach;
+    /** Décalage constant appliqué au poids ET à sa moyenne avant de calculer le
+     *  ratio de taille d'un satellite (voir weightToSizeRatio) : resserre la
+     *  fourchette de tailles (poids min moins minuscule, poids max un peu
+     *  moins dominant) sans changer la taille d'un satellite au poids moyen
+     *  exact (ratio toujours 1 dans ce cas), et sans dépendre du poids moyen
+     *  de la fratrie pour l'ampleur du resserrement. */
+    private static readonly WEIGHT_SIZE_FLOOR_OFFSET;
+    /** Ratio de taille d'un satellite (rayon relatif à la baseline uniforme de
+     *  sa facette) à partir de son poids et du poids moyen de sa fratrie —
+     *  voir WEIGHT_SIZE_FLOOR_OFFSET pour le resserrement. */
+    private static weightToSizeRatio;
+    /** Ratio of a component's heaviest satellite radius to its own uniform
+     *  baseline radius. Mirrors the per-cutting weight-based scaling applied
+     *  in createYinYangChildren(). */
+    private getMaxWeightRatio;
+    /** The container-fit shrink ratio only depends on borderOuterRadius/
+     *  smallCircleRadius/distanceFromChild, which are fixed for the whole
+     *  session once this top-level view is first initialized (they don't get
+     *  recomputed on facette switch) — so this is computed once (on the worst
+     *  case weight ratio across every facette) and cached. That's what keeps
+     *  the whole diagram's size from visibly changing every time the user
+     *  switches facette. */
+    private cachedGlobalFitShrinkRatio?;
+    private computeGlobalFitShrinkRatio;
+    applyChildrenFitScale(): void;
+    /**
+     * Retourne les actions applicables au cutting associé à `childKey`,
+     * en consultant `activeComposantes` via `actionMap` (lookup O(1)).
+     *
+     * Les actions adverses vivent sous le même satellite (l'invariant "une
+     * action vit sous un satellite" tient) mais ne sont proposées au joueur
+     * qu'en mode adverse (outil de debug, voir adverseMode.ts), où elles
+     * remplacent les actions ordinaires — d'où le filtre "mode" par défaut.
+     * Hors de ce mode, c'est le système qui les place lui-même dans la pile.
+     */
+    getActionsForChild(childKey: string, filter?: "mode" | "playable" | "adverse" | "all"): ActionDefinition[];
+}