@micheeeeel/yinyangapp 2.5.1 → 2.6.0

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

@@ -0,0 +1,139 @@
+import { IYinYangView } from "../../../interfaces/IYinYangView";
+import { IYinYangController } from "../../../interfaces/IYinYangController";
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+import { type ComboResult } from "../../../data/combo-engine";
+import { ChildrenOrbitEntry } from "../utils/childrenOrbit";
+import { SequentialActionProjectionInput } from "../actions/ActionProjectionService";
+import { ActionStackController, ActionStackItem } from "../action-stack/ActionStackController";
+import { ForceFieldDetailsPanel } from "./ForceFieldDetailsPanel";
+import { YinYangControllerState } from "../state/YinYangControllerState";
+import { DiagramNavigator } from "../navigation/DiagramNavigator";
+import { ComponentTitlePresenter } from "../labels/ComponentTitlePresenter";
+import { PropagationAnimator } from "./PropagationAnimator";
+import { ControllerSession } from "../state/ControllerSession";
+import type { ControllerUiCallbacks } from "../state/ControllerUiCallbacks";
+import { ForceFieldComputationService } from "./ForceFieldComputationService";
+import { ActionStackManager } from "../action-stack/ActionStackManager";
+import type { CumulativeBlock } from "../types";
+export type ForceFieldDetailsPresenterDeps = {
+    actionStackController: ActionStackController;
+    actionStackManager: ActionStackManager;
+    applyOddStateForCutting: (oddId: string) => void;
+    buildChildrenOrbitData: () => ChildrenOrbitEntry[];
+    buildProjectionActionsFromStackItems: (items: ActionStackItem[]) => SequentialActionProjectionInput[];
+    getChildControllers: () => IYinYangController[];
+    childOddMap: Map<string, {
+        oddId: string;
+        score: number;
+        cuttingIndex: number;
+    }>;
+    forceFieldComputationService: ForceFieldComputationService;
+    forceFieldDetailsPanel: ForceFieldDetailsPanel;
+    getAllComponents: () => YinYangInternalModel["components"];
+    getCurrentComponent: () => YinYangInternalModel["components"][number] | null;
+    getCurrentComponentOrUndefined: () => YinYangInternalModel["components"][number] | undefined;
+    navigator: DiagramNavigator;
+    propagationAnimator: PropagationAnimator;
+    session: ControllerSession;
+    setActiveChild: (childKey: string) => void;
+    state: YinYangControllerState;
+    titlePresenter: ComponentTitlePresenter;
+    ui: ControllerUiCallbacks;
+    updateChildActionMenu: (orbitData: ChildrenOrbitEntry[]) => void;
+    view: IYinYangView;
+};
+/** Contenu du panneau de détails du champ de force : action directe, action
+ *  propagée, vue cumulative de la pile (mode STACK) et blocs d'Événements Clés. */
+export declare class ForceFieldDetailsPresenter {
+    private deps;
+    constructor(deps: ForceFieldDetailsPresenterDeps);
+    /**
+     * Construit le bloc d'action directe pour un emplacement connu (compId/oddId/cutIdx/actionId)
+     * sans naviguer le diagramme, et fire le callback avec (compId, oddId, cutIdx, actionId, html, attachHandlers).
+     * Utilisé par les panneaux contextuels pour afficher le bloc d'une action cliquée dans leur arbre.
+     */
+    /**
+     * Déclenche l'affichage du bloc de propagation dans un panneau contextuel lorsque
+     * l'utilisateur clique sur un cutting dans l'arbre de ce panneau.
+     * Retourne true si le cutting est effectivement impacté par l'action active (bloc affiché),
+     * false sinon (aucun changement).
+     */
+    showPropagationForContextCutting(componentId: string, oddId: string, cuttingIndex: number): boolean;
+    buildDirectActionBlockForContext(compId: string, oddId: string, cutIdx: number, actionId: string, onReady: (compId: string, oddId: string, cutIdx: number, actionId: string, html: string, attachHandlers: (container: HTMLElement) => void) => void): void;
+    clearGhostDetails(): void;
+    renderGhostDetailsForActiveAction(): void;
+    clearForceFieldDetails(): void;
+    renderActionPropagationTable(): void;
+    /**
+     * Calcule les ComboResult pour une action donnée.
+     * Priorité : résultats pré-calculés du stack item → évaluation à la volée.
+     * Utilisé par le panneau principal et tous les panneaux contextuels.
+     */
+    computeComboResultsForAction(actionId: string): ComboResult[] | undefined;
+    renderSourceActionDetailsForCurrentSource(opts?: {
+        deltaOverride?: number;
+        comboResults?: ComboResult[];
+    }): void;
+    private _mergeAllComponentLinkDetails;
+    /**
+     * Pour chaque ligne de la composante courante qui vise une autre
+     * composante, les sauts qu'elle produit dans la composante cible. Ces
+     * lignes ne vivent dans l'état de la cible qu'après bascule ; on
+     * les calcule ici avec la même fonction que restoreIncomingForceFieldContext
+     * (buildIncomingContinuationHops, PROP-03), donc avec le même résultat.
+     */
+    private _computeCrossComponentCascadeRows;
+    renderForceFieldDetails(linkIndex: number): void;
+    private getActiveActionMeta;
+    /**
+     * Per active stack item sourced from the CURRENT component: its marginal
+     * contribution (state units, 0..100) to (oddId, cuttingId), and its own
+     * detailed propagation edges — both produced by the real sequential
+     * simulation (projectGhostStateForActionSequence), the same one that
+     * drives the diagram's displayed Δ.
+     *
+     * - marginalDeltaAtFocus: summing this across items equals the diagram's Δ
+     *   exactly, by construction (telescoping sum over the fractional
+     *   accumulator). Used as the authoritative block total.
+     * - detailPool: this item's OWN propagation edges (absorption/gap/cascade),
+     *   for the whole resolution — including what it carries on into other
+     *   facets — with stable identities (edgeId / parentEdgeId),
+     *   from the exact same single-pass computation (computeActionPropagationDetails,
+     *   via onStep) that produced marginalDeltaAtFocus — not a second, separately
+     *   re-run propagation — against the exact rolled-forward state this item
+     *   saw at its point in the stack, not the pristine base state. Used so the
+     *   panel's descriptive breakdown badges match the authoritative total
+     *   instead of an isolated estimate.
+     *
+     * Items sourced from a DIFFERENT component are absent from the map: they
+     * don't participate in this component's rolling simulation (their effect
+     * is merged separately via the cross-component incoming-links path).
+     * Callers must fall back to the isolated per-source estimate for those.
+     */
+    private computeSequentialStackContributionsAtFocus;
+    /**
+     * Blocs "keyEvent" pour la vue cumulative : un Événement Clé actif (coché
+     * dans la pile) dont la Facette d'origine (originComposanteId) correspond à
+     * `component` — indépendamment du satellite précis sélectionné, et même si
+     * aucune de ses actions ciblées n'est jouée (voir isKeyEventCurrentlyActive
+     * pour le seul état visuel actif/inactif). Réutilisé par
+     * renderCumulativeDetailsForCutting (satellite sélectionné) et par les
+     * appelants de renderComposanteInfo (Facette sélectionnée, aucun satellite).
+     */
+    buildKeyEventBlocksForComponent(component: {
+        id: string;
+    }): CumulativeBlock[];
+    renderCumulativeDetailsForCutting(oddId: string, cuttingId: number | undefined): boolean;
+    /** Une action active de cette Facette a-t-elle pour source le satellite
+     *  (oddId, cuttingId) ? Même résolution que le bloc "source" de
+     *  renderCumulativeDetailsForCutting (isDirectMatch). */
+    private hasActiveActionSourcedAt;
+    /**
+     * Arrivées d'un ensemble de lignes (une ou plusieurs résolutions d'une même
+     * action) sur le satellite cible, et leurs ancêtres dans l'arbre des
+     * arrivées : tout ce qui, dans ces lignes, mène à la cible — quels que
+     * soient le nombre de sauts, d'ODD ou de facettes traversés, les
+     * convergences ou les retours cycliques.
+     */
+    private collectDetailRowsForTarget;
+}

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

@@ -10,18 +10,10 @@ export declare class ForceFieldRenderer {
     private forceFieldDefs;
     private forceFieldLayers;
     private readonly gradientPrefix;
-    /** Active pulse overrides: linkIndex → { startMs, durationMs }. Cleared on arc end. */
-    private readonly _pulsedLinks;
     /** 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;
-    /**
-     * Temporarily boost the visual intensity of a force-field link.
-     * Opacity and aura stroke-width are amplified with a sin envelope over `durationMs`.
-     * Called by YinYangController while the propagation arc travels the matching segment.
-     */
-    pulseLink(linkIndex: number, durationMs: number): void;
     /** Horodatage du dernier updateVisual — updateVisual ne reçoit pas de Δt,
      *  on le dérive ici pour le lissage de l'emphase. */
     private _lastVisualNow;

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

@@ -0,0 +1,53 @@
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+import { ChildrenOrbitEntry } from "../utils/childrenOrbit";
+import { SequentialActionProjectionInput } from "../actions/ActionProjectionService";
+import { ActionStackItem } from "../action-stack/ActionStackController";
+import { ForceFieldLinkDetail } from "./types";
+import { YinYangControllerState } from "../state/YinYangControllerState";
+import { ComponentTitlePresenter } from "../labels/ComponentTitlePresenter";
+import { ControllerSession } from "../state/ControllerSession";
+import { ForceFieldComputationService } from "./ForceFieldComputationService";
+export type IncomingForceFieldServiceDeps = {
+    applyProjectedGhostFromStackItems: (items: ActionStackItem[]) => void;
+    buildChildrenOrbitData: () => ChildrenOrbitEntry[];
+    buildForceFieldSourceIndicesFromStackItems: (items: ActionStackItem[]) => number[];
+    buildProjectionActionsFromStackItems: (items: ActionStackItem[]) => SequentialActionProjectionInput[];
+    childOddMap: Map<string, {
+        oddId: string;
+        score: number;
+        cuttingIndex: number;
+    }>;
+    forceFieldComputationService: ForceFieldComputationService;
+    getAllComponents: () => YinYangInternalModel["components"];
+    getCurrentComponentOrUndefined: () => YinYangInternalModel["components"][number] | undefined;
+    renderOppositeChildrenForceField: (orbitData?: ChildrenOrbitEntry[], angleOffset?: number) => void;
+    restoreIncomingForceFieldContext: (context: {
+        type: "incoming";
+        sourceComponentId: string;
+        linksByOddId: Map<string, {
+            toOddId: string;
+            thickness: number;
+            potentialGain: number;
+            detail: ForceFieldLinkDetail;
+            sourceOriginKey?: string;
+        }>;
+    }) => void;
+    session: ControllerSession;
+    state: YinYangControllerState;
+    titlePresenter: ComponentTitlePresenter;
+};
+/** Recalcule le champ de force entrant d'une facette à partir des éléments
+ *  de pile actifs (liens issus d'autres facettes). */
+export declare class IncomingForceFieldService {
+    private deps;
+    constructor(deps: IncomingForceFieldServiceDeps);
+    /**
+     * Recomputes the incoming force-field view for `currentComponentId` based on
+     * the subset of source actions provided by `items`, using the source links saved
+     * when the user originally switched away from the source component.
+     * Returns true if matching cross-component links were found and the view was
+     * updated; returns false if no links target the current component (caller should
+     * fall back to switching to the source component instead).
+     */
+    recomputeIncomingForceFieldForItems(items: ActionStackItem[], sourceComponentId: string, currentComponentId: string): boolean;
+}

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

@@ -0,0 +1,56 @@
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+import { ActionStackController, ActionStackItem } from "../action-stack/ActionStackController";
+import { YinYangControllerState } from "../state/YinYangControllerState";
+import type { ForceFieldLinkDetail } from "./types";
+import type { PropagationCometPlayer } from "./propagation-viz/PropagationCometPlayer";
+export type PropagationAnimatorDeps = {
+    stackItemSourceOriginKey: (item: ActionStackItem) => string | null;
+    actionStackController: ActionStackController;
+    getCurrentComponentOrUndefined: () => YinYangInternalModel["components"][number] | undefined;
+    resolveFocusBubbleStub: () => {
+        sourceChildIndex: number;
+        center: {
+            x: number;
+            y: number;
+        };
+    } | null;
+    /** Arrivées de la résolution d'un item dont le bloc est affiché (celles
+     *  de ses listes Source / Bilan). */
+    getStackItemResolutionPool: (stackItemId: string) => readonly ForceFieldLinkDetail[] | undefined;
+    /** Lecteur dédié à la boucle (réglages propagationCometConfig). */
+    cometPlayer: PropagationCometPlayer;
+    state: YinYangControllerState;
+};
+/**
+ * Boucle de l'action en focus : tant qu'une action est en focus, sa
+ * propagation est rejouée en boucle, séparée par une pause réglable — c'est
+ * ce qui, dans un diagramme saturé, désigne sans ambiguïté les champs du
+ * bloc sélectionné.
+ *
+ * Trajets et rendu sont ceux de la comète des listes Source / Bilan
+ * (propagationVizModel.resolutionCometTrees, PropagationCometPlayer) : la
+ * passe suit les arrivées réelles du moteur, depuis la cible de l'action
+ * (ou depuis l'arc de la facette d'où arrive sa suite) jusqu'au dernier
+ * satellite impacté, en se divisant à chaque embranchement. Une passe est
+ * sautée (et re-tentée peu après) quand un aperçu par survol porte sur une
+ * autre action, ou hors mode STACK.
+ */
+export declare class PropagationAnimator {
+    private deps;
+    constructor(deps: PropagationAnimatorDeps);
+    private _focusLoopTimer;
+    /** Pause entre deux passes (propagationCometConfig.loopGapMs, panneau
+     *  Debug). Un timer en attente est reposé avec la nouvelle valeur pour que
+     *  le réglage se sente tout de suite. */
+    setFocusPropagationLoopGapMs(ms: number): void;
+    restartFocusPropagationLoop(): void;
+    private stopFocusPropagationLoop;
+    private _runFocusPropagationLoopPass;
+    /** Joue une passe pour l'item ; retourne sa durée (0 si rien à jouer). */
+    private _playFocusedItem;
+    /** Arrivées de la résolution de l'item : celles de son bloc dans le
+     *  panneau quand il est affiché (mêmes trajets que ses listes), sinon
+     *  celles de ses champs de force dans l'état du diagramme (même filtre
+     *  que ForceFieldDetailsPresenter pour le pool d'un bloc). */
+    private _resolutionPool;
+}

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

@@ -0,0 +1,28 @@
+import type { PropagatedActionEdge } from "../../../utils/actionPropagation";
+import type { ForceFieldLinkDetail } from "./types";
+export declare function edgeIdOf(resolutionId: string, index: number): string;
+/** Résolution d'un champ de force calculé depuis un satellite source. */
+export declare function sourceResolutionId(componentId: string, oddId: string, cuttingId: number | undefined): string;
+/** Résolution isolée d'un élément de pile joué depuis une autre facette que
+ *  celle affichée (ses arrivées dans cette facette, puis leur suite). */
+export declare function remoteResolutionId(stackItemId: string): string;
+/** Résolution d'un bloc de la pile (simulation séquentielle). */
+export declare function stackResolutionId(stackItemId: string): string;
+/**
+ * Lignes d'affichage d'une résolution complète. Les identifiants sont fixés
+ * sur les index d'origine AVANT le filtre `keep` : une ligne gardée dont le
+ * parent est écarté conserve son `parentEdgeId` (elle devient une racine
+ * pour cet affichage, sans changer d'identité).
+ */
+export declare function detailsFromResolution(edges: readonly PropagatedActionEdge[], resolutionId: string, keep?: (edge: PropagatedActionEdge) => boolean): ForceFieldLinkDetail[];
+/**
+ * Lignes d'une suite calculée à partir d'une arrivée (`entry`), par exemple
+ * dans la facette cible d'une arête inter-facettes : même résolution que
+ * l'arrivée, identifiants dérivés du sien ; les sorties du satellite
+ * d'arrivée ont l'arrivée pour parent.
+ */
+export declare function detailsFromContinuation(edges: readonly PropagatedActionEdge[], entry: Pick<ForceFieldLinkDetail, "resolutionId" | "edgeId">): ForceFieldLinkDetail[];
+/** Arêtes d'une résolution visibles depuis une facette : celles qui en
+ *  partent ou y arrivent. Les sauts entièrement dans une autre facette en
+ *  sont la suite et s'affichent depuis cette facette. */
+export declare function isVisibleFromComponent(edge: Pick<PropagatedActionEdge, "fromComponentId" | "toComponentId">, componentId: string): boolean;

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

@@ -0,0 +1,22 @@
+import { YinYangComponentNode } from "../../../interfaces/IYinYangInternalModel";
+import { PropagatedActionEdge } from "../../../utils/actionPropagation";
+import { ForceFieldLinkDetail } from "./types";
+/** Saut d'une suite entrante, prêt pour l'affichage. */
+export type IncomingContinuationHop = {
+    edge: PropagatedActionEdge;
+    detail: ForceFieldLinkDetail;
+    /** Profondeur dans l'arbre des arrivées : 0 pour les sorties du satellite
+     *  d'arrivée, parent + 1 ensuite. */
+    chainDepth: number;
+};
+/**
+ * Suite, dans la composante cible, d'une arête venue d'une autre composante.
+ * Le calcul est celui du moteur (computeIncomingLocalContinuation, mêmes
+ * sauts que la résolution complète dans cette composante) ; cette fonction ne
+ * fait que le traduire en lignes de détail, rattachées à l'arrivée `incoming`
+ * (même résolution, `parentEdgeId` pour les sorties de son satellite).
+ * Partagée par la vue de la composante cible (restoreIncomingForceFieldContext)
+ * et par le panneau vu depuis la source (_computeCrossComponentCascadeRows),
+ * qui affichent donc les mêmes sauts.
+ */
+export declare function buildIncomingContinuationHops(targetComponent: YinYangComponentNode, incoming: ForceFieldLinkDetail): IncomingContinuationHop[];

package/dist/types/components/controller/force-field/propagation-viz/PropagationCometPlayer.d.ts

@@ -0,0 +1,60 @@
+import type { IYinYangController } from "../../../../interfaces/IYinYangController";
+import type { YinYangInternalModel } from "../../../../interfaces/IYinYangInternalModel";
+import { type PropagationCometVizConfig } from "../../../../config/propagationCometVizConfig";
+import type { CometNode } from "./propagationVizModel";
+export type PropagationCometPlayerDeps = {
+    getCurrentComponent: () => YinYangInternalModel["components"][number] | null;
+    getChildControllers: () => IYinYangController[];
+    childOddMap: Map<string, {
+        oddId: string;
+        cuttingIndex: number;
+    }>;
+    getChildRenderedCenter: (controller: IYinYangController) => {
+        x: number;
+        y: number;
+    } | null;
+    getComponentBorderTargetPoint: (componentId: string) => {
+        x: number;
+        y: number;
+    } | null;
+    getGlobalGroup: () => SVGGElement | null;
+    /** Rayon de repli d'un satellite, et largeur de l'arc de bordure. */
+    getSatelliteRadius: () => number;
+    getBorderArcWidth: () => number;
+    /** Réglages lus à chaque lecture (par défaut : comète des listes). */
+    config?: PropagationCometVizConfig;
+};
+export type CometPlayOptions = {
+    /** Couleur de l'action du bloc, utilisée si le réglage le demande. */
+    blockColor?: string;
+    /** Point de départ avant la racine (bulle de l'action), pour le premier
+     *  arbre seulement. */
+    origin?: {
+        x: number;
+        y: number;
+    };
+};
+export declare class PropagationCometPlayer {
+    private deps;
+    private run;
+    constructor(deps: PropagationCometPlayerDeps);
+    private get cfg();
+    /** Joue un ou plusieurs arbres (rafale). Retourne la durée de la lecture
+     *  (ms, dernier anneau éteint), 0 si rien n'est résoluble sur le
+     *  diagramme. */
+    play(trees: CometNode[], options?: CometPlayOptions): number;
+    /** Efface toute lecture en cours. */
+    stop(): void;
+    private resolvePoint;
+    /** Aplatit l'arbre en résolvant les positions et les instants d'arrivée.
+     *  Une branche dont un satellite est introuvable s'arrête au précédent.
+     *  `origin` : point de départ placé avant la racine. */
+    private flatten;
+    /** Position de la tête qui mène au nœud `index`, à l'instant `t` (remonte
+     *  la lignée quand `t` précède l'arrivée sur le parent : sert à la queue). */
+    private positionAt;
+    private renderFlight;
+    private createHead;
+    /** Anneau qui s'élargit en s'éteignant autour d'un satellite atteint. */
+    private drawRing;
+}

package/dist/types/components/controller/force-field/propagation-viz/propagationVizLists.d.ts

@@ -0,0 +1,51 @@
+import type { ForceFieldLinkDetail } from "../types";
+import { type CometNode, type VizBlockKind, type VizSatellite } from "./propagationVizModel";
+import type { CometPlayOptions } from "./PropagationCometPlayer";
+export type CometPlayFn = (trees: CometNode[], options: CometPlayOptions) => void;
+export type PropagationVizListsOptions = {
+    /** Nom affiché d'un satellite (facette comprise). */
+    nameOf: (satellite: VizSatellite) => string;
+    /** Réticule de navigation d'une ligne (vide si pas de navigation). */
+    navIconHtml: (satellite: VizSatellite, list: "source" | "bilan") => string;
+    /** Lecteur de comète ; absent → listes non cliquables. */
+    play?: CometPlayFn;
+};
+export declare class PropagationVizLists {
+    private readonly opts;
+    private readonly actions;
+    constructor(opts: PropagationVizListsOptions);
+    /**
+     * Liste de la carte Bilan : cibles du prochain saut depuis `satellite`.
+     * Ligne → comète de X vers la cible puis toute sa suite ; en-tête →
+     * toutes les lignes en rafale.
+     */
+    bilanListHtml(params: {
+        pool: readonly ForceFieldLinkDetail[];
+        satellite: VizSatellite;
+        kind: VizBlockKind;
+        scale?: number;
+        blockColor?: string;
+    }): {
+        html: string;
+        count: number;
+    };
+    /**
+     * Liste de la carte Source : satellites dont les arrivées forment le
+     * budget de `satellite`. Ligne → comète du satellite cliqué jusqu'à X ;
+     * en-tête → toutes les lignes en rafale.
+     */
+    sourceListHtml(params: {
+        pool: readonly ForceFieldLinkDetail[];
+        satellite: VizSatellite;
+        blockColor?: string;
+        /** Libellé d'une provenance (ex. nom de l'action pour son satellite). */
+        labelOf?: (satellite: VizSatellite) => string | undefined;
+    }): {
+        html: string;
+        count: number;
+    };
+    /** Branche les lectures de ce rendu sur `container` (HTML déjà injecté). */
+    attach(container: HTMLElement): void;
+    private register;
+    private listHtml;
+}

package/dist/types/components/controller/force-field/propagation-viz/propagationVizModel.d.ts

@@ -0,0 +1,60 @@
+import type { PropagationScope } from "../../../../interfaces/IPropagationGraph";
+import type { ForceFieldLinkDetail } from "../types";
+export type VizSatellite = {
+    componentId: string;
+    oddId: string;
+    cuttingId: number;
+};
+export type VizBlockKind = "direct" | "propagation";
+/** Une ligne d'une liste Source ou Bilan : un satellite, la somme des deltas
+ *  bruts des sauts qui le relient à X (voir rawDeltaOf), ces sauts eux-mêmes
+ *  et leurs rationales (non vides, sans doublon, dans l'ordre des sauts). */
+export type VizListEntry = {
+    satellite: VizSatellite;
+    scope: PropagationScope;
+    delta: number;
+    edgeIds: string[];
+    rationales: string[];
+};
+/** Arbre de trajet d'une comète : le satellite de départ, puis chaque
+ *  satellite atteint, embranchements compris. */
+export type CometNode = {
+    satellite: VizSatellite;
+    children: CometNode[];
+};
+export declare function vizSatelliteKey(s: VizSatellite): string;
+/** Arrivées sur X (sauts qui y aboutissent). */
+export declare function arrivalsAt(pool: readonly ForceFieldLinkDetail[], satellite: VizSatellite): ForceFieldLinkDetail[];
+/** Sauts qui partent de X pour ce bloc (voir l'en-tête du fichier). */
+export declare function departuresFrom(pool: readonly ForceFieldLinkDetail[], satellite: VizSatellite, kind: VizBlockKind): ForceFieldLinkDetail[];
+/** Delta brut d'un saut : budget × poids, avant absorption et gap. C'est ce
+ *  qu'affichent les listes ; l'écart à l'effectif est porté par les cartes
+ *  de modificateurs. */
+export declare const rawDeltaOf: (row: Pick<ForceFieldLinkDetail, "baseDelta" | "weight">) => number;
+/**
+ * Carte Bilan : satellites cibles du prochain saut depuis X, chacun avec la
+ * part du delta brut qu'il reçoit. `scale` ramène les deltas du pool à
+ * ceux de l'action quand le pool a été calculé avec un autre delta (aperçu).
+ */
+export declare function bilanTargets(pool: readonly ForceFieldLinkDetail[], satellite: VizSatellite, kind: VizBlockKind, scale?: number): VizListEntry[];
+/** Carte Source : satellites dont les arrivées sur X forment son budget. */
+export declare function sourceContributors(pool: readonly ForceFieldLinkDetail[], satellite: VizSatellite): VizListEntry[];
+/**
+ * Trajet de la comète pour une ligne du Bilan : de X vers la cible cliquée,
+ * puis toute la suite réellement propagée depuis ces arrivées, en se
+ * divisant à chaque embranchement, jusqu'au dernier satellite impacté.
+ */
+export declare function bilanCometTree(pool: readonly ForceFieldLinkDetail[], satellite: VizSatellite, entry: Pick<VizListEntry, "satellite" | "edgeIds">): CometNode;
+/**
+ * Trajets de toute une résolution (boucle de l'action en focus) : un arbre
+ * par satellite de départ, c'est-à-dire par satellite d'où partent des sauts
+ * dont le parent n'est pas dans le pool. Pour le pool d'un bloc d'action
+ * directe, c'est un seul arbre depuis X, dont les branches sont exactement
+ * les trajets des lignes de son Bilan (mêmes règles que bilanCometTree).
+ */
+export declare function resolutionCometTrees(pool: readonly ForceFieldLinkDetail[]): CometNode[];
+/** Trajet de la comète pour une ligne de la Source : du satellite cliqué
+ *  jusqu'à X, sans poursuite au-delà. */
+export declare function sourceCometTree(satellite: VizSatellite, entry: Pick<VizListEntry, "satellite">): CometNode;
+/** Satellites d'un arbre, racine comprise, dans l'ordre du parcours. */
+export declare function cometTreeSatellites(tree: CometNode): VizSatellite[];

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

@@ -0,0 +1,32 @@
+import type { ForceFieldLinkDetail } from "./types";
+type Row = ForceFieldLinkDetail;
+/** Satellite d'arrivée d'une ligne, facette comprise. */
+export declare function targetSatelliteKey(row: Pick<Row, "toComponentId" | "toOddId" | "toCuttingId">): string;
+/** Satellite de départ d'une ligne, facette comprise. */
+export declare function sourceSatelliteKey(row: Pick<Row, "fromComponentId" | "fromOddId" | "fromCuttingId">): string;
+export declare class PropagationTree {
+    readonly rows: readonly Row[];
+    private readonly byId;
+    private readonly children;
+    private readonly order;
+    constructor(rows: readonly Row[]);
+    get size(): number;
+    has(row: Row): boolean;
+    parentOf(row: Row): Row | undefined;
+    childrenOf(row: Row): Row[];
+    /** Racines, dans l'ordre des lignes. */
+    roots(): Row[];
+    depthOf(row: Row): number;
+    /** Chemin de la racine jusqu'à `row` inclus. */
+    pathTo(row: Row): Row[];
+    /** Ancêtres d'un ensemble de lignes, dédupliqués, racines d'abord (par
+     *  profondeur, puis ordre des lignes). Les lignes de `rows` elles-mêmes en
+     *  sont exclues. */
+    ancestorsOf(rows: readonly Row[]): Row[];
+    /** Descendants d'un ensemble de lignes, en largeur, dédupliqués ; les
+     *  lignes de `rows` elles-mêmes en sont exclues. */
+    descendantsOf(rows: readonly Row[]): Row[];
+    /** Lignes triées par profondeur puis ordre d'origine. */
+    sortTopDown(rows: readonly Row[]): Row[];
+}
+export {};

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

@@ -0,0 +1,79 @@
+import type { ShieldAbsorption } from "../actions/ActionProjectionService";
+/** Un bouclier posé par une action de la pile sur son satellite source. */
+export interface ShieldGrant {
+    componentId?: string;
+    oddId: string;
+    cuttingIndex: number;
+    shield: number;
+    /** Nom de l'action qui l'a créé — l'origine affichée au joueur. */
+    label?: string;
+    /** Item de pile qui l'a créé — cible du lien de la carte Bouclier. */
+    stackItemId?: string;
+}
+export interface ActiveShield {
+    value: number;
+    originLabel?: string;
+    originStackItemId?: string;
+}
+export interface ShieldTargetRef {
+    componentId?: string;
+    oddId: string;
+    cuttingIndex: number;
+}
+/**
+ * Bouclier actif sur `target` après les `grants` donnés (ordre de pile) :
+ * un seul par satellite, le plus fort ; à valeur égale, le premier posé
+ * reste l'origine (un bouclier plus faible ou égal ne remplace jamais).
+ */
+export declare function resolveActiveShield(grants: ShieldGrant[], target: ShieldTargetRef): ActiveShield | undefined;
+export type ShieldVerdict = "creates" | "replaces" | "ignored" | "unchanged";
+/**
+ * Ce que ferait un bouclier `created` face au bouclier `active` déjà en
+ * place sur le même satellite — undefined si rien n'est créé.
+ */
+export declare function shieldVerdict(active: number | undefined, created: number | undefined): ShieldVerdict | undefined;
+/** « Bouclier actif : −X sur chaque menace directe ou propagée jusqu'à la fin de la mission. » */
+export declare function activeShieldSentence(active: ActiveShield): string;
+/** Phrase du bouclier qu'une stabilisation prévisualisée créerait, avec le
+ *  résultat face au bouclier actif. */
+export declare function createdShieldSentence(created: number, active: number | undefined): string;
+/** Décomposition d'une résolution négative sur un satellite protégé. */
+export interface AbsorptionBreakdown {
+    /** Delta adverse direct (≤ 0) — 0 si la menace ne vise pas ce satellite. */
+    direct: number;
+    /** Total propagé (≤ 0), tous chemins confondus. */
+    propagated: number;
+    /** Total négatif agrégé avant bouclier = direct + propagé. */
+    aggregated: number;
+    shield: number;
+    /** Points effectivement absorbés (≥ 0), une seule fois sur l'agrégé. */
+    absorbed: number;
+    /** Delta finalement appliqué (≤ 0), jamais un bonus. */
+    applied: number;
+    /** true si le bouclier a tout absorbé : le delta appliqué est 0, pas un gain. */
+    boundedToZero: boolean;
+}
+/**
+ * @param absorption  réduction rapportée par la projection pour ce satellite
+ * @param directDelta delta effectif de l'action si elle vise ce satellite,
+ *                    0 sinon — permet de séparer direct et propagé.
+ */
+export declare function buildAbsorptionBreakdown(absorption: Pick<ShieldAbsorption, "shield" | "aggregated" | "applied">, directDelta: number): AbsorptionBreakdown;
+/** Lignes courtes du journal de résolution, dans l'ordre du pipeline. */
+export declare function absorptionSentences(b: AbsorptionBreakdown): string[];
+/** Carte « Bouclier » d'un bloc de l'ANALYSE : maillon additif entre les
+ *  modificateurs et le Bilan — badge = points absorbés, si bien que
+ *  delta avant bouclier + badge = Bilan. */
+export interface ShieldCardViewModel {
+    /** Points absorbés (> 0), affichés en badge positif. */
+    absorbed: number;
+    shield: number;
+    originLabel?: string;
+    originStackItemId?: string;
+    /** Lignes de calcul, dans l'ordre du pipeline. */
+    lines: string[];
+    boundedToZero: boolean;
+}
+/** undefined quand le bouclier n'a rien réduit dans ce bloc (contribution
+ *  positive, ou pas de bouclier) : pas de carte, la note du Bilan suffit. */
+export declare function shieldCardViewModel(absorption: AbsorptionBreakdown | undefined, active?: ActiveShield): ShieldCardViewModel | undefined;