@micheeeeel/yinyangapp 1.0.6 → 2.0.0

package/dist/types/interfaces/IYinYangController.d.ts

@@ -1,22 +1,317 @@
-import { IOddItem } from "../interfaces/IOddItem";
 import { IYinYangAppFactory } from "./IYinYangAppFactory";
-import { ICategory } from "./ICategory";
 import { IYinYangModel } from "./IYinYangModel";
 import { IYinYangView } from "./IYinYangView";
 import { IAnimator } from "./IAnimator";
+import { YinYangInternalModel } from "./IYinYangInternalModel";
+import { ForceFieldLinkDetail } from "../components/controller/force-field/types";
 export interface IYinYangController {
     model: IYinYangModel;
     view: IYinYangView;
     factory: IYinYangAppFactory;
     animator: IAnimator;
     createYinYangChildren(): void;
+    clearForceFieldDetails(): void;
+    applyChildrenFitScale(): void;
+    setChildrenEnabled(isEnabled: boolean): void;
+    setChildrenOrbitEnabled(isEnabled: boolean): void;
+    setChildrenOrbitDuration(durationMs: number): void;
+    setChildrenOrbitSpeed(speed: number): void;
+    setChildrenOrbitRadiusScale(scale: number): void;
+    animateChildrenHide(): void;
+    handleComponentSwitchChildren(): void;
+    /** Registers an in-progress animation (rotation, facette/ODD switch, ...)
+     *  that should block ghost display while active. Returns a token to pass
+     *  to endBlockingAnimation() once the animation completes. */
+    beginBlockingAnimation(label: string): symbol;
+    /** Releases a token obtained from beginBlockingAnimation(). */
+    endBlockingAnimation(token: symbol): void;
+    /** Whether any animation registered via beginBlockingAnimation is still running. */
+    hasActiveBlockingAnimation(): boolean;
+    cancelOuterSparkForActivation(): void;
+    prepareForComponentSwitch(targetComponentId: string): void;
     getBorderNb(): number;
-    getSortedData(): IOddItem[];
-    getCategories(): ICategory[];
+    getInternalModel(): YinYangInternalModel;
     getKey(): string;
     getParentKey(): string | null;
-    getIsEnemy(): boolean;
-    calculateAverageScore(): number;
     generateChildKey(): string;
     InitializeAnimations(): void;
+    highlightOddInChildren(oddId: string | null): void;
+    refreshWeightPreviewPulse(): void;
+    enterOddView(oddId: string): void;
+    exitOddView(): void;
+    cancelOddHighlight(): void;
+    /** Shows ODD name + description in the details panel (called on ODD arc click). */
+    showOddInfo(oddId: string): void;
+    /** Shows Composante name + description in the details panel (called on title/legend click). */
+    showComposanteInfo(): void;
+    /**
+     * Sets the number of random force fields (for UI control).
+     */
+    setRandomForceFieldCount(count: number): void;
+    /**
+     * Shows or hides action delta labels next to impacted children.
+     */
+    setActionDeltaLabelsVisible(isVisible: boolean): void;
+    /**
+     * Shows or hides children context labels.
+     */
+    setChildrenContextLabelsVisible(isVisible: boolean): void;
+    /**
+     * Lève le plafond à 1 sur le ratio de performance des prérequis
+     * déclencheurs (combos non dangereux), autorisant une cascade de combos à
+     * dépasser ×2.
+     */
+    setComboUncappedChainedPerformance(isEnabled: boolean): void;
+    /**
+     * Permet à un combo dangereux de devenir un bonus net : lève le plafond à
+     * 1 sur le ratio de performance des prérequis protecteurs, autorisant
+     * m = avgRatio à dépasser ×1.
+     */
+    setComboDangerousCanBecomeBonus(isEnabled: boolean): void;
+    /**
+     * Sets shared font scale for labels.
+     */
+    setLabelsFontScale(scale: number): void;
+    /**
+     * Enables/disables text shadow under labels.
+     */
+    setLabelsTextShadowEnabled(isEnabled: boolean): void;
+    /**
+     * Positions child short label above or below each child.
+     */
+    setChildLabelPlacement(position: "top" | "bottom"): void;
+    /**
+     * Shows or hides ODD labels rendered inside Yin/Yang arcs.
+     */
+    setOddContextLabelsVisible(isVisible: boolean): void;
+    /**
+     * Shows or hides all label types at once (action deltas, children labels).
+     * ODD labels remain visible but switch between compact ("ODD4") and full label format.
+     */
+    setAllLabelsVisible(isVisible: boolean): void;
+    /**
+     * Switches ODD arc labels between compact ("ODD4") and full label text.
+     * Compact mode is used when the global labels toggle is off.
+     */
+    setOddLabelsCompact(compact: boolean): void;
+    /**
+     * Sets radial offset multiplier for child action menu items distance.
+     */
+    setChildActionMenuItemDistance(distance: number): void;
+    /**
+     * Sets size scale for child action menu items.
+     */
+    setChildActionMenuItemScale(scale: number): void;
+    /**
+     * Sets font scale for child action menu item icons.
+     */
+    setChildActionIconFontScale(scale: number): void;
+    /**
+     * Fine (px) adjustment of the Key Event radial menu buttons' distance,
+     * layered on top of the auto-computed base distance.
+     */
+    setCoreEventMenuDistanceOffset(offset: number): void;
+    setCoreEventMenuItemScale(scale: number): void;
+    setCoreEventIconFontScale(scale: number): void;
+    /**
+     * Sets maximum number of lines for child labels (1-3).
+     */
+    setChildLabelMaxLines(lines: number): void;
+    /**
+     * Sets maximum number of lines for ODD arc labels (1-3).
+     */
+    setOddLabelMaxLines(lines: number): void;
+    setLabelShortMaxChars(chars: number): void;
+    isChildrenEnabled(): boolean;
+    isActionActive(): boolean;
+    /**
+     * Sets font scale for action stack item labels.
+     */
+    setActionStackLabelFontScale(scale: number): void;
+    /**
+     * Sets the size scale for the undo/redo/clear-all history buttons.
+     */
+    setActionStackHistoryButtonScale(scale: number): void;
+    /**
+     * Sets font scale for component/child context labels.
+     */
+    setComponentLabelFontScale(scale: number): void;
+    /**
+     * Sets font scale for children état and delta labels.
+     */
+    setChildStateDeltaFontScale(scale: number): void;
+    /**
+     * Sets the distance offset between child circle and état/delta labels.
+     */
+    setChildStateDeltaOffset(offset: number): void;
+    /**
+     * Sets the scale factor for the selection highlight box around état/delta labels.
+     */
+    setChildStateDeltaBoxScale(scale: number): void;
+    /**
+     * Sets font scale for ODD arc labels.
+     */
+    setOddLabelFontScale(scale: number): void;
+    /**
+     * Sets font scale for the facette score/weight labels in the main circle.
+     */
+    setFacetteLabelFontScale(scale: number): void;
+    /**
+     * Shows/hides the "/max" suffix on the facette score/weight labels.
+     */
+    setFacetteLabelSuffixVisible(isVisible: boolean): void;
+    /**
+     * Sets font scale for deployed component legend labels.
+     */
+    setComponentLegendLabelFontScale(scale: number): void;
+    /**
+     * Enables or disables the dark background frame on deployed labels.
+     */
+    setLegendLabelsBgEnabled(enabled: boolean): void;
+    /**
+     * Enables or disables ellipsis for short labels.
+     */
+    setDisplayEllipsisForShortLabels(enabled: boolean): void;
+    /** Handles a composante click from the Recherche tab — mirrors border arc click logic. */
+    searchHandleComposanteClick(componentIndex: number): void;
+    /** Navigates the diagram to a composante (no stack insertion). */
+    searchNavigateToComponent(componentIndex: number): void;
+    /** Navigates the diagram into ODD view (switching component if needed, no stack insertion). */
+    searchNavigateToOdd(componentIndex: number, oddId: string): void;
+    /** Highlights the ODD arc without entering ODD view (switching component if needed, no stack insertion). */
+    searchHighlightOdd(componentIndex: number, oddId: string): void;
+    /** Handles an ODD arc click from the Recherche tab — mirrors onDiagramOddArcClicked logic. */
+    searchHandleOddArcClick(componentIndex: number, oddId: string): void;
+    /** Mirrors a RECHERCHE legend chip's open/closed state onto its arc in the diagram. */
+    searchActivateOdd(componentIndex: number, oddId: string, isOpen: boolean): void;
+    /** Handles a cutting click from the Recherche tab — mirrors onUserCuttingClicked logic. */
+    searchHandleCuttingClick(componentIndex: number, oddId: string, cuttingIndex: number): void;
+    /** Navigates the diagram to a specific cutting (switching component if needed, no stack insertion).
+     *  @param forceOpen Land on this cutting in its open state even if its menu is already
+     *    flagged active — used by history replay so back/forward never toggles it closed. */
+    searchNavigateToCutting(componentIndex: number, oddId: string, cuttingIndex: number, forceOpen?: boolean): void;
+    /** Navigates to a cutting and activates an action to show force fields (no stack insertion). */
+    searchNavigateToAction(componentIndex: number, oddId: string, cuttingIndex: number, actionId: string): void;
+    /** Re-shows a Key Event's descriptive card (preview only, no stack insertion). */
+    searchNavigateToKeyEvent(keyEventId: string): void;
+    /** Restores the diagram to show a specific action's force field (history restore).
+     *  Unlike searchNavigateToAction, never toggles off if the action is already active. */
+    restoreActionDiagramState(componentIndex: number, oddId: string, cuttingIndex: number, actionId: string): void;
+    /**
+     * Activates force fields for multiple simultaneous sources on the current composante.
+     * Each source is identified by its ODD id and cutting index (0-based array position).
+     * Links from all sources are computed, then _computeMergedSegments() merges overlapping
+     * segments (same startIndex→endIndex) into a single layer group with cumulative potentialGain.
+     *
+     * Used by the benchmark to simulate a multi-action stack without drag-and-drop interaction.
+     */
+    activateForceFieldMultiSource(sources: Array<{
+        oddId: string;
+        cuttingIndex: number;
+    }>): void;
+    /** Starts a drag-to-stack interaction from a search action row. */
+    startSearchActionDrag(componentIndex: number, oddId: string, cuttingIndex: number, actionId: string, label: string, startEvent: PointerEvent, sourceEl: Element, onDragIntentDetected?: () => void): void;
+    /** Starts a drag-to-stack interaction from a search key event row. */
+    startSearchKeyEventDrag(componentIndex: number, keyEventId: string, label: string, startEvent: PointerEvent, sourceEl: Element, onDragIntentDetected?: () => void): void;
+    /**
+     * Wires a callback for opening the search tab with a query string.
+     * Called from main.ts after globalSearch is set up.
+     */
+    setOpenSearchWithQuery(cb: (query: string) => void): void;
+    /** Wires a callback fired when the user starts dragging an action from the diagram. */
+    setOnDiagramActionDragIntent(cb: () => void): void;
+    /** Fires whenever the active satellite (child) changes — including deselection. */
+    setOnActiveChildChange(cb: () => void): void;
+    /** Returns the ODD id, cutting index, and component id of the currently active satellite, or null if none. */
+    getActiveChildMeta(): {
+        oddId: string;
+        cuttingIndex: number;
+        componentId: string;
+    } | null;
+    /** Wires a callback to locate a stack item in the Recherche panel when the user clicks its magnifier icon. */
+    setOnLocateStackItemInSearch(cb: (componentId: string, oddId: string, cuttingIndex: number, actionId: string, kind: "action" | "keyEvent") => void): void;
+    /** Wires a callback to auto-select a stack item's carrier satellite (action) — or
+     *  its origin Facette (Key Event, empty oddId) — in the diagram when the user
+     *  clicks its label. Stays on the current tab (STACK), unlike
+     *  setOnLocateStackItemInSearch which switches to Recherche. */
+    setOnSelectStackItemSatellite(cb: (componentId: string, oddId: string, cuttingIndex: number, stackItemId: string) => void): void;
+    /** Centers (animated scroll) the "Effets cumulés" block matching this stack item,
+     *  once it appears in the panel — see ForceFieldDetailsPanel.requestScrollToStackItemBlock. */
+    requestScrollToStackItemBlock(stackItemId: string): void;
+    /** Wires callbacks to show/clear the direct action impact block in the Recherche tab. */
+    setOnDirectActionBlock(show: (compId: string, oddId: string, cutIdx: number, actionId: string, cardsHtml: string, attachHandlers: (container: HTMLElement) => void) => void, clear: () => void): void;
+    /** Wires callbacks to show/clear a Key Event's descriptive card in the Recherche tab. */
+    setOnShowKeyEventBlock(show: (compId: string, keyEventId: string, cardsHtml: string, attachHandlers: (container: HTMLElement) => void) => void, clear: () => void): void;
+    /** Wires a callback to display a prereq action's direct action block in Panel B. */
+    setOnDirectActionBlockPanelB(show: (compId: string, oddId: string, cutIdx: number, actionId: string, cardsHtml: string, attachHandlers: (container: HTMLElement) => void) => void): void;
+    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;
+    /** Wires callbacks to show/clear the propagated action block in the Recherche tab. */
+    setOnPropagationBlock(show: (compId: string, oddId: string, cutIdx: number, html: string, attachHandlers: (container: HTMLElement) => void, sourceDesc: {
+        breadcrumb: string;
+        title: string;
+        description: string;
+    }, rationale?: string) => void, clear: () => void): void;
+    /** Wires a callback fired when the user clicks an ODD arc in the diagram. */
+    setOnDiagramOddChange(cb: (componentIndex: number, oddId: string, mode: "highlight") => void): void;
+    /** Called by YinYangDrawer when the user clicks an ODD arc: toggles that
+     *  ODD's legend chip in the panel, mirroring a direct chip click. */
+    onDiagramOddArcClicked(oddId: string): void;
+    /** Called by YinYangDrawer when the user clicks the small "eye" circle of
+     *  the facette's dominant lobe (yin or yang, per Composante.orientation) —
+     *  opens/closes the radial menu of Événements Clés for the active facette. */
+    onCoreEventNucleusClicked(): void;
+    /** Wires a callback fired when the user clicks a composante border, cutting, or action in the diagram. */
+    setOnDiagramNavChange(cb: (event: {
+        type: "composante";
+        componentIndex: number;
+    } | {
+        type: "cutting";
+        componentIndex: number;
+        oddId: string;
+        cuttingIndex: number;
+    } | {
+        type: "action";
+        componentIndex: number;
+        oddId: string;
+        cuttingIndex: number;
+        actionId: string;
+    } | {
+        type: "keyEvent";
+        componentIndex: number;
+        keyEventId: string;
+    }) => void): void;
+    /** Fired when the active satellite is deselected (toggle-to-close, or an
+     *  ODD-level interaction taking over) — componentIndex is the current facette. */
+    setOnDiagramSatelliteDeselect(cb: (componentIndex: number) => void): void;
+    /** Fired when the user clicks the current composante's border arc to hide its satellites. */
+    setOnDiagramComposanteDeselect(cb: () => void): void;
+    /** Called by BorderDrawer when the user clicks a composante border arc. */
+    onDiagramComposanteClicked(componentIndex: number): void;
+    /** Toggles satellite (cutting circle) visibility when the user clicks the current composante's border arc. */
+    toggleComposanteChildrenFromDiagram(componentIndex: number): void;
+    /** Hides satellites when the user collapses a composante in the hierarchy. */
+    deactivateComposanteFromHierarchy(): void;
+    /** Signalement visuel transient depuis le survol de l'arbre Recherche — null = clear. */
+    searchPreviewHover(target: {
+        type: string;
+        componentIndex: number;
+        oddId?: string;
+        cuttingIndex?: number;
+        actionId?: string;
+    } | null): void;
+    /** Wire d'un callback déclenché quand la souris entre/sort d'un satellite dans le diagramme. */
+    setOnDiagramChildHover(cb: (componentIndex: number | null, oddId: string | null, cuttingIndex?: number) => void): void;
+    /** Wire d'un callback déclenché quand la souris entre/sort d'un arc de bordure dans le diagramme. */
+    setOnDiagramComposanteHover(cb: (componentIndex: number | null) => void): void;
+    /** Wire d'un callback déclenché quand la souris entre/sort d'un cercle d'action dans le menu radial. */
+    setOnDiagramActionHover(cb: (componentIndex: number | null, oddId: string | null, cuttingIndex: number | null, actionId: string | null) => void): void;
+    /** Wire d'un callback déclenché quand la souris entre/sort d'un arc ODD dans le diagramme
+     *  (lien inverse vers les chips de la légende ODD du panneau RECHERCHE). */
+    setOnDiagramOddArcHover(cb: (oddId: string | null) => void): void;
+    /**
+     * Returns the current force-field allLinkDetails for this controller.
+     * Used by sibling controllers to build a merged detail pool for cross-component chains.
+     */
+    getForceFieldAllLinkDetails(): ForceFieldLinkDetail[];
 }

package/dist/types/interfaces/IYinYangGeometry.d.ts

@@ -0,0 +1,43 @@
+export interface YinYangCategoryArcGeometry {
+    category: string;
+    color: string;
+    startAngle: number;
+    endAngle: number;
+}
+export interface YinYangLayoutGeometry {
+    positionX: number;
+    positionY: number;
+    borderInnerRadius: number;
+}
+export interface YinYangSymbolGeometry {
+    centerY: number;
+    radius: number;
+    smallRadius: number;
+}
+export interface YinYangBorderGeometry {
+    innerRadius: number;
+    outerRadius: number;
+    thickness: number;
+    count: number;
+    isChild: boolean;
+    colors: string[];
+}
+export interface YinYangSpikeGeometry {
+    type: "yin" | "yang";
+    category: string;
+    cuttingIndex: number;
+    startX: number;
+    startY: number;
+    endX: number;
+    endY: number;
+    color: string;
+}
+export interface IYinYangGeometry {
+    layout: YinYangLayoutGeometry;
+    yin: YinYangSymbolGeometry;
+    yang: YinYangSymbolGeometry;
+    categoryArcs: YinYangCategoryArcGeometry[];
+    borderSegments: YinYangCategoryArcGeometry[];
+    border: YinYangBorderGeometry;
+    spikes: YinYangSpikeGeometry[];
+}

package/dist/types/interfaces/IYinYangInternalModel.d.ts

@@ -0,0 +1,34 @@
+export type YinYangOrientation = "yin" | "yang";
+export interface YinYangCategorySlice {
+    id: string;
+    color?: string;
+    weight: number;
+}
+export interface YinYangCuttingNode {
+    id: number;
+    label?: string;
+    shortLabel?: string;
+}
+export interface YinYangOddNode {
+    id: string;
+    label?: string;
+    shortLabel?: string;
+    /** Nombre de satellites (cuttings) que compte cet ODD. */
+    satelliteCount: number;
+    cuttingScores: number[];
+    /** Poids de chaque satellite ; pilote le rayon de son cercle enfant. */
+    cuttingWeights: number[];
+    cuttingIds?: number[];
+    cuttings?: YinYangCuttingNode[];
+}
+export interface YinYangComponentNode {
+    id: string;
+    label?: string;
+    shortLabel?: string;
+    orientation: YinYangOrientation;
+    odds: YinYangOddNode[];
+}
+export interface YinYangInternalModel {
+    slices: YinYangCategorySlice[];
+    components: YinYangComponentNode[];
+}

package/dist/types/interfaces/IYinYangModel.d.ts

@@ -1,18 +1,10 @@
-import { IOddItem } from "../interfaces/IOddItem";
-import { ICategory } from "./ICategory";
+import { YinYangInternalModel } from "./IYinYangInternalModel";
 export interface IYinYangModel {
-    sortedData: IOddItem[];
-    categories: ICategory[];
+    internalModel: YinYangInternalModel;
     key: string;
     parentKey: string | null;
     childCounter: number;
     borderNb: number;
-    isEnemy: boolean;
     generateChildKey(): string;
-    calculateAverageScore(): number;
-    getSmallCircleData(): {
-        score: number;
-        angle: number;
-    }[];
-    setupCategories(data: IOddItem[]): ICategory[];
+    resetChildCounter(): void;
 }

package/dist/types/main.d.ts

@@ -0,0 +1,9 @@
+import "./styles/base.css";
+import "./styles/layout.css";
+import "./styles/controls.css";
+import "./styles/details-panel.css";
+import "./styles/search.css";
+import "./styles/delta-chips.css";
+import "./styles/action-image.css";
+export * from "./api";
+import "./benchmark/runner";

package/dist/types/utils/actionImages.d.ts

@@ -0,0 +1,14 @@
+export type ActionImageSize = "thumb" | "full";
+/**
+ * Convention : les fichiers webp sont nommés exactement par l'id de l'action
+ * (voir scripts/convert-actions.sh), donc l'URL se déduit sans champ stocké.
+ */
+export declare function getActionImageUrl(actionId: string, size: ActionImageSize): string;
+/**
+ * Icône vectorielle courte (bouton, préfixe de liste), même convention de nommage.
+ */
+export declare function getActionIconUrl(actionId: string): string;
+/**
+ * Pictogramme officiel ODD (ONU, version française), même convention de nommage.
+ */
+export declare function getOddIconUrl(oddId: string): string;

package/dist/types/utils/actionPropagation.d.ts

@@ -0,0 +1,74 @@
+import { CauseGraph } from "../interfaces/ICauseGraph";
+import { YinYangComponentNode } from "../interfaces/IYinYangInternalModel";
+import { LocalCuttingEdge, PropagationLayersConfig } from "../interfaces/IPropagationLayers";
+export type Action = {
+    id: string;
+    name: string;
+    from: string;
+    delta: number;
+    category: string;
+    cost: number;
+};
+export type PropagatedActionEdge = {
+    layerType: "inter" | "intra" | "bridge";
+    fromComponentId: string;
+    toComponentId: string;
+    fromOddId: string;
+    toOddId: string;
+    fromCuttingId?: number;
+    toCuttingId?: number;
+    weight: number;
+    deltaTo: number;
+    baseDelta: number;
+    propagationFactor: number;
+    fromState: number;
+    toState: number;
+    absorption: number;
+    gap: number;
+    rationale?: string;
+    /** Entry-point cutting carried from the inter-ODD graph edge (used by Phase 6+7). */
+    targetedCutting?: number;
+};
+export type ProjectedActionStateDetails = {
+    oddStates: Record<string, number>;
+    cuttingStates: CuttingStateMap;
+};
+type CuttingStateMap = Record<string, Record<number, number>>;
+export declare function clampState(state: number): number;
+export declare function tensionFromState(state: number): number;
+export declare function absorptionMultiplier(state: number): number;
+export declare function gapMultiplier(sourceState: number, targetState: number): number;
+export declare function absorptionRuleExplanation(state: number): string;
+export declare function gapRuleExplanation(sourceState: number, targetState: number): string;
+export declare function deriveOddStates(component: YinYangComponentNode): Record<string, number>;
+export declare function deriveCuttingStates(component: YinYangComponentNode): CuttingStateMap;
+/** Find a node in the intra-ODD flat array by toCuttingId (to start AT it). */
+export declare function findNodeInTree(edges: LocalCuttingEdge[], targetId: number): LocalCuttingEdge | null;
+export declare function propagateActionInComponent(component: YinYangComponentNode, graph: CauseGraph, sourceOddId: string, delta: number, k: number): PropagatedActionEdge[];
+export type ActionPropagationDetails = ProjectedActionStateDetails & {
+    edges: PropagatedActionEdge[];
+};
+/**
+ * Canonical single-pass propagation: runs the 8 phases once and returns both
+ * the collected edges AND the final states. propagateForceFieldActionInComponent
+ * and projectActionStateDetailsInComponent below are thin wrappers over this —
+ * having them as two independently-maintained twins previously let the
+ * state-only path silently drift from the edge path: it never passed
+ * `allComponents` into the Phase 5 inter-ODD call (so cross-component edges
+ * were absent from its internal `interEdges` — with real data this happened
+ * to have no effect on the RETURNED states, since Phase 6/7 already only
+ * ever applies same-component budgets, but it meant edges/rationale for ~150
+ * real cross-component synergies were unavailable to any caller built on top
+ * of the state-only path), and it never threaded the Phase 6/7 "global mode"
+ * tracking (`targetedOddsWithGlobalMode`) that the edge path has — inert with
+ * today's graph/layers data (no same-component edge without a targetedCutting
+ * currently targets an ODD that has its own intra chain) but a silent
+ * divergence waiting for the next graph data change. One implementation
+ * makes both classes of bug structurally impossible instead of just
+ * currently-inert.
+ */
+export declare function computeActionPropagationDetails(component: YinYangComponentNode, graph: CauseGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, k: number, layers?: PropagationLayersConfig, allComponents?: YinYangComponentNode[]): ActionPropagationDetails;
+export declare function propagateForceFieldActionInComponent(component: YinYangComponentNode, graph: CauseGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, k: number, layers?: PropagationLayersConfig, allComponents?: YinYangComponentNode[]): PropagatedActionEdge[];
+export declare function projectActionStateDetailsInComponent(component: YinYangComponentNode, graph: CauseGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, k: number, layers?: PropagationLayersConfig, allComponents?: YinYangComponentNode[]): ProjectedActionStateDetails;
+export declare function projectActionStatesInComponent(component: YinYangComponentNode, graph: CauseGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, k: number, layers?: PropagationLayersConfig, allComponents?: YinYangComponentNode[]): Record<string, number>;
+export {};

package/dist/types/utils/appMode.d.ts

@@ -0,0 +1,5 @@
+/** Whether the STACK panel tab (as opposed to RECHERCHE) is currently active.
+ *  Mirrors the DOM-based mode check already used in DiagramPanelBridge/main.ts —
+ *  there is no in-memory "mode" state to read from, tab activity is the source
+ *  of truth for which panel the user is looking at. */
+export declare function isStackModeActive(): boolean;

package/dist/types/utils/causeGraph.d.ts

@@ -0,0 +1,6 @@
+import { Cause } from "../interfaces/ICauseModel";
+import { CauseGraph, CauseNodeId } from "../interfaces/ICauseGraph";
+export declare function makeCauseNodeId(componentId: string, oddId: string): CauseNodeId;
+export declare function listCauseNodeIds(cause: Cause): CauseNodeId[];
+export declare function validateCauseGraph(cause: Cause, graph: CauseGraph): string[];
+export declare function countEdges(graph: CauseGraph): number;

package/dist/types/utils/causeMetrics.d.ts

@@ -0,0 +1,26 @@
+export declare function average(values: number[]): number;
+export declare function weightedAverage(values: number[], weights: number[]): number;
+export declare function clampScore(value: number): number;
+/**
+ * Canonical domain metric in [0, 1]. Weighted by each satellite's `weight`
+ * when provided, so a heavier satellite pulls the tension further toward
+ * its own score; falls back to a simple average otherwise.
+ */
+export declare function tensionFromCuttings(cuttingScores: number[], cuttingWeights?: number[]): number;
+export declare const oddTensionFromCuttings: typeof tensionFromCuttings;
+export declare function stateFromTension(tension: number): number;
+/** Bornes du poids d'un satellite (importance dans sa facette). Un satellite
+ *  vaut 1 par défaut ; les actions le font varier par pas entiers, mais ne
+ *  peuvent jamais le sortir de cette plage. Échelle 0-10 (doublée depuis la
+ *  0-5 d'origine) pour laisser de la marge aux deltas cumulés (actions,
+ *  combos, amplificateurs d'événements clés) avant écrêtage. */
+export declare const WEIGHT_MIN = 0;
+export declare const WEIGHT_MAX = 10;
+export declare function clampWeight(value: number): number;
+/**
+ * Delta de poids réellement applicable compte tenu des bornes [WEIGHT_MIN,
+ * WEIGHT_MAX] : un delta qui pousserait le poids hors bornes est écrêté, et
+ * vaut 0 (donc "aucun delta") si le poids est déjà à la borne visée par son
+ * signe — ex: +1 sur un satellite déjà à WEIGHT_MAX ne change rien.
+ */
+export declare function effectiveWeightDelta(currentWeight: number, delta: number): number;

package/dist/types/utils/chainCardHeight.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Un seul bloc affiché : les cartes gardent leur hauteur par défaut, calée sur
+ * le format des illustrations pour qu'elles s'affichent entières (cf.
+ * commentaire sur .ff-chain-card dans details-panel.css).
+ * À partir de deux blocs, on réduit la hauteur des cartes pour que deux blocs
+ * tiennent dans la hauteur visible du conteneur sans scroll — au-delà, le
+ * scroll prend le relais. L'image reste alors visible en entier mais plus
+ * petite, avec une bande vide en haut et en bas (object-fit: contain, cf.
+ * action-image.css) : c'est la hauteur qui cède, jamais le cadrage.
+ *
+ * La variable CSS est posée à la fois sur le conteneur ET directement sur
+ * chaque `.ff-chain-card` : quand un bloc est ajouté après coup (RECHERCHE,
+ * insertAdjacentHTML) plutôt qu'en même temps que les autres (STACK,
+ * innerHTML unique), l'héritage seul ne suffit pas toujours à invalider le
+ * `height` déjà calculé des cartes existantes — le poser directement sur
+ * chaque carte contourne ce cas.
+ */
+export declare function syncChainCardHeight(container: HTMLElement, blockSelector?: string): void;
+/**
+ * Recalcule immédiatement puis surveille le conteneur pour garder la hauteur
+ * des cartes synchronisée : redimensionnement du panneau (ResizeObserver) et
+ * ajout/retrait de blocs (MutationObserver — un bloc peut être ajouté/retiré
+ * sans que la taille du conteneur lui-même ne change, ex. panneau RECHERCHE
+ * où le bloc secondaire propagé apparaît/disparaît). Idempotent : un seul
+ * couple d'observers est installé par conteneur.
+ */
+export declare function watchChainCardHeight(container: HTMLElement, blockSelector?: string): void;

package/dist/types/utils/d3/D3Element.d.ts

@@ -2,12 +2,12 @@ import * as d3 from "d3";
 import { IGraphicElement } from "../../interfaces/IGraphicElement";
 export declare class D3Element implements IGraphicElement {
     private selection;
-    constructor(selection: d3.Selection<any, unknown, HTMLElement, any>);
+    constructor(selection: d3.Selection<any, unknown, Element | null, any>);
     appendElement(elementType: string): IGraphicElement;
     setStyle(property: string, value: string): IGraphicElement;
     setAttribute(name: string, value: string): IGraphicElement;
     addEventListener(event: string, callback: () => void): void;
-    getSelection(): d3.Selection<any, unknown, HTMLElement, any>;
+    getSelection(): d3.Selection<any, unknown, Element | null, any>;
     select(query: string): IGraphicElement;
     node(): any;
     getDimensions(): {