@micheeeeel/yinyangapp 3.0.0 → 3.1.0

package/dist/types/data/key-event-eligibility.d.ts

@@ -0,0 +1,24 @@
+import type { ActionStackItem } from "../components/controller/action-stack/ActionStackState";
+import type { KeyEventDefinition } from "./key-event-types";
+/** EVT-08: an occupied event slot keeps half its nominal effect, including
+ * the first action. The shared Beta peak stays unchanged; combos keep their
+ * own 15% floor. See documentation/events-balance.md for measured arbitration. */
+export declare const EVENT_MIN_POSITIONAL_STRENGTH = 0.5;
+export declare function eventPositionStrength(slotDistance: number, withinNextN: number): number;
+export interface EligibleKeyEvent {
+    eventId: string;
+    sourceItemId: string;
+    targetItemId: string;
+    /** Absolute slot distance, including unoccupied slots. */
+    slotDistance: number;
+    strength: number;
+}
+/** Shared eligibility for all five signatures. An event remains available on
+ * every slot of its window: no charge, consumption, or trigger counter. */
+export declare function evaluateKeyEventEligibility(params: {
+    event: KeyEventDefinition;
+    sourceItem: ActionStackItem;
+    targetItem: ActionStackItem;
+    activeItemIds: ReadonlySet<string>;
+    actionDelta: number;
+}): EligibleKeyEvent | null;

package/dist/types/data/key-event-propagation.d.ts

@@ -0,0 +1,13 @@
+import { type CompiledEdge, type CompiledPropagationGraph, type SatelliteRef } from "../interfaces/IPropagationGraph";
+import type { ResolvedKeyEvent } from "./key-event-effects";
+export type KeyEventPropagationContext = {
+    actionId: string;
+    source: SatelliteRef;
+    /** Actual source satellite's action catalogue, not the event's target list. */
+    applicableActionIds: readonly string[];
+    eligibleEvents: readonly ResolvedKeyEvent[];
+};
+/** Resolution-local first hops. No writes to graph, catalogue or event data.
+ * RAYONNEMENT adds weighted boosts before one clamp. PORTÉE contributions
+ * remain separate (including equal endpoints), in stable event/bridge order. */
+export declare function resolveKeyEventPropagationEdges(graph: CompiledPropagationGraph, source: SatelliteRef, context: KeyEventPropagationContext | undefined, exists: (ref: SatelliteRef) => boolean): readonly CompiledEdge[];

package/dist/types/data/key-event-types.d.ts

@@ -0,0 +1,48 @@
+import type { SatelliteRef } from "../interfaces/IPropagationGraph";
+export type AmplifierSignature = {
+    type: "amplifier";
+    deltaBonus: number;
+    weightBonus?: number;
+};
+export type RayonnementSignature = {
+    type: "rayonnement";
+    propagationBoost: number;
+};
+export type StabiliteSignature = {
+    type: "stabilite";
+    shield: number;
+};
+export type GarantieSignature = {
+    type: "garantie";
+    minBaseDeltaRatio: number;
+};
+export type PorteeSignature = {
+    type: "portee";
+    bridges: EventPropagationBridge[];
+};
+/** Temporary causal edge; resolved only for an eligible action (EVT-04). */
+export interface EventPropagationBridge {
+    from: SatelliteRef;
+    to: SatelliteRef;
+    w: number;
+    rationale: string;
+    triggerActionIds?: string[];
+}
+export type KeyEventSignature = AmplifierSignature | RayonnementSignature | StabiliteSignature | GarantieSignature | PorteeSignature;
+export interface KeyEventDefinition {
+    id: string;
+    alignment: "ally" | "adverse";
+    name: string;
+    shortDescription: string;
+    description: string;
+    origin: {
+        kind: "facet";
+        componentId: string;
+    };
+    /** Attribution of an adverse event, separate from its facet origin. */
+    originLabel?: string;
+    targetedActionIds: string[];
+    withinNextN: number;
+    signature: KeyEventSignature;
+}
+export declare function isAdverseKeyEvent(event: KeyEventDefinition): boolean;

package/dist/types/data/key-event-validation.d.ts

@@ -0,0 +1,11 @@
+import type { KeyEventDefinition } from "./key-event-types";
+import type { ActionDefinition } from "./yasuni_actions";
+import type { Composante } from "./yasuni_cause";
+export interface KeyEventDiagnostic {
+    eventId: string;
+    path: string;
+    message: string;
+}
+/** Read-only catalogue validation. No edge is ever added to the cause graph. */
+export declare function validateKeyEvents(events: readonly KeyEventDefinition[], actions: readonly ActionDefinition[], cause: readonly Composante[]): KeyEventDiagnostic[];
+export declare function formatKeyEventDiagnostics(diagnostics: readonly KeyEventDiagnostic[]): string;

package/dist/types/data/stability-shield.d.ts

@@ -19,3 +19,17 @@ export declare function applyStabilityShield(aggregatedDelta: number, shield: nu
  * bouclier plus faible ne dégrade jamais celui déjà en place.
  */
 export declare function mergeStabilityShield(current: number | undefined, incoming: number): number;
+/** Persisted scalar shields are always allied, irrespective of the last action. */
+export type ProtectedSign = 1 | -1;
+export type DirectionalShield = {
+    magnitude: number;
+    protectedSign: ProtectedSign;
+};
+export type StabilityProtection = number | DirectionalShield[];
+export declare function normalizeStabilityProtection(value: StabilityProtection | undefined): DirectionalShield[];
+export declare function mergeDirectionalShield(current: StabilityProtection | undefined, incoming: DirectionalShield): DirectionalShield[];
+/** Filter each signed aggregate once. No consumption and no cross-direction cancellation. */
+export declare function filterDirectionalContributions(positive: number, negative: number, protection: StabilityProtection): {
+    positive: number;
+    negative: number;
+};

package/dist/types/data/yasuni_adverse_key_events.d.ts

@@ -1,2 +1,2 @@
-import type { KeyEventDefinition } from "./yasuni_key_events";
+import type { KeyEventDefinition } from "./key-event-types";
 export declare const yasuniAdverseKeyEvents: KeyEventDefinition[];

package/dist/types/data/yasuni_cause.d.ts

@@ -26,6 +26,13 @@ export interface Composante {
     id: string;
     name: string;
     orientation?: "yin" | "yang";
+    /** Notion parente commune à des facettes d'orientations opposées (ex. la
+     *  Gouvernance, déclinée en une facette yin et une facette yang). Les
+     *  facettes qui la partagent sont regroupées dans la vue Idle « tab ». */
+    notion?: {
+        id: string;
+        name: string;
+    };
     /** Vue d'ensemble des enjeux et des dynamiques propres à cette composante. */
     description?: string;
     odds: ODD[];

package/dist/types/data/yasuni_key_events.d.ts

@@ -1,62 +1,6 @@
-export interface KeyEventEffect {
-    /**
-     * Bonus additif nominal au pic de la fenêtre. Pour un slot occupé éligible,
-     * pondération positionnelle avec plancher 0,15 ; aucun effet si la cible est
-     * absente ou hors fenêtre. Voir positionalBonus (amplifier-engine.ts).
-     * Appliqué dans la direction du delta effectif de l'action (après combos),
-     * jamais sur une action au delta nul. Additif et non multiplicatif : un
-     * ratio réduit par la position devenait fractionnaire et se faisait
-     * absorber par l'arrondi du poids ; un montant en points permet aussi à
-     * un futur malus (bonus négatif) de s'annuler exactement avec lui.
-     */
-    scoreBonus: number;
-    /**
-     * Bonus ADDITIF de poids (en points entiers), au pic de la fenêtre.
-     * Renforce le weightDelta de l'action ciblée dans sa propre direction
-     * (alléger ou alourdir) — sans effet sur une action sans weightDelta.
-     * L'arrondi à l'entier se fait par événement à l'évaluation, jamais sur
-     * un total fractionnaire : ce que la carte affiche est ce qui s'applique.
-     */
-    weightBonus: number;
-}
-export interface KeyEventDefinition {
-    id: string;
-    name: string;
-    shortDescription: string;
-    description: string;
-    /** Facette (Composante.id) depuis laquelle l'événement se déclenche. */
-    originComposanteId: string;
-    /**
-     * Actions amplifiées (par id), même logique que ComboCondition.requires.
-     * Cohérence thématique obligatoire avec la facette d'origine.
-     */
-    targetedActionIds: string[];
-    /**
-     * Fenêtre temporelle AVANT laquelle l'amplification s'arrête — pendant
-     * inverse de ComboCondition.withinLastN : une action ciblée jouée plus de
-     * withinNextN slots après l'événement n'est plus amplifiée. Oblige le
-     * joueur à réserver des emplacements libres après l'événement plutôt que
-     * de le placer systématiquement tout en bas de la pile.
-     */
-    withinNextN?: number;
-    effect: KeyEventEffect;
-    /** Acteur à l'origine d'un Événement adverse (pouvoir politique,
-     *  industrie…), affiché en note de provenance sur son bloc — les
-     *  Événements Clés positifs n'en ont pas (ils émanent de la cause). */
-    origin?: string;
-}
-/**
- * Un Événement adverse est une KeyEventDefinition ordinaire dont l'effet est
- * un MALUS (bonus négatifs) — même critère de signe qu'isAdverseAction, pas
- * un drapeau. Catalogue séparé (yasuni_adverse_key_events.ts), jamais listé
- * dans yasuniKeyEvents : le menu radial du cercle central et l'arbre
- * RECHERCHE, qui itèrent ce tableau, l'ignorent donc structurellement — seul
- * yasuniKeyEventMap (moteur, rendu de la pile) fusionne les deux catalogues.
- */
-export declare function isAdverseKeyEvent(keyEvent: KeyEventDefinition): boolean;
+import type { KeyEventDefinition } from "./key-event-types";
+export type * from "./key-event-types";
+export { isAdverseKeyEvent } from "./key-event-types";
 export declare const yasuniKeyEvents: KeyEventDefinition[];
-/** Lookup O(1) par id, même convention que les autres catalogues — fusionne
- *  Événements Clés ET Événements adverses : le moteur et le rendu de la pile
- *  résolvent les deux ici, tandis que les surfaces utilisateur (menu radial,
- *  arbre RECHERCHE) itèrent yasuniKeyEvents, sans les adverses. */
 export declare const yasuniKeyEventMap: Map<string, KeyEventDefinition>;
+export declare const yasuniKeyEventDiagnostics: import("./key-event-validation").KeyEventDiagnostic[];

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

@@ -16,14 +16,25 @@ export interface CauseOddCutting {
     score: number;
     weight: number;
 }
+/** Notion parente d'une facette : des facettes d'orientations opposées qui
+ *  la partagent en sont les déclinaisons yin et yang (regroupées dans la vue
+ *  Idle « tab »). */
+export interface FacetNotion {
+    id: string;
+    name: string;
+}
 export interface CauseComponent {
     id: string;
     name?: string;
     shortName?: string;
     description?: string;
     orientation: YinYangOrientation;
+    /** Notion parente (absente : la facette est seule de sa notion). */
+    notion?: FacetNotion;
     odds: CauseOdd[];
-    /** Somme brute des poids de tous les satellites de la facette. */
+    /** Poids de la facette (taille relative de son arc) : C_f, moyenne des
+     *  poids de TOUS ses satellites, zéros inclus, de 0 à 10 — même règle pour
+     *  une cause et pour un contact (`facetWeight`, POC-05A4). */
     perimeterWeight: number;
 }
 export interface Cause {

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

@@ -18,10 +18,17 @@ export interface IGraphicsStrategy {
         color: string;
         opacity: number;
     }[], gradientUnits: string): IGraphicElement;
+    /** Retire du <defs> les éléments (masques, dégradés…) portant ces ids. */
+    removeDefsByIds(ids: Iterable<string>): void;
     createYinOrYangArcMask(id: string, cx: number, cy: number, innerRadius: number, outerRadius: number, startAngle: number, endAngle: number, type: "yin" | "yang", blendOpacity?: number): string;
+    /** Met à jour en place un masque de createYinOrYangArcMask (frame de
+     *  transition) ; false s'il manque, l'appelant refait alors un rendu complet. */
+    updateYinOrYangArcMask(id: string, cx: number, cy: number, innerRadius: number, outerRadius: number, startAngle: number, endAngle: number, type: "yin" | "yang", blendOpacity?: number): boolean;
     createBorderMask(id: string, cx: number, cy: number, innerRadius: number, outerRadius: number): void;
-    changeBorderColors(gradient: any, duration: number, colors: string[]): void;
     drawLineWithGradient(parent: IGraphicElement, x1: number, y1: number, x2: number, y2: number, gradientId: string): void;
     createUnderlyingCircleGradient(id: string, color: string, spread?: number, intensity?: number): string;
-    createUnderlyingCircleWithArcMask(maskId: string | undefined, gradientId: string, parent: IGraphicElement, cx: number, cy: number, radius: number): void;
+    /** Repeint en place un dégradé de createUnderlyingCircleGradient ; false
+     *  s'il manque. */
+    updateUnderlyingCircleGradientColor(id: string, color: string, spread?: number, intensity?: number): boolean;
+    createUnderlyingCircleWithArcMask(maskId: string | undefined, gradientId: string, parent: IGraphicElement, cx: number, cy: number, radius: number): IGraphicElement;
 }

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

@@ -22,6 +22,20 @@ export type PropagationScope = "local" | "inter-odd" | "inter-facette";
 export type CompiledEdge = PropagationTarget & {
     from: SatelliteRef;
     scope: PropagationScope;
+    eventPropagation?: EventPropagationMetadata;
+};
+/** Explanatory provenance, preserved on applied hops and Bilan details. */
+export type EventPropagationMetadata = {
+    kind: "rayonnement" | "portee";
+    originalWeight: number;
+    sources: readonly {
+        eventId: string;
+        eventName: string;
+        sourceItemId: string;
+        strength: number;
+        parameter: number;
+        bridgeIndex?: number;
+    }[];
 };
 export type PropagationGraphRule = "V1" | "V2" | "V3" | "V4" | "V5" | "V6" | "V7";
 export type PropagationGraphDiagnostic = {

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

@@ -23,4 +23,14 @@ export interface IViewData {
      *  (voir YinYangDrawer.renderChildWeightGauge). Absent pour les patterns
      *  qui ne sont pas des satellites. */
     weight?: number;
+    /** Libellé de poids déjà formaté, affiché tel quel dans la pastille du
+     *  satellite au lieu de l'entier arrondi de `weight`. Posé pour les
+     *  satellites-facettes : c'est celui de l'arc de leur facette
+     *  (facetWeightLabel — « 5,5 » en règle `mean`, « 61 » en règle `sum`). */
+    weightLabel?: string;
+    /** Angle imposé (radians, repère SVG : 0 = 3 h, sens horaire) auquel ce
+     *  satellite se place autour de son parent, au lieu de la répartition
+     *  uniforme par index. Posé pour les satellites-facettes du sous-état
+     *  Idle « facettes », alignés sur le milieu de l'arc de leur facette. */
+    angleOverride?: number;
 }

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

@@ -10,6 +10,12 @@ export interface IYinYangController {
     factory: IYinYangAppFactory;
     animator: IAnimator;
     createYinYangChildren(): void;
+    /** Fin de vie : arrête toutes les boucles d'animation du contrôleur et de
+     *  ses satellites (champ de force, orbite, rotation, ghost, étincelles,
+     *  comètes…), déconnecte ses observers et libère ses defs. Le contrôleur
+     *  n'est plus utilisable ensuite. Idempotent. Le DOM du diagramme est
+     *  vidé par l'appelant (voir mountYinYang). */
+    destroy(): void;
     clearForceFieldDetails(): void;
     applyChildrenFitScale(): void;
     setChildrenEnabled(isEnabled: boolean): void;
@@ -122,9 +128,9 @@ export interface IYinYangController {
      * 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;
+    setKeyEventMenuDistanceOffset(offset: number): void;
+    setKeyEventMenuItemScale(scale: number): void;
+    setKeyEventIconFontScale(scale: number): void;
     /**
      * Sets maximum number of lines for child labels (1-3).
      */
@@ -136,6 +142,18 @@ export interface IYinYangController {
     setLabelShortMaxChars(chars: number): void;
     isChildrenEnabled(): boolean;
     isActionActive(): boolean;
+    /** Sous-état d'Idle : arcs pondérés ou un satellite yin/yang par facette. */
+    getIdleView(): "arcs" | "facettes" | "tab";
+    setIdleView(view: "arcs" | "facettes" | "tab"): Promise<void>;
+    /** Crochets de l'hôte autour du sous-état Idle « tab » (voir
+     *  YinYangController.setIdleTabHooks). */
+    setIdleTabHooks(hooks: {
+        beforeEnter?: () => Promise<void> | void;
+        afterLeave?: () => Promise<void> | void;
+    } | null): void;
+    setOnIdleViewChange(callback: ((view: "arcs" | "facettes" | "tab") => void) | null): void;
+    toggleIdleView(): Promise<void>;
+    isIdleFacettesActive(): boolean;
     /**
      * Sets font scale for action stack item labels.
      */
@@ -269,10 +287,10 @@ export interface IYinYangController {
     /** 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;
+    /** Called by YinYangDrawer when the user clicks the core of the facette's
+     *  dominant lobe (yin or yang, per Composante.orientation) while a Facette
+     *  is open — closes it and shows the cause in Idle « facettes ». */
+    onFacetteCoreClicked(): void;
     /** Wires a callback fired when the user clicks a composante border, cutting, or action in the diagram. */
     setOnDiagramNavChange(cb: (event: {
         type: "composante";

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

@@ -26,6 +26,11 @@ export interface YinYangComponentNode {
     label?: string;
     shortLabel?: string;
     orientation: YinYangOrientation;
+    /** Notion parente — voir `FacetNotion` (ICauseModel). */
+    notion?: {
+        id: string;
+        name: string;
+    };
     odds: YinYangOddNode[];
 }
 export interface YinYangInternalModel {

package/dist/types/main.d.ts

@@ -6,4 +6,3 @@ import "./styles/search.css";
 import "./styles/delta-chips.css";
 import "./styles/action-image.css";
 export * from "./api";
-import "./benchmark/runner";

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

@@ -0,0 +1,23 @@
+/**
+ * Facteur de taille maximal des icônes d'action pour qu'elles tiennent dans
+ * leur bulle (groupe debug "Grappe actions" › "Taille icônes").
+ *
+ * Les SVG partagent un viewBox 64×64 mais leur dessin n'occupe pas tous la
+ * même surface : certains (satellite, barrières flottantes…) remplissent les
+ * coins et débordaient du cercle de la bulle. On rastérise chaque icône une
+ * fois pour mesurer son rayon réel (trait compris), puis on en déduit le
+ * facteur au-delà duquel le dessin franchirait l'anneau.
+ */
+/** Taille de l'icône rapportée au rayon de la bulle, pour l'action active —
+ *  la plus grande des deux variantes rendues par ChildActionMenuController. */
+export declare const ACTIVE_ACTION_ICON_SIZE_RATIO = 1.85;
+export declare function scaleFittingExtent(extent: number): number;
+/** Plus grand facteur qui fait tenir toutes les icônes mesurées jusqu'ici
+ *  (Infinity tant qu'aucune ne l'a été). */
+export declare function getActionIconFitScale(): number;
+export declare function onActionIconFitScaleChange(listener: (fitScale: number) => void): () => void;
+/** Lance la mesure des icônes pas encore vues ; les abonnés sont prévenus
+ *  chaque fois que le facteur admissible baisse. La promesse se résout quand
+ *  toutes les icônes demandées sont mesurées, pour retoucher celles déjà
+ *  affichées. */
+export declare function measureActionIcons(urls: readonly string[]): Promise<void>;

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

@@ -1,4 +1,5 @@
-import { type CompiledPropagationGraph, type PropagationScope, type SatelliteKey } from "../interfaces/IPropagationGraph";
+import { type KeyEventPropagationContext } from "../data/key-event-propagation";
+import { type EventPropagationMetadata, type CompiledPropagationGraph, type PropagationScope, type SatelliteKey } from "../interfaces/IPropagationGraph";
 import { YinYangComponentNode } from "../interfaces/IYinYangInternalModel";
 export type Action = {
     id: string;
@@ -14,6 +15,7 @@ export type Action = {
  * ODD, autre facette — sont produites par le même parcours.
  */
 export type PropagatedActionEdge = {
+    eventPropagation?: EventPropagationMetadata;
     scope: PropagationScope;
     fromComponentId: string;
     toComponentId: string;
@@ -112,7 +114,7 @@ export type ActionPropagationDetails = ProjectedActionStateDetails & {
  * `allComponents` fournit l'état de base des autres facettes ; sans lui, les
  * sauts qui sortent de `component` sont ignorés.
  */
-export declare function computeActionPropagationDetails(component: YinYangComponentNode, graph: CompiledPropagationGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, allComponents?: readonly YinYangComponentNode[]): ActionPropagationDetails;
+export declare function computeActionPropagationDetails(component: YinYangComponentNode, graph: CompiledPropagationGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, allComponents?: readonly YinYangComponentNode[], eventPropagation?: KeyEventPropagationContext): ActionPropagationDetails;
 /**
  * Arrivée dans `component` d'une arête venue d'une autre composante, déjà
  * calculée par la résolution de l'action (voir computeActionPropagationDetails).
@@ -141,6 +143,6 @@ export type IncomingLocalContinuation = {
  * autre ODD de la même composante est poursuivie comme une arête locale.
  */
 export declare function computeIncomingLocalContinuation(component: YinYangComponentNode, entry: IncomingPropagationEntry, graph: CompiledPropagationGraph): IncomingLocalContinuation;
-export declare function propagateForceFieldActionInComponent(component: YinYangComponentNode, graph: CompiledPropagationGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, allComponents?: readonly YinYangComponentNode[]): PropagatedActionEdge[];
-export declare function projectActionStateDetailsInComponent(component: YinYangComponentNode, graph: CompiledPropagationGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, allComponents?: readonly YinYangComponentNode[]): ProjectedActionStateDetails;
+export declare function propagateForceFieldActionInComponent(component: YinYangComponentNode, graph: CompiledPropagationGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, allComponents?: readonly YinYangComponentNode[], eventPropagation?: KeyEventPropagationContext): PropagatedActionEdge[];
+export declare function projectActionStateDetailsInComponent(component: YinYangComponentNode, graph: CompiledPropagationGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, allComponents?: readonly YinYangComponentNode[], eventPropagation?: KeyEventPropagationContext): ProjectedActionStateDetails;
 export {};

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

@@ -5,9 +5,58 @@ 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.
+ *
+ * ⚠️ FACETTES D'UN CONTACT : cette règle est reproduite à l'identique par
+ * yvy-backend (`src/contacts/contact-facets.ts`), qui fait autorité pour le
+ * jeu. Deux implémentations à maintenir identiques : toute évolution met à
+ * jour les deux, ainsi que le fichier de cas commun
+ * `src/data/contacts/contact-facets.reference.json` (POC-05A2).
  */
 export declare function tensionFromCuttings(cuttingScores: number[], cuttingWeights?: number[]): number;
 export declare const oddTensionFromCuttings: typeof tensionFromCuttings;
+/**
+ * RÈGLE DES POIDS DE FACETTE, commutable pour comparaison (debug de la page
+ * standalone, clé localStorage `spheres.facetWeightRule`) :
+ *  - `mean` (défaut, POC-05A4) : C_f = moyenne des poids de tous les
+ *    satellites ; Q_f = moyenne pondérée sur tous les satellites, repli sur
+ *    leur moyenne simple ;
+ *  - `sum` (ancienne règle) : poids = somme des poids ; Q_f = tension de
+ *    chaque catégorie pondérée par la somme de ses poids, repli par
+ *    catégorie sur son nombre de satellites.
+ * La lib npm reste en `mean` : seule la page standalone la change.
+ */
+export type FacetWeightRule = "mean" | "sum";
+export declare function getFacetWeightRule(): FacetWeightRule;
+export declare function setFacetWeightRule(rule: FacetWeightRule): void;
+/** Satellites d'une catégorie (ODD) d'une facette : tensions et poids. */
+interface FacetOddCuttings {
+    cuttingScores: readonly number[];
+    cuttingWeights: readonly number[];
+}
+/**
+ * Tension d'une FACETTE (cause ou contact). Règle `mean` (POC-05A4) :
+ * `tensionFromCuttings` sur TOUS ses satellites, catégories confondues —
+ * moyenne pondérée par les poids, ou moyenne simple de la facette si tous
+ * ses poids sont nuls. Règle `sum` : voir `FacetWeightRule`.
+ * Q_f = (1 − T) × 100. `cuttingTensions` remplace les tensions de la
+ * catégorie d'indice donné (projection d'une action) ; une catégorie dont
+ * les poids ne sont pas alignés sur les scores compte ses satellites à 1.
+ * Facette sans satellite : 0,5.
+ */
+export declare function facetTensionFromOdds(odds: readonly FacetOddCuttings[], cuttingTensions?: (oddIndex: number) => readonly number[] | undefined): number;
+/**
+ * POIDS d'une facette — ou d'une catégorie, pour sa pastille. Règle `mean`
+ * (défaut, POC-05A4) : C_f, moyenne arithmétique des poids (bornés à 0) de
+ * TOUS ses satellites, zéros inclus, de 0 à 10, indépendante de leur nombre.
+ * Règle `sum` : leur somme. Fixe la taille des arcs de facette et la valeur
+ * des pastilles. Facettes d'un contact, règle `mean` : reproduite à
+ * l'identique par yvy-backend (`contactFacetWeights`), cas communs dans
+ * `src/data/contacts/contact-facets.reference.json`.
+ */
+export declare function facetWeight(weights: readonly number[]): number;
+/** Plafond de `facetWeight` pour `count` satellites : 10 (`mean`) ou
+ *  `count × 10` (`sum`). */
+export declare function facetWeightMax(count: number): number;
 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
@@ -24,3 +73,4 @@ export declare function clampWeight(value: number): number;
  * signe — ex: +1 sur un satellite déjà à WEIGHT_MAX ne change rien.
  */
 export declare function effectiveWeightDelta(currentWeight: number, delta: number): number;
+export {};

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

@@ -1,3 +1,80 @@
+export type DetailDensity = "full" | "reduced" | "compact";
+export interface DetailDensityInput {
+    /** Hauteur visible du conteneur (clientHeight). */
+    available: number;
+    /** Hauteur de la description dépliée (0 si aucune). */
+    descFullH: number;
+    /** Hauteur de la description repliée (= descFullH si l'utilisateur l'a dépliée). */
+    descFoldedH: number;
+    /** Habillage d'un bloc hors carte (marges, en-têtes du bloc). */
+    chrome: number;
+    /** Nombre de blocs de cartes affichés. */
+    blockCount: number;
+    /** Hauteur occupée par le reste du contenu (ni description ni bloc). */
+    other?: number;
+    /** Palier précédent, pour l'hystérésis. */
+    previous?: DetailDensity | null;
+}
+export interface DetailDensityResult {
+    density: DetailDensity;
+    /** null = hauteur de carte par défaut (pas de variable posée). */
+    cardHeight: number | null;
+    foldDesc: boolean;
+}
+/**
+ * Choisit la densité d'une colonne de détail d'après la hauteur réellement
+ * libre — pas d'après le nombre de panneaux ouverts :
+ * - full    : description entière et cartes au format nominal (352px) ;
+ * - reduced : description repliée sur une ligne, cartes réduites
+ *             (≥ REDUCED_MIN_CARD_HEIGHT), haut de l'illustration visible ;
+ * - compact : description repliée, cartes au plus court, haut de
+ *             l'illustration visible.
+ * Au-delà de deux blocs, on vise deux blocs visibles et le scroll prend le
+ * relais (même règle que l'ancien comportement multi-blocs).
+ */
+export declare function computeDetailDensity(input: DetailDensityInput): DetailDensityResult;
+export interface StackCardHeightInput {
+    /** Hauteur utile du conteneur (clientHeight moins ses paddings). */
+    available: number;
+    /** Habillage (en-tête, description, marges) de chaque bloc déplié, dans
+     *  l'ordre d'affichage. */
+    expandedChromes: number[];
+    /** Hauteur de tout le reste : blocs repliés, bandeau Σ. */
+    other: number;
+    previous?: DetailDensity | null;
+}
+/**
+ * STACK : hauteur des cartes pour que les blocs dépliés remplissent la place
+ * libre. Jusqu'à deux blocs dépliés, tout le panneau (blocs repliés et
+ * bandeau Σ compris) doit tenir ; au-delà, on vise les deux premiers blocs
+ * et le scroll prend le relais. La carte ne dépasse jamais le format nominal
+ * (image entière) : au-delà, il ne resterait que du vide autour de l'image.
+ */
+export declare function computeStackCardHeight(input: StackCardHeightInput): {
+    density: DetailDensity;
+    cardHeight: number | null;
+};
+export interface ChainCardHeightOptions {
+    blockSelector?: string;
+    /**
+     * RECHERCHE : ajuste les cartes à la hauteur libre du conteneur même avec un
+     * seul bloc (description comprise) et pose data-density. Sans cette option
+     * (STACK), seul le cas « 2 blocs ou plus » réduit les cartes.
+     */
+    fitToContainer?: boolean;
+    /**
+     * STACK : ajuste les cartes à la place libre en tenant compte des blocs
+     * repliés et du bandeau Σ (voir computeStackCardHeight), et pose
+     * data-density.
+     */
+    fitBlocks?: boolean;
+}
+/**
+ * Synchro immédiate d'un conteneur surveillé (watchChainCardHeight), avec ses
+ * options : à appeler au sein d'une bascule animée, pour que la hauteur
+ * finale mesurée tienne compte des cartes recalées. Sans effet sinon.
+ */
+export declare function resyncChainCardHeightNow(container: HTMLElement): void;
 /**
  * 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.
@@ -6,7 +83,9 @@
  * 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.
+ * action-image.css) : c'est la hauteur qui cède, jamais le cadrage — sauf
+ * avec `fitToContainer`, où la carte réduite garde le haut de l'image.
+ * Avec `fitToContainer` (RECHERCHE), voir computeDetailDensity.
  *
  * 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,
@@ -15,13 +94,17 @@
  * `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;
+export declare function syncChainCardHeight(container: HTMLElement, options?: ChainCardHeightOptions): 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
+ * où le bloc secondaire propagé apparaît/disparaît). Avec `fitToContainer`,
+ * le sous-arbre est aussi observé : une description remplacée ou des cartes
+ * re-rendues changent la place disponible. Seules les insertions/retraits de
+ * nœuds sont observés (pas les attributs) : les classes et styles posés par
+ * la synchro elle-même ne la redéclenchent donc pas. Idempotent : un seul
  * couple d'observers est installé par conteneur.
  */
-export declare function watchChainCardHeight(container: HTMLElement, blockSelector?: string): void;
+export declare function watchChainCardHeight(container: HTMLElement, options?: ChainCardHeightOptions): void;