@micheeeeel/yinyangapp 1.0.6 → 2.0.0

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

@@ -0,0 +1,149 @@
+import { type ActionStackItem } from "./ActionStackState";
+export type { ActionStackItem };
+type Point = {
+    x: number;
+    y: number;
+};
+export declare class ActionStackController {
+    private readonly state;
+    private readonly drag;
+    private actionStackGroup;
+    private stackLayoutMetrics;
+    private actionStackLabelFontScale;
+    private historyButtonScale;
+    private fallingStackItemIds;
+    private keyboardListenersBound;
+    private _linkedHoverId;
+    private _onBlockHighlightCb?;
+    private _onSatelliteHighlightCb?;
+    private activeComboHighlight;
+    /** Highlight temporaire (tag click) — remplacé par activeComboHighlight si actif. */
+    private flashComboHighlight;
+    private flashComboTimeout;
+    private resizeObserver;
+    private _cachedNumVisibleSlots;
+    private onLocateInSearch?;
+    private onSelectSatellite?;
+    setOnLocateInSearch(cb: (componentId: string, oddId: string, cuttingIndex: number, actionId: string, kind: "action" | "keyEvent") => void): void;
+    setOnSelectSatellite(cb: (componentId: string, oddId: string, cuttingIndex: number, stackItemId: string) => void): void;
+    constructor(onActiveItemsChange: (activeItems: ActionStackItem[]) => void, onClear?: () => void);
+    setLabelFontScale(scale: number): void;
+    setHistoryButtonScale(scale: number): void;
+    /**
+     * Surligne dans le stack les actions impliquées dans le combo actuellement affiché.
+     * Affiche un crochet coloré sur la droite qui délimite la fenêtre temporelle,
+     * met en valeur les actions requises (glow) et estompe les autres dans la fenêtre.
+     */
+    highlightComboContext(params: {
+        requires: string[];
+        withinLastN?: number;
+        type: string;
+        comboName?: string;
+        sourceItemId?: string;
+        deltaMultiplier?: number;
+        maxDeltaMultiplier?: number;
+        direction?: "forward" | "backward";
+    }): 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;
+    highlightByStackItemId(id: string | null): void;
+    /**
+     * Affiche temporairement le highlight combo (cercles de fenêtre) pendant ~1.8 s.
+     * Sans effet si un highlight permanent est déjà actif.
+     */
+    flashComboContext(params: {
+        requires: string[];
+        withinLastN?: number;
+        type: string;
+        comboName?: string;
+        sourceItemId?: string;
+        deltaMultiplier?: number;
+        maxDeltaMultiplier?: number;
+        direction?: "forward" | "backward";
+    }): void;
+    /**
+     * Brève mise en valeur (flash) d'une action dans le stack par son actionId.
+     * Anime l'intégralité de l'élément (icôn + checkbox + libellé) via un glow
+     * drop-shadow, sans toucher au mécanisme de combo highlight.
+     */
+    flashActionById(actionId: string): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undo(): void;
+    redo(): void;
+    clearAll(): void;
+    clearToolRange(): void;
+    /**
+     * Clears the active selection in the stack without emitting a change event
+     * and without recording history. Called when the diagram state is cleared
+     * externally (e.g. the user clicks a different child or closes an action menu)
+     * so the stack visual stays in sync. Because the deselection is a side-effect
+     * of a diagram action — not a direct user action on the stack — it is not
+     * added to the undo history.
+     */
+    deselectAllItems(): void;
+    getActionLabel(actionId: string): string | null;
+    clickBookmark(index: number): void;
+    addItem(item: Omit<ActionStackItem, "id" | "validatedAt" | "slotIndex">, insertAtVisibleIndex?: number | null, entryOrigin?: Point): void;
+    /** Insertion à un slot absolu avec décalage systématique — voir
+     *  ActionStackState.addItemAtSlot. Même remise à zéro de l'aperçu de
+     *  glisser qu'addItem, pour la même raison (rendu synchrone dans
+     *  state.addItemAtSlot). */
+    addItemAtSlot(item: Omit<ActionStackItem, "id" | "validatedAt" | "slotIndex">, slotIndex: number): ActionStackItem;
+    syncActiveAction(sourceChildKey: string | null, actionId: string | null): void;
+    setExternalDragActive(active: boolean): void;
+    clearDropPreview(): void;
+    updateDropPreview(clientX: number, clientY: number, _localY: number): boolean;
+    isDropZoneHit(clientX: number, clientY: number): boolean;
+    getInsertionPreviewIndex(): number | null;
+    /** True while the user is actively dragging a stack item. */
+    get isDragging(): boolean;
+    /**
+     * Returns all action IDs currently in the stack, in visual stack order
+     * (bottom-first, i.e. earliest-played first). This is the authoritative
+     * "played history" for combo evaluation: items[0] is the oldest/bottom card,
+     * items[last] is the newest/top card. Drag-and-drop reordering is reflected
+     * immediately because reorderStackItemsByVisibleIndex mutates this.state.items.
+     */
+    getOrderedActionIds(): string[];
+    getSlotPaddedActionIds(anchorSlot: number, activeItemIds?: Set<string>): string[];
+    getNextTopSlot(): number;
+    getItemsInStackOrder(): ActionStackItem[];
+    getEffectiveDeltaByActionId(): Map<string, number>;
+    updateVisual(): void;
+    /**
+     * Garantit, dans le <defs> du SVG de la pile, le gradient de cœur propre au
+     * type de highlight courant, ainsi que le gradient d'impulsion et le filtre
+     * de flou partagés par toutes les jauges de fenêtre. Idempotent.
+     */
+    private _ensureWindowIndicatorDefs;
+    private _buildRenderContext;
+    /**
+     * Pendant un glisser du corps du bracket (voir draggingRangeBlock), calcule une
+     * projection en direct des positions — mêmes formules que ActionStackState.
+     * moveRangeTo, mais purement pour l'affichage : this.state.items n'est modifié
+     * qu'au relâchement (commitRangeMove). Hors glisser, retourne les items tels quels.
+     */
+    private _computePreviewItems;
+    private _computeLayout;
+    private _renderPanel;
+    private _renderFooterButtons;
+    private _renderConfigBookmarks;
+    private _renderGhostSlots;
+    private _renderTimeline;
+    private _renderItems;
+    private _renderComboHighlight;
+    private _renderUnifiedControl;
+    private _renderDragGhost;
+    private _bindItemInteractions;
+    private ensureActionStackGroup;
+    private ensureResizeObserver;
+    /** Copies the current tool range to the internal clipboard. */
+    copyRangeToClipboard(): void;
+    /** Pastes the clipboard at the top of the currently active stack. */
+    pasteClipboard(): void;
+    private ensureKeyboardListeners;
+}

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

@@ -0,0 +1,111 @@
+import * as d3 from "d3";
+import type { ActionStackState, ActionStackItem } from "./ActionStackState";
+export interface DragHandlerHost {
+    updateVisual(): void;
+    removeItem(id: string): void;
+    toggleItemSelection(id: string, emitChange: boolean): void;
+    toggleRangeActivation(): void;
+    setToolRange(minSlot: number, maxSlot: number): void;
+    /** Tap (sans glisser) sur la poignée basse : étend la plage jusqu'au slot 0. */
+    expandRangeToBottom(): void;
+    /** Tap (sans glisser) sur la poignée haute : étend la plage jusqu'au dernier item. */
+    expandRangeToTop(): void;
+    /** Double-clic sur la gouttière, n'importe où : sélectionne toute la pile d'un coup. */
+    selectAllRange(): void;
+    /** Déplace effectivement le bloc [originalMinSlot..originalMaxSlot] jusqu'à ce
+     *  que son début arrive à targetMinSlot — appelé au relâchement d'un glisser sur
+     *  le corps du bracket, une fois le geste confirmé (pas un simple tap). */
+    commitRangeMove(originalMinSlot: number, originalMaxSlot: number, targetMinSlot: number): void;
+    highlightByStackItemId(id: string | null): void;
+    triggerBlockHighlight(id: string | null): void;
+    triggerSatelliteHighlight(id: string | null): void;
+    locateInSearch(compId: string, oddId: string, cutIdx: number, actionId: string, kind: "action" | "keyEvent"): void;
+    /** Clic sur le libellé d'un item : sélectionne automatiquement son
+     *  satellite porteur dans le diagramme (action) — ou sa Facette d'origine
+     *  (Événement Clé, sentinel oddId="" / cutIdx=-1, cf. ActionStackState) —
+     *  sans changer d'onglet, contrairement à locateInSearch. stackItemId
+     *  permet ensuite de centrer automatiquement le bloc correspondant dans la
+     *  liste "Effets cumulés" une fois celle-ci (re)rendue. */
+    selectSatelliteForItem(compId: string, oddId: string, cutIdx: number, stackItemId: string): void;
+}
+type Point = {
+    x: number;
+    y: number;
+};
+type RenderableItem = ActionStackItem & {
+    isPlaceholder?: boolean;
+    /** Aperçu d'échange lors d'un réordonnancement interne uniquement — voir
+     *  ActionStackController._computeLayout. */
+    isDisplacedPreview?: boolean;
+};
+export declare class ActionStackDragHandler {
+    private readonly state;
+    private readonly host;
+    static readonly ACTION_DRAG_THRESHOLD_PX = 12;
+    static readonly DOUBLE_CLICK_MS = 300;
+    draggingStackItemId: string | null;
+    draggingStackItemPosition: Point | null;
+    draggingStackItemGhostWithLabel: boolean;
+    stackInsertionPreviewIndex: number | null;
+    pendingStackItemEntryOrigins: Map<string, Point>;
+    pendingSwapDropY: Map<string, number>;
+    stackControlDragInProgress: boolean;
+    /** Bloc en cours de glissement via le corps du bracket — permet au rendu de
+     *  prévisualiser en direct la translation des items concernés, sans encore
+     *  toucher à l'état persistant (le vrai déplacement n'a lieu qu'au relâchement,
+     *  voir commitRangeMove). */
+    draggingRangeBlock: {
+        ids: Set<string>;
+        originalMinSlot: number;
+        originalMaxSlot: number;
+    } | null;
+    externalActionDragActive: boolean;
+    dropZoneClient: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    } | null;
+    dropZoneIsHot: boolean;
+    private lastGutterClickTime;
+    private layoutMetrics;
+    constructor(state: ActionStackState, host: DragHandlerHost);
+    get isDragging(): boolean;
+    setExternalDragActive(active: boolean): void;
+    setRenderGeometry(dropZoneClient: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    }, layoutMetrics: {
+        firstSlotCenterY: number;
+        slotSpacing: number;
+        compactLength: number;
+    }): void;
+    clearDropPreview(): void;
+    updateDropPreview(clientX: number, clientY: number, _localY: number): boolean;
+    isDropZoneHit(clientX: number, clientY: number): boolean;
+    getInsertionPreviewIndex(): number | null;
+    private emitDragPreviewChange;
+    syncPosition(actionStackGroup: SVGGElement | null): void;
+    bindItemInteractions(mergedItems: d3.Selection<SVGGElement, RenderableItem, SVGGElement, unknown>, bindCtx: {
+        x: number;
+        leftPad: number;
+        labelXOffset: number;
+        bottomY: number;
+    }, actionStackGroup: SVGGElement | null, _actionStackLabelFontScale: number): void;
+    bindUnifiedControlInteractions(ctrlMerged: d3.Selection<SVGGElement, number, SVGGElement, unknown>, ctrlBounds: {
+        minSlot: number;
+        maxSlot: number;
+    }, slotSpacing: number, numVisibleSlots: number): void;
+    /**
+     * Glisser dans la gouttière temporelle (graduation à gauche de la pile) définit
+     * une plage libre — plus d'ancrage forcé au slot 0. Un simple tap sélectionne le
+     * slot visé seul (plage de taille 1) ; un glissement l'étend jusqu'au slot courant.
+     * Réutilise le même calcul slot↔Y que l'aperçu de dépôt (updateDropPreview) pour
+     * rester cohérent avec la conversion clientY → slot déjà éprouvée ailleurs.
+     */
+    bindGutterSelectInteraction(hitStrip: d3.Selection<SVGRectElement, number, SVGGElement, unknown>): void;
+    private _svgLocalPoint;
+}
+export {};

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

@@ -0,0 +1,118 @@
+import { IYinYangController } from "../../../interfaces/IYinYangController";
+import { IYinYangView } from "../../../interfaces/IYinYangView";
+import { YinYangControllerState } from "../state/YinYangControllerState";
+import { ActionStackController, ActionStackItem } from "./ActionStackController";
+import { ChildrenOrbitEntry } from "../utils/childrenOrbit";
+import { SequentialActionProjectionInput } from "../actions/ActionProjectionService";
+import { type ComboResult } from "../../../data/combo-engine";
+import { ForceFieldLink } from "../force-field/types";
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+type ChildOddMeta = {
+    oddId: string;
+    score: number;
+    cuttingIndex: number;
+};
+type SelectedSourceFocus = {
+    oddId: string;
+    cuttingId: number | undefined;
+} | null;
+type PersistentActionContext = {
+    sourceComponentId: string;
+    sourceOddId: string;
+    sourceCuttingIndex: number;
+    actionId: string;
+    actionLabel?: string;
+    links: ForceFieldLink[];
+} | null;
+type ActionStackManagerDeps = {
+    view: IYinYangView;
+    state: YinYangControllerState;
+    actionStackController: ActionStackController;
+    getChildControllers: () => IYinYangController[];
+    getChildOddMap: () => Map<string, ChildOddMeta>;
+    getSelectedSourceFocus: () => SelectedSourceFocus;
+    setSelectedSourceFocus: (focus: SelectedSourceFocus) => void;
+    getPersistentActionContext: () => PersistentActionContext;
+    setPersistentActionContext: (ctx: PersistentActionContext) => void;
+    getInternalModel: () => YinYangInternalModel;
+    getCurrentComponent: () => YinYangInternalModel["components"][number] | null;
+    getCurrentComponentOrUndefined: () => YinYangInternalModel["components"][number] | undefined;
+    getAllComponents: () => YinYangInternalModel["components"] | undefined;
+    prepareForComponentSwitch: (targetComponentId: string) => void;
+    animateChildrenHide: () => void;
+    recomputeIncomingForceFieldForItems: (items: ActionStackItem[], sourceComponentId: string, currentComponentId: string) => boolean;
+    buildProjectionActionsFromStackItems: (items: ActionStackItem[]) => SequentialActionProjectionInput[];
+    buildForceFieldSourceIndicesFromStackItems: (items: ActionStackItem[]) => number[];
+    clearProjectedActionState: (options?: {
+        deselect?: boolean;
+    }) => void;
+    clearActiveChild: () => void;
+    clearForceFieldComputationState: () => void;
+    renderOppositeChildrenForceField: () => void;
+    renderForceFieldDetails: (linkIndex: number) => void;
+    buildChildrenOrbitData: () => ChildrenOrbitEntry[];
+    renderChildScoresDeltas: (orbitData: ChildrenOrbitEntry[]) => void;
+    syncGhostTensionFromAction: () => void;
+    renderGhostDetailsForActiveAction: () => void;
+    renderCumulativeDetailsForCutting: (oddId: string, cuttingId: number | undefined) => boolean | undefined;
+    renderSourceActionDetailsForCurrentSource: () => void;
+    renderActionPropagationTable: () => void;
+    clearGhostDetails: () => void;
+    /** Réaffiche le descriptif de la Facette courante (avec ses blocs Événement
+     *  Clé) — utilisé quand la pile ne contient plus que des items sans
+     *  satellite (Événement Clé) après clearProjectedActionState, qui sinon
+     *  retombe seul sur la carte Sphère. */
+    showComposanteInfo: () => void;
+    refreshChildActionMenu: () => void;
+};
+export declare class ActionStackManager {
+    private readonly deps;
+    private activeStackItemsSnapshot;
+    private lastComboResults;
+    private lastFocusBeforeAllUnchecked;
+    /** weightDelta of the action(s) currently previewed, summed per targeted
+     *  satellite (a satellite is always its own single target, never
+     *  propagated) — read by YinYangController to animate/ring each satellite. */
+    private currentWeightDeltaByChildKey;
+    constructor(deps: ActionStackManagerDeps);
+    getActiveItems(): ActionStackItem[];
+    getWeightDeltaByChildKey(): Map<string, number>;
+    /**
+     * Same weightDelta computation as getWeightDeltaByChildKey (baseDelta ×
+     * amplificateurs, écrêté aux bornes [WEIGHT_MIN, WEIGHT_MAX] du poids
+     * actuel), mais agrégée sur TOUTE la pile active — pas seulement les items
+     * de la facette actuellement affichée. La bordure du cercle central montre
+     * toutes les facettes à la fois (voir buildBorderSegments), donc son ghost
+     * a besoin du poids projeté de chaque facette ayant des items empilés,
+     * même celles qu'on ne regarde pas en ce moment. Clé :
+     * `${sourceComponentId}::${sourceOddId}::${sourceCuttingIndex}` — un
+     * satellite d'une facette non affichée n'a pas de sourceChildKey exploitable
+     * ici (childOddMap ne connaît que la facette courante).
+     */
+    getWeightDeltaByComponentOddCutting(): Map<string, number>;
+    clearWeightPreview(): void;
+    resetLastComboResults(): void;
+    computeComboResultsForAction(actionId: string): ComboResult[] | undefined;
+    validateActionSelection(childController: IYinYangController, actionId: string, label: string, insertAtVisibleIndex?: number | null, entryOrigin?: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Insertion directe à un slot absolu, sans passer par la sélection
+     * d'action du satellite (pas de menu, pas de champ de force) : c'est le
+     * chemin du placement automatique des actions adverses par le système.
+     * Le delta effectif est évalué à la position réelle d'insertion ; il
+     * sera de toute façon recalculé pour toute la pile par
+     * onStackItemVisibilityToggle à l'émission qui suit.
+     */
+    insertActionAtSlot(childController: IYinYangController, actionId: string, label: string, slotIndex: number): void;
+    /** Item de pile d'une action jouée depuis un satellite — couleur de son
+     *  ODD, métadonnées de son cutting. Null si le satellite est inconnu. */
+    private buildActionStackItem;
+    activateActionFromChild(childController: IYinYangController, actionId?: string, label?: string, clearStack?: boolean): void;
+    applyProjectedGhostFromStackItems(items: ActionStackItem[]): void;
+    onStackItemVisibilityToggle(activeItems: ActionStackItem[]): void;
+    private updateProjectedGhostTensions;
+    private applyEmptyGhostProjectionState;
+}
+export {};

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

@@ -0,0 +1,169 @@
+export type ActionStackItem = {
+    id: string;
+    /**
+     * Nature de l'item — "action" (par défaut) pour une action satellite
+     * classique, "keyEvent" pour un Événement Clé joué depuis le cercle
+     * central d'une facette. Un keyEvent n'a pas de satellite cible (les
+     * champs source* ci-dessous sont des sentinels dans ce cas) ni de delta
+     * propre (effectiveDelta reste 0) — son seul effet est d'amplifier les
+     * actions listées dans sa définition, si elles sont jouées après lui
+     * dans la pile (voir amplifier-engine.ts).
+     */
+    kind: "action" | "keyEvent";
+    /** actionId pour kind="action" ; KeyEventDefinition.id pour kind="keyEvent"
+     *  (préfixe "key_" garantit l'absence de collision avec un actionId). */
+    actionId: string;
+    label: string;
+    /** Sentinel "" pour kind="keyEvent" — non rattaché à un satellite précis. */
+    sourceChildKey: string;
+    /** Sentinel "" pour kind="keyEvent". */
+    sourceOddId: string;
+    /** Sentinel -1 pour kind="keyEvent". */
+    sourceCuttingIndex: number;
+    /** Facette d'origine — pour un keyEvent, c'est la facette de déclenchement. */
+    sourceComponentId: string;
+    color: string;
+    validatedAt: number;
+    /** Delta effectif après évaluation du combo (= baseDelta × multiplicateur).
+     *  Toujours 0 pour kind="keyEvent" (pas d'effet propre). */
+    effectiveDelta: number;
+    /** Résultats des combos évalués au moment du jeu — un par slot déclenché. */
+    comboResults?: import("../../../data/combo-engine").ComboResult[];
+    /** Index du slot occupé dans la pile (0 = en bas, croissant vers le haut). */
+    slotIndex: number;
+};
+/** Champs persistants d'un item copié — sans id/validatedAt/slotIndex, qui sont
+ *  réattribués à l'insertion (dans la même pile ou une autre, via un bookmark). */
+export type StackClipboardEntry = Omit<ActionStackItem, "id" | "validatedAt" | "slotIndex">;
+export type BookmarkState = "empty" | "unlocked" | "locked";
+export type ConfigBookmark = {
+    state: BookmarkState;
+    lockedSnapshot: StackState | null;
+    dominantColor: string;
+};
+export type StackState = {
+    items: ActionStackItem[];
+    activeItemIds: string[];
+};
+export type ActionStackSnapshot = StackState & {
+    activeBookmarkIndex: number | null;
+    bookmarks: Array<{
+        state: BookmarkState;
+        lockedSnapshot: StackState | null;
+        dominantColor: string;
+    }>;
+};
+/**
+ * Pure state class for the action stack — no DOM, no D3.
+ * Manages items, selection, history, config bookmarks and tool range.
+ * The controller wraps mutations with a visual update after each call.
+ */
+export declare class ActionStackState {
+    private readonly onActiveItemsChange;
+    private readonly onClear?;
+    readonly ACTION_STACK_MAX_ITEMS = 30;
+    readonly HISTORY_LIMIT = 120;
+    readonly CONFIG_BOOKMARKS_MAX = 4;
+    items: ActionStackItem[];
+    activeItemIds: Set<string>;
+    historyPast: ActionStackSnapshot[];
+    historyFuture: ActionStackSnapshot[];
+    isApplyingHistory: boolean;
+    toolRangeMin: number;
+    toolRangeMax: number | null;
+    /** Presse-papiers de plage — survit volontairement au changement de bookmark
+     *  (copier sur une pile, basculer de bookmark, coller sur une autre). */
+    stackClipboard: StackClipboardEntry[] | null;
+    configBookmarks: ConfigBookmark[];
+    activeBookmarkIndex: number;
+    constructor(onActiveItemsChange: (activeItems: ActionStackItem[]) => void, onClear?: (() => void) | undefined);
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getItemById(id: string): ActionStackItem | undefined;
+    getActionLabel(actionId: string): string | null;
+    getOrderedActionIds(): string[];
+    getSlotPaddedActionIds(anchorSlot: number, activeItemIds?: Set<string>): string[];
+    getNextTopSlot(): number;
+    getItemsInStackOrder(): ActionStackItem[];
+    getEffectiveDeltaByActionId(): Map<string, number>;
+    /** Bornes de la plage d'outil, qu'elle contienne des items ou non — pour l'affichage
+     *  du bracket, qui doit rester visible même sur une plage dessinée à vide (voir
+     *  getToolBlock ci-dessous, qui lui exige au moins un item pour les mutations). */
+    getToolRangeBounds(): {
+        minSlot: number;
+        maxSlot: number;
+    } | null;
+    getToolBlock(): {
+        items: ActionStackItem[];
+        minSlot: number;
+        maxSlot: number;
+    } | null;
+    hasClipboard(): boolean;
+    /**
+     * Adds a new item to the stack and returns the created ActionStackItem so
+     * the controller can register animation origins if needed.
+     *
+     * @param compactLength  Current number of visible slots (from render context).
+     *                       Null when called without a specific insertion index.
+     */
+    addItem(item: Omit<ActionStackItem, "id" | "validatedAt" | "slotIndex">, insertAtVisibleIndex: number | null, compactLength: number | null): ActionStackItem;
+    /**
+     * Insère à un slot ABSOLU (0 = bas de pile), en décalant d'un cran tout
+     * item situé à ce slot ou au-dessus — inconditionnellement, même si le
+     * slot est un trou : c'est ce qui rend l'arithmétique d'un plan
+     * d'insertions (adverse-action-planner.ts) exacte, insertion après
+     * insertion. addItem, lui, n'a pas cette garantie (il ne décale qu'en
+     * présence d'un occupant, et raisonne en index visible).
+     */
+    addItemAtSlot(item: Omit<ActionStackItem, "id" | "validatedAt" | "slotIndex">, slotIndex: number): ActionStackItem;
+    private pushItemAtSlot;
+    removeItem(itemId: string): void;
+    clearAll(): void;
+    deselectAllItems(): void;
+    syncActiveAction(sourceChildKey: string | null, actionId: string | null): boolean;
+    toggleItemSelection(itemId: string, emitChange: boolean): void;
+    /** Définit la plage d'outil librement (glisser dans la gouttière temporelle) — plus d'ancrage forcé au slot 0. */
+    setToolRange(minSlot: number, maxSlot: number): void;
+    /** Fait disparaître le bracket sans toucher aux items — clic sur un emplacement
+     *  vide de la pile, en dehors de la gouttière et du bracket lui-même. */
+    clearToolRange(): void;
+    /** Étend la borne basse de la plage jusqu'au tout début de la pile (slot 0) —
+     *  tap sur la poignée basse du bracket, sans glisser. */
+    expandRangeToBottom(): void;
+    /** Étend la borne haute de la plage jusqu'au dernier item de la pile — tap sur
+     *  la poignée haute du bracket, sans glisser. */
+    expandRangeToTop(): void;
+    /** Sélectionne d'un coup l'ensemble de la pile — double-clic sur la gouttière
+     *  temporelle, n'importe où. */
+    selectAllRange(): void;
+    clickBookmark(index: number): void;
+    undo(): void;
+    redo(): void;
+    /**
+     * Translate le bloc [originalMinSlot..originalMaxSlot] pour que son début arrive
+     * à targetMinSlot — décalage pur des numéros de slot, pas une réinsertion relative
+     * aux autres items. Les items "traversés" par le déplacement (ceux qui occupaient
+     * l'espace entre l'ancienne et la nouvelle position du bloc) sont repoussés de la
+     * taille du bloc pour combler l'espace laissé vacant ; tout le reste ne bouge pas.
+     * Généralise l'ancien couple moveRangeUp/moveRangeDown (un cran à la fois, swap
+     * avec le seul item adjacent) à un déplacement de plusieurs crans en un glisser.
+     */
+    moveRangeTo(originalMinSlot: number, originalMaxSlot: number, targetMinSlot: number): void;
+    toggleRangeActivation(): void;
+    /** Copie la plage sélectionnée dans le presse-papiers interne — n'affecte pas la pile,
+     *  donc pas d'entrée d'historique. */
+    copyRangeToClipboard(): void;
+    /** Colle le contenu du presse-papiers au sommet de la pile courante (celle du
+     *  bookmark actif) et sélectionne la plage collée. */
+    pasteClipboard(): void;
+    createSnapshot(): ActionStackSnapshot;
+    recordHistoryBeforeMutation(): void;
+    recordHistoryBeforeMutationAndReturnItems(): ActionStackItem[];
+    markActiveBookmarkDirty(): void;
+    ensureItemSlotIndices(): void;
+    emitActiveItemsChange(): void;
+    private createStackState;
+    private pushHistory;
+    private applyStackState;
+    private applySnapshot;
+}

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

@@ -0,0 +1,73 @@
+import { YinYangInternalModel } from "../../../interfaces/IYinYangInternalModel";
+import { type PropagatedActionEdge } from "../../../utils/actionPropagation";
+import { ForceFieldLink } from "../force-field/types";
+export type ProjectedCuttingState = {
+    cuttingId: number;
+    originalTension: number;
+    projectedTension: number;
+    originalState: number;
+    projectedState: number;
+};
+export type GhostProjectionResult = {
+    projectedGhostTensionByOddId: Map<string, number>;
+    projectedGhostStateByOddId: Map<string, number>;
+    projectedGhostComponentTension: number;
+    projectedGhostCuttingStatesByOddId: Map<string, ProjectedCuttingState[]>;
+};
+export type SequentialActionProjectionInput = {
+    sourceOddId: string;
+    sourceCuttingIndex: number;
+};
+export type EmptyGhostProjectionState = {
+    projectedGhostTensionByOddId: null;
+    projectedGhostStateByOddId: null;
+    projectedGhostComponentTension: null;
+    projectedGhostCuttingStatesByOddId: null;
+};
+export declare function getEmptyGhostProjectionState(): EmptyGhostProjectionState;
+export declare function projectGhostStateForIncomingLinks(params: {
+    component: YinYangInternalModel["components"][number] | undefined;
+    incomingLinks: ForceFieldLink[];
+}): GhostProjectionResult | null;
+export type ActionSequenceStateSnapshot = Map<string, Map<number, number>>;
+export type ActionSequenceStepInfo = {
+    actionIndex: number;
+    action: SequentialActionProjectionInput;
+    effectiveDelta: number;
+    /** Clone of the fractional accumulator just before this step is applied. */
+    statesBefore: ActionSequenceStateSnapshot;
+    /** Clone of the fractional accumulator just after this step is applied. */
+    statesAfter: ActionSequenceStateSnapshot;
+    /** This step's own propagation edges — the exact same computation (single
+     *  pass, computeActionPropagationDetails) that produced statesBefore →
+     *  statesAfter, against the real rolled-forward state this step saw. Lets
+     *  callers build a descriptive breakdown (e.g. UI badges) that's guaranteed
+     *  consistent with the state diff, without re-running propagation. */
+    edges: PropagatedActionEdge[];
+};
+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[];
+    /** Called once per action, exposing the fractional accumulator state right
+     *  before and right after that step — lets callers read the exact marginal
+     *  contribution of a single stacked action within the real sequential
+     *  simulation (e.g. the STACK panel's per-block delta). No effect on the
+     *  returned projection. */
+    onStep?: (info: ActionSequenceStepInfo) => void;
+}): GhostProjectionResult | null;
+export declare function projectGhostStateForComponent(params: {
+    component: YinYangInternalModel["components"][number] | undefined;
+    allComponents: YinYangInternalModel["components"] | undefined;
+    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;