@fullstackcraftllc/floe 0.0.15 → 0.0.17

package/dist/exposure/index.d.ts

@@ -1,17 +1,22 @@
-import { OptionChain, ExposurePerExpiry, IVSurface } from '../types';
+import { OptionChain, ExposureVariantsPerExpiry, ExposureCalculationOptions, IVSurface } from '../types';
 /**
- * Calculate Gamma, Vanna, and Charm exposures for an option chain
+ * Calculate canonical, state-weighted, and flow-delta exposure variants.
  *
- * @param chain - Option chain with market context (spot, rates, options)
- * @param ivSurfaces - IV surfaces for all expirations
- * @returns Array of exposure metrics per expiration
+ * canonical:
+ * - GEX: dollars per 1% underlying move
+ * - VEX: dollars per 1 vol-point move
+ * - CEX: dollars per 1 day of time decay
  *
- * @example
- * ```typescript
- * const exposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * ```
+ * stateWeighted:
+ * - Gamma: same as canonical (spot is already the state variable)
+ * - Vanna: canonical vanna weighted by strike IV level
+ * - Charm: canonical charm weighted by days-to-expiration
+ *
+ * flowDelta:
+ * - Canonical exposure formulas using OI deltas:
+ *   (liveOpenInterest - openInterest)
  */
-export declare function calculateGammaVannaCharmExposures(chain: OptionChain, ivSurfaces: IVSurface[]): ExposurePerExpiry[];
+export declare function calculateGammaVannaCharmExposures(chain: OptionChain, ivSurfaces: IVSurface[], options?: ExposureCalculationOptions): ExposureVariantsPerExpiry[];
 /**
  * Calculate shares needed to cover net exposure
  *

package/dist/exposure/index.js

@@ -6,70 +6,62 @@ const types_1 = require("../types");
 const blackscholes_1 = require("../blackscholes");
 const volatility_1 = require("../volatility");
 /**
- * Calculate Gamma, Vanna, and Charm exposures for an option chain
+ * Calculate canonical, state-weighted, and flow-delta exposure variants.
  *
- * @param chain - Option chain with market context (spot, rates, options)
- * @param ivSurfaces - IV surfaces for all expirations
- * @returns Array of exposure metrics per expiration
+ * canonical:
+ * - GEX: dollars per 1% underlying move
+ * - VEX: dollars per 1 vol-point move
+ * - CEX: dollars per 1 day of time decay
  *
- * @example
- * ```typescript
- * const exposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * ```
+ * stateWeighted:
+ * - Gamma: same as canonical (spot is already the state variable)
+ * - Vanna: canonical vanna weighted by strike IV level
+ * - Charm: canonical charm weighted by days-to-expiration
+ *
+ * flowDelta:
+ * - Canonical exposure formulas using OI deltas:
+ *   (liveOpenInterest - openInterest)
  */
-function calculateGammaVannaCharmExposures(chain, ivSurfaces) {
-    const { spot, riskFreeRate, dividendYield, options } = chain;
+function calculateGammaVannaCharmExposures(chain, ivSurfaces, options = {}) {
+    const { spot, riskFreeRate, dividendYield, options: chainOptions } = chain;
+    const asOfTimestamp = options.asOfTimestamp ?? Date.now();
     const exposureRows = [];
-    // Get unique expirations from options
     const expirationsSet = new Set();
-    for (const option of options) {
+    for (const option of chainOptions) {
         expirationsSet.add(option.expirationTimestamp);
     }
     const expirations = Array.from(expirationsSet).sort((a, b) => a - b);
-    // Loop through all expirations
+    const putOptionsByKey = new Map();
+    for (const option of chainOptions) {
+        if (option.optionType === 'put') {
+            putOptionsByKey.set(getOptionKey(option.expirationTimestamp, option.strike), option);
+        }
+    }
     for (const expiration of expirations) {
-        // Skip any expiration that is in the past
-        if (expiration < Date.now()) {
+        if (expiration < asOfTimestamp) {
+            continue;
+        }
+        const timeToExpirationInYears = (expiration - asOfTimestamp) / types_1.MILLISECONDS_PER_YEAR;
+        if (timeToExpirationInYears <= 0) {
             continue;
         }
-        // Reset totals for this expiration
-        let totalGammaExposure = 0.0;
-        let totalVannaExposure = 0.0;
-        let totalCharmExposure = 0.0;
-        let strikeOfMaxGamma = 0.0;
-        let strikeOfMinGamma = 0.0;
-        let strikeOfMaxVanna = 0.0;
-        let strikeOfMinVanna = 0.0;
-        let strikeOfMaxCharm = 0.0;
-        let strikeOfMinCharm = 0.0;
-        let strikeOfMaxNet = 0.0;
-        let strikeOfMinNet = 0.0;
-        const strikeExposures = [];
-        // Process all call options first
-        for (const callOption of options) {
-            // Check if this option is at the expiration we are looking at
-            if (callOption.expirationTimestamp !== expiration || callOption.optionType === 'put') {
+        const timeToExpirationInDays = Math.max(timeToExpirationInYears * types_1.DAYS_PER_YEAR, 0);
+        const strikeExposureVariants = [];
+        for (const callOption of chainOptions) {
+            if (callOption.expirationTimestamp !== expiration || callOption.optionType !== 'call') {
                 continue;
             }
-            // Get the corresponding put option
-            const putOption = options.find((opt) => opt.expirationTimestamp === expiration &&
-                opt.optionType === 'put' &&
-                opt.strike === callOption.strike);
+            const putOption = putOptionsByKey.get(getOptionKey(expiration, callOption.strike));
             if (!putOption) {
-                continue; // Skip if no matching put
+                continue;
             }
-            // Get IV for this strike and expiry from the surface
-            const callIVAtStrike = (0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'call', callOption.strike);
-            const putIVAtStrike = (0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'put', putOption.strike);
-            // Get time to expiration in years
-            const timeToExpirationInYears = (0, blackscholes_1.getTimeToExpirationInYears)(expiration);
-            // Calculate Greeks for both call and put
-            // Rates are already decimals in OptionChain, IV from surface is percentage
+            const callIVAtStrike = resolveIVPercent((0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'call', callOption.strike), callOption.impliedVolatility);
+            const putIVAtStrike = resolveIVPercent((0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'put', putOption.strike), putOption.impliedVolatility);
             const callGreeks = (0, blackscholes_1.calculateGreeks)({
                 spot,
                 strike: callOption.strike,
                 timeToExpiry: timeToExpirationInYears,
-                volatility: callIVAtStrike / 100.0, // Convert from percentage to decimal
+                volatility: callIVAtStrike / 100.0,
                 riskFreeRate,
                 dividendYield,
                 optionType: 'call',
@@ -83,74 +75,33 @@ function calculateGammaVannaCharmExposures(chain, ivSurfaces) {
                 dividendYield,
                 optionType: 'put',
             });
-            // Calculate exposures from dealer perspective
-            // Dealer is short calls (negative gamma) and long puts (positive gamma)
-            // Multiply by 100 for contract size, multiply by spot for dollar exposure
-            // Multiply by 0.01 for 1% move sensitivity
-            // Gamma: second order with respect to price twice
-            const gammaExposureForStrike = -callOption.openInterest * callGreeks.gamma * (spot * 100.0) * spot * 0.01 +
-                putOption.openInterest * putGreeks.gamma * (spot * 100.0) * spot * 0.01;
-            // Vanna: second order with respect to price and volatility
-            const vannaExposureForStrike = -callOption.openInterest * callGreeks.vanna * (spot * 100.0) * callIVAtStrike * 0.01 +
-                putOption.openInterest * putGreeks.vanna * (spot * 100.0) * putIVAtStrike * 0.01;
-            // Charm: second order with respect to price and time
-            // Already normalized per day in calculateGreeks
-            const charmExposureForStrike = -callOption.openInterest * callGreeks.charm * (spot * 100.0) * types_1.DAYS_PER_YEAR * timeToExpirationInYears +
-                putOption.openInterest * putGreeks.charm * (spot * 100.0) * types_1.DAYS_PER_YEAR * timeToExpirationInYears;
-            // NaN checks
-            const gammaExposure = isNaN(gammaExposureForStrike) ? 0.0 : gammaExposureForStrike;
-            const vannaExposure = isNaN(vannaExposureForStrike) ? 0.0 : vannaExposureForStrike;
-            const charmExposure = isNaN(charmExposureForStrike) ? 0.0 : charmExposureForStrike;
-            // Add to totals
-            totalGammaExposure += gammaExposure;
-            totalVannaExposure += vannaExposure;
-            totalCharmExposure += charmExposure;
-            // Add to strike exposures
-            strikeExposures.push({
+            const callOpenInterest = sanitizeFinite(callOption.openInterest);
+            const putOpenInterest = sanitizeFinite(putOption.openInterest);
+            const canonical = calculateCanonicalVector(spot, callOpenInterest, putOpenInterest, callGreeks.gamma, putGreeks.gamma, callGreeks.vanna, putGreeks.vanna, callGreeks.charm, putGreeks.charm);
+            const stateWeighted = calculateStateWeightedVector(spot, callOpenInterest, putOpenInterest, callGreeks.vanna, putGreeks.vanna, callGreeks.charm, putGreeks.charm, callIVAtStrike, putIVAtStrike, timeToExpirationInDays, canonical.gammaExposure);
+            const callFlowDelta = resolveFlowDeltaOpenInterest(callOption.openInterest, callOption.liveOpenInterest);
+            const putFlowDelta = resolveFlowDeltaOpenInterest(putOption.openInterest, putOption.liveOpenInterest);
+            const flowDelta = calculateCanonicalVector(spot, callFlowDelta, putFlowDelta, callGreeks.gamma, putGreeks.gamma, callGreeks.vanna, putGreeks.vanna, callGreeks.charm, putGreeks.charm);
+            strikeExposureVariants.push({
                 strikePrice: callOption.strike,
-                gammaExposure,
-                vannaExposure,
-                charmExposure,
-                netExposure: gammaExposure + vannaExposure + charmExposure,
+                canonical,
+                stateWeighted,
+                flowDelta,
             });
         }
-        if (strikeExposures.length === 0) {
-            continue; // No options for this expiration
+        if (strikeExposureVariants.length === 0) {
+            continue;
         }
-        // Sort by gamma exposure and find extremes
-        strikeExposures.sort((a, b) => b.gammaExposure - a.gammaExposure);
-        strikeOfMaxGamma = strikeExposures[0].strikePrice;
-        strikeOfMinGamma = strikeExposures[strikeExposures.length - 1].strikePrice;
-        // Sort by vanna exposure and find extremes
-        strikeExposures.sort((a, b) => b.vannaExposure - a.vannaExposure);
-        strikeOfMaxVanna = strikeExposures[0].strikePrice;
-        strikeOfMinVanna = strikeExposures[strikeExposures.length - 1].strikePrice;
-        // Sort by charm exposure and find extremes
-        strikeExposures.sort((a, b) => b.charmExposure - a.charmExposure);
-        strikeOfMaxCharm = strikeExposures[0].strikePrice;
-        strikeOfMinCharm = strikeExposures[strikeExposures.length - 1].strikePrice;
-        // Sort by net exposure and find extremes
-        strikeExposures.sort((a, b) => b.netExposure - a.netExposure);
-        strikeOfMaxNet = strikeExposures[0].strikePrice;
-        strikeOfMinNet = strikeExposures[strikeExposures.length - 1].strikePrice;
-        const totalNetExposure = totalGammaExposure + totalVannaExposure + totalCharmExposure;
-        // Add exposure row
+        const canonical = buildModeBreakdown(strikeExposureVariants, 'canonical');
+        const stateWeighted = buildModeBreakdown(strikeExposureVariants, 'stateWeighted');
+        const flowDelta = buildModeBreakdown(strikeExposureVariants, 'flowDelta');
         exposureRows.push({
             spotPrice: spot,
             expiration,
-            totalGammaExposure,
-            totalVannaExposure,
-            totalCharmExposure,
-            totalNetExposure,
-            strikeOfMaxGamma,
-            strikeOfMinGamma,
-            strikeOfMaxVanna,
-            strikeOfMinVanna,
-            strikeOfMaxCharm,
-            strikeOfMinCharm,
-            strikeOfMaxNet,
-            strikeOfMinNet,
-            strikeExposures
+            canonical,
+            stateWeighted,
+            flowDelta,
+            strikeExposureVariants,
         });
     }
     return exposureRows;
@@ -210,3 +161,110 @@ function calculateSharesNeededToCover(sharesOutstanding, totalNetExposure, under
         resultingSpotToCover: resultingPrice,
     };
 }
+function getOptionKey(expiration, strike) {
+    return `${expiration}:${strike}`;
+}
+function calculateCanonicalVector(spot, callPosition, putPosition, callGamma, putGamma, callVanna, putVanna, callCharm, putCharm) {
+    const gammaExposure = -callPosition * callGamma * (spot * 100.0) * spot * 0.01 +
+        putPosition * putGamma * (spot * 100.0) * spot * 0.01;
+    const vannaExposure = -callPosition * callVanna * (spot * 100.0) * 0.01 +
+        putPosition * putVanna * (spot * 100.0) * 0.01;
+    const charmExposure = -callPosition * callCharm * (spot * 100.0) +
+        putPosition * putCharm * (spot * 100.0);
+    return sanitizeVector({
+        gammaExposure,
+        vannaExposure,
+        charmExposure,
+        netExposure: gammaExposure + vannaExposure + charmExposure,
+    });
+}
+function calculateStateWeightedVector(spot, callPosition, putPosition, callVanna, putVanna, callCharm, putCharm, callIVPercent, putIVPercent, timeToExpirationInDays, canonicalGammaExposure) {
+    const callIVLevel = Math.max(callIVPercent * 0.01, 0);
+    const putIVLevel = Math.max(putIVPercent * 0.01, 0);
+    // Gamma already uses instantaneous price scaling in canonical GEX.
+    const gammaExposure = canonicalGammaExposure;
+    const vannaExposure = -callPosition * callVanna * (spot * 100.0) * 0.01 * callIVLevel +
+        putPosition * putVanna * (spot * 100.0) * 0.01 * putIVLevel;
+    const canonicalCharmComponent = -callPosition * callCharm * (spot * 100.0) +
+        putPosition * putCharm * (spot * 100.0);
+    const charmExposure = canonicalCharmComponent * Math.max(timeToExpirationInDays, 0);
+    return sanitizeVector({
+        gammaExposure,
+        vannaExposure,
+        charmExposure,
+        netExposure: gammaExposure + vannaExposure + charmExposure,
+    });
+}
+function resolveFlowDeltaOpenInterest(openInterest, liveOpenInterest) {
+    if (typeof liveOpenInterest !== 'number' || !isFinite(liveOpenInterest)) {
+        return 0;
+    }
+    return sanitizeFinite(liveOpenInterest - openInterest);
+}
+function resolveIVPercent(ivFromSurface, optionImpliedVolatilityDecimal) {
+    if (isFinite(ivFromSurface) && ivFromSurface > 0) {
+        return ivFromSurface;
+    }
+    const fallback = optionImpliedVolatilityDecimal * 100.0;
+    if (isFinite(fallback) && fallback > 0) {
+        return fallback;
+    }
+    return 0;
+}
+function buildModeBreakdown(strikeExposureVariants, mode) {
+    const strikeExposures = strikeExposureVariants.map((strike) => ({
+        strikePrice: strike.strikePrice,
+        ...strike[mode],
+    }));
+    if (strikeExposures.length === 0) {
+        return {
+            totalGammaExposure: 0,
+            totalVannaExposure: 0,
+            totalCharmExposure: 0,
+            totalNetExposure: 0,
+            strikeOfMaxGamma: 0,
+            strikeOfMinGamma: 0,
+            strikeOfMaxVanna: 0,
+            strikeOfMinVanna: 0,
+            strikeOfMaxCharm: 0,
+            strikeOfMinCharm: 0,
+            strikeOfMaxNet: 0,
+            strikeOfMinNet: 0,
+            strikeExposures: [],
+        };
+    }
+    const totalGammaExposure = strikeExposures.reduce((sum, s) => sum + s.gammaExposure, 0);
+    const totalVannaExposure = strikeExposures.reduce((sum, s) => sum + s.vannaExposure, 0);
+    const totalCharmExposure = strikeExposures.reduce((sum, s) => sum + s.charmExposure, 0);
+    const totalNetExposure = totalGammaExposure + totalVannaExposure + totalCharmExposure;
+    const byGamma = [...strikeExposures].sort((a, b) => b.gammaExposure - a.gammaExposure);
+    const byVanna = [...strikeExposures].sort((a, b) => b.vannaExposure - a.vannaExposure);
+    const byCharm = [...strikeExposures].sort((a, b) => b.charmExposure - a.charmExposure);
+    const byNet = [...strikeExposures].sort((a, b) => b.netExposure - a.netExposure);
+    return {
+        totalGammaExposure: sanitizeFinite(totalGammaExposure),
+        totalVannaExposure: sanitizeFinite(totalVannaExposure),
+        totalCharmExposure: sanitizeFinite(totalCharmExposure),
+        totalNetExposure: sanitizeFinite(totalNetExposure),
+        strikeOfMaxGamma: byGamma[0].strikePrice,
+        strikeOfMinGamma: byGamma[byGamma.length - 1].strikePrice,
+        strikeOfMaxVanna: byVanna[0].strikePrice,
+        strikeOfMinVanna: byVanna[byVanna.length - 1].strikePrice,
+        strikeOfMaxCharm: byCharm[0].strikePrice,
+        strikeOfMinCharm: byCharm[byCharm.length - 1].strikePrice,
+        strikeOfMaxNet: byNet[0].strikePrice,
+        strikeOfMinNet: byNet[byNet.length - 1].strikePrice,
+        strikeExposures: byNet,
+    };
+}
+function sanitizeVector(vector) {
+    return {
+        gammaExposure: sanitizeFinite(vector.gammaExposure),
+        vannaExposure: sanitizeFinite(vector.vannaExposure),
+        charmExposure: sanitizeFinite(vector.charmExposure),
+        netExposure: sanitizeFinite(vector.netExposure),
+    };
+}
+function sanitizeFinite(value) {
+    return isFinite(value) && !isNaN(value) ? value : 0;
+}

package/dist/hedgeflow/index.d.ts

@@ -1,9 +1,11 @@
 import { ExposurePerExpiry, IVSurface } from '../types';
 import { HedgeImpulseConfig, CharmIntegralConfig, HedgeFlowAnalysis } from './types';
 export type { MarketRegime, RegimeParams, HedgeImpulseConfig, HedgeImpulsePoint, HedgeImpulseCurve, ZeroCrossing, ImpulseExtremum, DirectionalAsymmetry, ImpulseRegime, CharmIntegralConfig, CharmBucket, CharmIntegral, HedgeFlowAnalysis, } from './types';
+export type { HedgeContractEstimates, PressureZone, RegimeEdge, PressureLevel, PressureCloudConfig, PressureCloud, } from './pressurecloud';
 export { deriveRegimeParams, interpolateIVAtStrike } from './regime';
 export { computeHedgeImpulseCurve } from './curve';
 export { computeCharmIntegral } from './charm';
+export { computePressureCloud } from './pressurecloud';
 /**
  * Compute a complete hedge flow analysis for a single expiration.
  *

package/dist/hedgeflow/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeCharmIntegral = exports.computeHedgeImpulseCurve = exports.interpolateIVAtStrike = exports.deriveRegimeParams = void 0;
+exports.computePressureCloud = exports.computeCharmIntegral = exports.computeHedgeImpulseCurve = exports.interpolateIVAtStrike = exports.deriveRegimeParams = void 0;
 exports.analyzeHedgeFlow = analyzeHedgeFlow;
 const regime_1 = require("./regime");
 const curve_1 = require("./curve");
@@ -14,6 +14,9 @@ var curve_2 = require("./curve");
 Object.defineProperty(exports, "computeHedgeImpulseCurve", { enumerable: true, get: function () { return curve_2.computeHedgeImpulseCurve; } });
 var charm_2 = require("./charm");
 Object.defineProperty(exports, "computeCharmIntegral", { enumerable: true, get: function () { return charm_2.computeCharmIntegral; } });
+// Re-export pressure cloud
+var pressurecloud_1 = require("./pressurecloud");
+Object.defineProperty(exports, "computePressureCloud", { enumerable: true, get: function () { return pressurecloud_1.computePressureCloud; } });
 /**
  * Compute a complete hedge flow analysis for a single expiration.
  *

package/dist/hedgeflow/pressurecloud.d.ts

@@ -0,0 +1,166 @@
+import { HedgeImpulseCurve } from './types';
+import { RegimeParams } from './types';
+/**
+ * Expected dealer hedge volume in futures contracts for a 1-point spot move.
+ * Positive = dealers buying, negative = dealers selling.
+ */
+export interface HedgeContractEstimates {
+    /** E-mini Nasdaq 100 (multiplier: 20) */
+    nq: number;
+    /** Micro E-mini Nasdaq 100 (multiplier: 2) */
+    mnq: number;
+    /** E-mini S&P 500 (multiplier: 50) */
+    es: number;
+    /** Micro E-mini S&P 500 (multiplier: 5) */
+    mes: number;
+}
+/**
+ * A zone where price is likely to stabilize (positive impulse)
+ * or accelerate (negative impulse).
+ */
+export interface PressureZone {
+    /** Center price of the zone (peak of the impulse) */
+    center: number;
+    /** Lower bound of the zone (25th percentile of the peak width) */
+    lower: number;
+    /** Upper bound of the zone (75th percentile of the peak width) */
+    upper: number;
+    /** Normalized strength 0-1 (relative to the strongest zone found) */
+    strength: number;
+    /** Whether this zone is above or below current spot */
+    side: 'above-spot' | 'below-spot';
+    /**
+     * Trade type this zone favors:
+     * - Stability zones below spot → long (buy the bounce)
+     * - Stability zones above spot → short (sell the rejection)
+     * - Acceleration zones below spot → short (momentum downside)
+     * - Acceleration zones above spot → long (momentum upside / squeeze)
+     */
+    tradeType: 'long' | 'short';
+    /**
+     * Hedge execution type:
+     * - passive: dealers post resting limit orders (positive gamma → absorption)
+     * - aggressive: dealers send market orders (negative gamma → sweeping)
+     */
+    hedgeType: 'passive' | 'aggressive';
+}
+/**
+ * A regime boundary where behavior flips between mean-reverting and trend-amplifying.
+ */
+export interface RegimeEdge {
+    /** Price at which the impulse curve crosses zero */
+    price: number;
+    /** Direction of the transition relative to a downward price move */
+    transitionType: 'stable-to-unstable' | 'unstable-to-stable';
+}
+/**
+ * Per-price-level detail for the full pressure overlay.
+ */
+export interface PressureLevel {
+    /** Price level */
+    price: number;
+    /**
+     * Stability score: positive means mean-reverting pressure at this level.
+     * Higher = stronger buffering. Weighted by proximity to spot.
+     */
+    stabilityScore: number;
+    /**
+     * Acceleration score: positive means trend-amplifying pressure at this level.
+     * Higher = stronger momentum fuel. Weighted by proximity to spot.
+     */
+    accelerationScore: number;
+    /**
+     * Expected signed hedge contracts (positive = dealers buy, negative = dealers sell)
+     * for a 1-point spot move toward this level. Units depend on product.
+     * @deprecated Use hedgeContracts instead for multi-product estimates.
+     */
+    expectedHedgeContracts: number;
+    /** Multi-product hedge contract estimates */
+    hedgeContracts: HedgeContractEstimates;
+    /**
+     * Whether dealers would hedge passively (limit orders / absorption)
+     * or aggressively (market orders / sweeping) at this level.
+     */
+    hedgeType: 'passive' | 'aggressive';
+}
+/**
+ * Configuration for pressure cloud computation.
+ */
+export interface PressureCloudConfig {
+    /**
+     * Product multiplier for contract conversion.
+     * NQ = 20, MNQ = 2, ES = 50, MES = 5, SPY = 100 (shares).
+     * Default: 20 (NQ)
+     */
+    contractMultiplier?: number;
+    /** Product type hint for primary contract display. Default: 'NQ' */
+    product?: 'NQ' | 'MNQ' | 'ES' | 'MES' | 'SPY';
+    /**
+     * How many expected-daily-moves to consider "reachable".
+     * Levels beyond this get heavily penalized. Default: 2.0
+     */
+    reachabilityMultiple?: number;
+    /**
+     * Minimum impulse magnitude (as fraction of mean abs impulse) to
+     * qualify as a zone. Default: 0.15
+     */
+    zoneThreshold?: number;
+}
+/**
+ * Complete pressure cloud analysis combining stability and acceleration zones.
+ */
+export interface PressureCloud {
+    /** Current spot price */
+    spot: number;
+    /** Expiration timestamp */
+    expiration: number;
+    /** Timestamp when this cloud was computed */
+    computedAt: number;
+    /**
+     * Stability zones: levels where positive dealer impulse creates
+     * mean-reverting pressure. Price decelerates into these zones.
+     * Trade approach: reversal / bounce entries.
+     */
+    stabilityZones: PressureZone[];
+    /**
+     * Acceleration zones: levels where negative dealer impulse creates
+     * trend-amplifying pressure. Price accelerates through these zones.
+     * Trade approach: momentum / breakout continuation.
+     */
+    accelerationZones: PressureZone[];
+    /**
+     * Regime edges: prices where the impulse curve crosses zero,
+     * marking transitions between mean-reverting and trend-amplifying behavior.
+     */
+    regimeEdges: RegimeEdge[];
+    /**
+     * Per-price-level detail for the full chart overlay.
+     * Every point on the impulse curve grid, enriched with scores and contract estimates.
+     */
+    priceLevels: PressureLevel[];
+}
+/**
+ * Compute a pressure cloud from an existing hedge impulse curve.
+ *
+ * The pressure cloud translates the raw impulse curve into actionable
+ * trading zones:
+ *
+ * - **Stability zones** (positive impulse peaks, weighted by proximity):
+ *   Where dealer hedging creates counter-trend flow. These are bounce/rejection
+ *   targets — price decelerates into them and often stalls or reverses.
+ *
+ * - **Acceleration zones** (negative impulse troughs, weighted by proximity):
+ *   Where dealer hedging creates with-trend flow. If price reaches these levels,
+ *   dealers amplify the move. These are momentum/breakout zones — price
+ *   accelerates through them.
+ *
+ * - **Regime edges** (zero crossings):
+ *   Where behavior flips. Critical for understanding "if price breaks past X,
+ *   the character of the tape changes."
+ *
+ * @param impulseCurve - A previously computed hedge impulse curve
+ * @param regimeParams - Regime parameters (for expected daily move / reachability)
+ * @param config - Optional tuning parameters
+ * @returns Complete pressure cloud analysis
+ */
+export declare function computePressureCloud(impulseCurve: HedgeImpulseCurve, regimeParams: RegimeParams, config?: PressureCloudConfig): PressureCloud;

package/dist/hedgeflow/pressurecloud.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computePressureCloud = computePressureCloud;
+/** Product multipliers for contract conversion */
+const PRODUCT_MULTIPLIERS = {
+    NQ: 20,
+    MNQ: 2,
+    ES: 50,
+    MES: 5,
+};
+/**
+ * Convert a dollar impulse value to hedge contracts for a given product multiplier.
+ * contracts = impulse / (multiplier * spot * 0.01)
+ */
+function impulseToContracts(impulse, multiplier, spot) {
+    const denominator = multiplier * spot * 0.01;
+    return denominator > 0 ? sanitize(impulse / denominator) : 0;
+}
+/**
+ * Compute multi-product hedge contract estimates from a dollar impulse value.
+ */
+function computeHedgeContractEstimates(impulse, spot) {
+    return {
+        nq: impulseToContracts(impulse, PRODUCT_MULTIPLIERS.NQ, spot),
+        mnq: impulseToContracts(impulse, PRODUCT_MULTIPLIERS.MNQ, spot),
+        es: impulseToContracts(impulse, PRODUCT_MULTIPLIERS.ES, spot),
+        mes: impulseToContracts(impulse, PRODUCT_MULTIPLIERS.MES, spot),
+    };
+}
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Compute a pressure cloud from an existing hedge impulse curve.
+ *
+ * The pressure cloud translates the raw impulse curve into actionable
+ * trading zones:
+ *
+ * - **Stability zones** (positive impulse peaks, weighted by proximity):
+ *   Where dealer hedging creates counter-trend flow. These are bounce/rejection
+ *   targets — price decelerates into them and often stalls or reverses.
+ *
+ * - **Acceleration zones** (negative impulse troughs, weighted by proximity):
+ *   Where dealer hedging creates with-trend flow. If price reaches these levels,
+ *   dealers amplify the move. These are momentum/breakout zones — price
+ *   accelerates through them.
+ *
+ * - **Regime edges** (zero crossings):
+ *   Where behavior flips. Critical for understanding "if price breaks past X,
+ *   the character of the tape changes."
+ *
+ * @param impulseCurve - A previously computed hedge impulse curve
+ * @param regimeParams - Regime parameters (for expected daily move / reachability)
+ * @param config - Optional tuning parameters
+ * @returns Complete pressure cloud analysis
+ */
+function computePressureCloud(impulseCurve, regimeParams, config = {}) {
+    const { contractMultiplier = 20, // NQ default
+    reachabilityMultiple = 2.0, zoneThreshold = 0.15, } = config;
+    const { spot, curve, extrema, zeroCrossings } = impulseCurve;
+    const expectedMove = regimeParams.expectedDailySpotMove * spot;
+    // Compute reachability-weighted scores for each price level
+    const priceLevels = computePriceLevels(curve, spot, expectedMove, reachabilityMultiple, contractMultiplier);
+    // Extract stability zones from positive impulse peaks
+    const stabilityZones = extractStabilityZones(extrema, curve, spot, expectedMove, reachabilityMultiple, zoneThreshold);
+    // Extract acceleration zones from negative impulse troughs
+    const accelerationZones = extractAccelerationZones(extrema, curve, spot, expectedMove, reachabilityMultiple, zoneThreshold);
+    // Convert zero crossings to regime edges
+    const regimeEdges = convertZeroCrossingsToEdges(zeroCrossings, spot);
+    return {
+        spot,
+        expiration: impulseCurve.expiration,
+        computedAt: Date.now(),
+        stabilityZones,
+        accelerationZones,
+        regimeEdges,
+        priceLevels,
+    };
+}
+/**
+ * Compute per-price-level detail from the impulse curve.
+ */
+function computePriceLevels(curve, spot, expectedMove, reachabilityMultiple, contractMultiplier) {
+    const reachRange = expectedMove * reachabilityMultiple;
+    return curve.map((point) => {
+        const distance = Math.abs(point.price - spot);
+        const proximity = Math.exp(-((distance / reachRange) ** 2));
+        // Stability: positive impulse weighted by proximity
+        const stabilityScore = point.impulse > 0
+            ? point.impulse * proximity
+            : 0;
+        // Acceleration: negative impulse magnitude weighted by proximity
+        const accelerationScore = point.impulse < 0
+            ? Math.abs(point.impulse) * proximity
+            : 0;
+        // Convert dollar impulse to signed contract count.
+        // impulse is $ of hedging per 1% move. For contracts per 1 point:
+        // contracts = impulse / (contractMultiplier * spot * 0.01)
+        const contractDenominator = contractMultiplier * spot * 0.01;
+        const expectedHedgeContracts = contractDenominator > 0
+            ? point.impulse / contractDenominator
+            : 0;
+        return {
+            price: point.price,
+            stabilityScore,
+            accelerationScore,
+            expectedHedgeContracts: sanitize(expectedHedgeContracts),
+            hedgeContracts: computeHedgeContractEstimates(point.impulse, spot),
+            hedgeType: point.impulse >= 0 ? 'passive' : 'aggressive',
+        };
+    });
+}
+/**
+ * Extract stability zones from positive impulse peaks (basins).
+ */
+function extractStabilityZones(extrema, curve, spot, expectedMove, reachabilityMultiple, zoneThreshold) {
+    const basins = extrema.filter((e) => e.type === 'basin');
+    if (basins.length === 0)
+        return [];
+    const reachRange = expectedMove * reachabilityMultiple;
+    const maxImpulse = Math.max(...basins.map((b) => Math.abs(b.impulse)), 1e-10);
+    // Filter by threshold
+    const significant = basins.filter((b) => Math.abs(b.impulse) / maxImpulse >= zoneThreshold);
+    // Build zones
+    const zones = significant.map((basin) => {
+        const proximity = Math.exp(-((Math.abs(basin.price - spot) / reachRange) ** 2));
+        const rawStrength = (Math.abs(basin.impulse) / maxImpulse) * proximity;
+        // Find zone width: where impulse drops to 50% of peak
+        const halfPeak = basin.impulse * 0.5;
+        const { lower, upper } = findZoneBounds(curve, basin.price, halfPeak);
+        const side = basin.price >= spot ? 'above-spot' : 'below-spot';
+        const tradeType = side === 'below-spot' ? 'long' : 'short';
+        return {
+            center: basin.price,
+            lower,
+            upper,
+            strength: Math.min(1, rawStrength),
+            side,
+            tradeType,
+            hedgeType: 'passive',
+        };
+    });
+    // Sort by strength descending
+    return zones.sort((a, b) => b.strength - a.strength);
+}
+/**
+ * Extract acceleration zones from negative impulse troughs (peaks in the type system).
+ */
+function extractAccelerationZones(extrema, curve, spot, expectedMove, reachabilityMultiple, zoneThreshold) {
+    const peaks = extrema.filter((e) => e.type === 'peak');
+    if (peaks.length === 0)
+        return [];
+    const reachRange = expectedMove * reachabilityMultiple;
+    const maxImpulse = Math.max(...peaks.map((p) => Math.abs(p.impulse)), 1e-10);
+    const significant = peaks.filter((p) => Math.abs(p.impulse) / maxImpulse >= zoneThreshold);
+    const zones = significant.map((peak) => {
+        const proximity = Math.exp(-((Math.abs(peak.price - spot) / reachRange) ** 2));
+        const rawStrength = (Math.abs(peak.impulse) / maxImpulse) * proximity;
+        const halfTrough = peak.impulse * 0.5;
+        const { lower, upper } = findZoneBounds(curve, peak.price, halfTrough);
+        const side = peak.price >= spot ? 'above-spot' : 'below-spot';
+        // Acceleration below spot → momentum short (waterfall)
+        // Acceleration above spot → momentum long (squeeze)
+        const tradeType = side === 'below-spot' ? 'short' : 'long';
+        return {
+            center: peak.price,
+            lower,
+            upper,
+            strength: Math.min(1, rawStrength),
+            side,
+            tradeType,
+            hedgeType: 'aggressive',
+        };
+    });
+    return zones.sort((a, b) => b.strength - a.strength);
+}
+/**
+ * Find the price bounds where impulse drops to the given threshold
+ * around a peak/trough center price.
+ */
+function findZoneBounds(curve, centerPrice, thresholdImpulse) {
+    // Find the center index
+    let centerIdx = 0;
+    let minDist = Infinity;
+    for (let i = 0; i < curve.length; i++) {
+        const d = Math.abs(curve[i].price - centerPrice);
+        if (d < minDist) {
+            minDist = d;
+            centerIdx = i;
+        }
+    }
+    const isPositive = thresholdImpulse > 0;
+    // Scan left for lower bound
+    let lowerIdx = centerIdx;
+    for (let i = centerIdx - 1; i >= 0; i--) {
+        if (isPositive ? curve[i].impulse < thresholdImpulse : curve[i].impulse > thresholdImpulse) {
+            lowerIdx = i;
+            break;
+        }
+        lowerIdx = i;
+    }
+    // Scan right for upper bound
+    let upperIdx = centerIdx;
+    for (let i = centerIdx + 1; i < curve.length; i++) {
+        if (isPositive ? curve[i].impulse < thresholdImpulse : curve[i].impulse > thresholdImpulse) {
+            upperIdx = i;
+            break;
+        }
+        upperIdx = i;
+    }
+    return {
+        lower: curve[lowerIdx].price,
+        upper: curve[upperIdx].price,
+    };
+}
+/**
+ * Convert impulse zero crossings into regime edge descriptors.
+ */
+function convertZeroCrossingsToEdges(crossings, spot) {
+    return crossings.map((crossing) => {
+        // A "falling" crossing means impulse goes from positive to negative.
+        // If this is below spot, moving down into it means going from
+        // stable (positive impulse) to unstable (negative impulse).
+        // If above spot, it's the reverse perspective.
+        const isBelow = crossing.price < spot;
+        let transitionType;
+        if (crossing.direction === 'falling') {
+            // Impulse goes + → -
+            transitionType = isBelow ? 'stable-to-unstable' : 'unstable-to-stable';
+        }
+        else {
+            // Impulse goes - → +
+            transitionType = isBelow ? 'unstable-to-stable' : 'stable-to-unstable';
+        }
+        return {
+            price: crossing.price,
+            transitionType,
+        };
+    });
+}
+function sanitize(value) {
+    return isFinite(value) && !isNaN(value) ? value : 0;
+}

package/dist/impliedpdf/adjusted.d.ts

@@ -114,7 +114,7 @@ export declare const OPEX_CONFIG: ExposureAdjustmentConfig;
  * @param symbol - Underlying ticker symbol
  * @param underlyingPrice - Current spot price
  * @param callOptions - Call options for a single expiry
- * @param exposures - Exposure metrics from calculateGammaVannaCharmExposures()
+ * @param exposures - Canonical exposure metrics from calculateGammaVannaCharmExposures()
  * @param config - Adjustment configuration (uses defaults if not provided)
  * @returns Baseline and adjusted PDFs with comparison metrics
  *
@@ -122,7 +122,10 @@ export declare const OPEX_CONFIG: ExposureAdjustmentConfig;
  * ```typescript
  * // Get exposures first
  * const allExposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * const expiryExposures = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiry = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiryExposures = expiry
+ *   ? { spotPrice: expiry.spotPrice, expiration: expiry.expiration, ...expiry.canonical }
+ *   : undefined;
  *
  * // Calculate adjusted PDF
  * const result = estimateExposureAdjustedPDF(

package/dist/impliedpdf/adjusted.js

@@ -122,7 +122,7 @@ exports.OPEX_CONFIG = {
  * @param symbol - Underlying ticker symbol
  * @param underlyingPrice - Current spot price
  * @param callOptions - Call options for a single expiry
- * @param exposures - Exposure metrics from calculateGammaVannaCharmExposures()
+ * @param exposures - Canonical exposure metrics from calculateGammaVannaCharmExposures()
  * @param config - Adjustment configuration (uses defaults if not provided)
  * @returns Baseline and adjusted PDFs with comparison metrics
  *
@@ -130,7 +130,10 @@ exports.OPEX_CONFIG = {
  * ```typescript
  * // Get exposures first
  * const allExposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * const expiryExposures = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiry = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiryExposures = expiry
+ *   ? { spotPrice: expiry.spotPrice, expiration: expiry.expiration, ...expiry.canonical }
+ *   : undefined;
  *
  * // Calculate adjusted PDF
  * const result = estimateExposureAdjustedPDF(

package/dist/index.d.ts

@@ -14,8 +14,8 @@ export { buildOCCSymbol, parseOCCSymbol, generateStrikesAroundSpot, generateOCCS
 export type { OCCSymbolParams, ParsedOCCSymbol, StrikeGenerationParams, } from './utils/occ';
 export { estimateImpliedProbabilityDistribution, estimateImpliedProbabilityDistributions, getProbabilityInRange, getCumulativeProbability, getQuantile, estimateExposureAdjustedPDF, getEdgeAtPrice, getSignificantAdjustmentLevels, DEFAULT_ADJUSTMENT_CONFIG, LOW_VOL_CONFIG, CRISIS_CONFIG, OPEX_CONFIG, } from './impliedpdf';
 export type { StrikeProbability, ImpliedProbabilityDistribution, ImpliedPDFResult, ExposureAdjustmentConfig, AdjustedPDFResult, PDFComparison, } from './impliedpdf';
-export { deriveRegimeParams, interpolateIVAtStrike, computeHedgeImpulseCurve, computeCharmIntegral, analyzeHedgeFlow, } from './hedgeflow';
-export type { MarketRegime, RegimeParams, HedgeImpulseConfig, HedgeImpulsePoint, HedgeImpulseCurve, ZeroCrossing, ImpulseExtremum, DirectionalAsymmetry, ImpulseRegime, CharmIntegralConfig, CharmBucket, CharmIntegral, HedgeFlowAnalysis, } from './hedgeflow';
+export { deriveRegimeParams, interpolateIVAtStrike, computeHedgeImpulseCurve, computeCharmIntegral, computePressureCloud, analyzeHedgeFlow, } from './hedgeflow';
+export type { MarketRegime, RegimeParams, HedgeImpulseConfig, HedgeImpulsePoint, HedgeImpulseCurve, ZeroCrossing, ImpulseExtremum, DirectionalAsymmetry, ImpulseRegime, CharmIntegralConfig, CharmBucket, CharmIntegral, HedgeFlowAnalysis, HedgeContractEstimates, PressureZone, RegimeEdge, PressureLevel, PressureCloudConfig, PressureCloud, } from './hedgeflow';
 export { FloeClient, Broker } from './client/FloeClient';
 export { TradierClient } from './client/brokers/TradierClient';
 export { TastyTradeClient } from './client/brokers/TastyTradeClient';

package/dist/index.js

@@ -20,7 +20,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeRealizedVolatility = exports.computeImpliedVolatility = exports.computeVarianceSwapIV = exports.createOptionChain = exports.getAdapter = exports.brokerAdapters = exports.tdaAdapter = exports.ibkrAdapter = exports.schwabAdapter = exports.genericAdapter = exports.TradeStationClient = exports.TastyTradeClient = exports.TradierClient = exports.Broker = exports.FloeClient = exports.analyzeHedgeFlow = exports.computeCharmIntegral = exports.computeHedgeImpulseCurve = exports.interpolateIVAtStrike = exports.deriveRegimeParams = exports.OPEX_CONFIG = exports.CRISIS_CONFIG = exports.LOW_VOL_CONFIG = exports.DEFAULT_ADJUSTMENT_CONFIG = exports.getSignificantAdjustmentLevels = exports.getEdgeAtPrice = exports.estimateExposureAdjustedPDF = exports.getQuantile = exports.getCumulativeProbability = exports.getProbabilityInRange = exports.estimateImpliedProbabilityDistributions = exports.estimateImpliedProbabilityDistribution = exports.generateOCCSymbolsAroundSpot = exports.generateOCCSymbolsForStrikes = exports.generateStrikesAroundSpot = exports.parseOCCSymbol = exports.buildOCCSymbol = exports.normalPDF = exports.cumulativeNormalDistribution = exports.calculateSharesNeededToCover = exports.calculateGammaVannaCharmExposures = exports.smoothTotalVarianceSmile = exports.getIVForStrike = exports.getIVSurfaces = exports.getTimeToExpirationInYears = exports.getMillisecondsToExpiration = exports.calculateImpliedVolatility = exports.calculateGreeks = exports.blackScholes = void 0;
+exports.computeRealizedVolatility = exports.computeImpliedVolatility = exports.computeVarianceSwapIV = exports.createOptionChain = exports.getAdapter = exports.brokerAdapters = exports.tdaAdapter = exports.ibkrAdapter = exports.schwabAdapter = exports.genericAdapter = exports.TradeStationClient = exports.TastyTradeClient = exports.TradierClient = exports.Broker = exports.FloeClient = exports.analyzeHedgeFlow = exports.computePressureCloud = exports.computeCharmIntegral = exports.computeHedgeImpulseCurve = exports.interpolateIVAtStrike = exports.deriveRegimeParams = exports.OPEX_CONFIG = exports.CRISIS_CONFIG = exports.LOW_VOL_CONFIG = exports.DEFAULT_ADJUSTMENT_CONFIG = exports.getSignificantAdjustmentLevels = exports.getEdgeAtPrice = exports.estimateExposureAdjustedPDF = exports.getQuantile = exports.getCumulativeProbability = exports.getProbabilityInRange = exports.estimateImpliedProbabilityDistributions = exports.estimateImpliedProbabilityDistribution = exports.generateOCCSymbolsAroundSpot = exports.generateOCCSymbolsForStrikes = exports.generateStrikesAroundSpot = exports.parseOCCSymbol = exports.buildOCCSymbol = exports.normalPDF = exports.cumulativeNormalDistribution = exports.calculateSharesNeededToCover = exports.calculateGammaVannaCharmExposures = exports.smoothTotalVarianceSmile = exports.getIVForStrike = exports.getIVSurfaces = exports.getTimeToExpirationInYears = exports.getMillisecondsToExpiration = exports.calculateImpliedVolatility = exports.calculateGreeks = exports.blackScholes = void 0;
 // Core types
 __exportStar(require("./types"), exports);
 // Black-Scholes pricing and Greeks
@@ -67,7 +67,7 @@ Object.defineProperty(exports, "DEFAULT_ADJUSTMENT_CONFIG", { enumerable: true,
 Object.defineProperty(exports, "LOW_VOL_CONFIG", { enumerable: true, get: function () { return impliedpdf_1.LOW_VOL_CONFIG; } });
 Object.defineProperty(exports, "CRISIS_CONFIG", { enumerable: true, get: function () { return impliedpdf_1.CRISIS_CONFIG; } });
 Object.defineProperty(exports, "OPEX_CONFIG", { enumerable: true, get: function () { return impliedpdf_1.OPEX_CONFIG; } });
-// Hedge flow analysis (impulse curve, charm integral, regime derivation)
+// Hedge flow analysis (impulse curve, charm integral, regime derivation, pressure cloud)
 var hedgeflow_1 = require("./hedgeflow");
 // Regime derivation from IV surface
 Object.defineProperty(exports, "deriveRegimeParams", { enumerable: true, get: function () { return hedgeflow_1.deriveRegimeParams; } });
@@ -76,6 +76,8 @@ Object.defineProperty(exports, "interpolateIVAtStrike", { enumerable: true, get:
 Object.defineProperty(exports, "computeHedgeImpulseCurve", { enumerable: true, get: function () { return hedgeflow_1.computeHedgeImpulseCurve; } });
 // Charm integral
 Object.defineProperty(exports, "computeCharmIntegral", { enumerable: true, get: function () { return hedgeflow_1.computeCharmIntegral; } });
+// Pressure cloud (stability/acceleration zones)
+Object.defineProperty(exports, "computePressureCloud", { enumerable: true, get: function () { return hedgeflow_1.computePressureCloud; } });
 // Combined analysis
 Object.defineProperty(exports, "analyzeHedgeFlow", { enumerable: true, get: function () { return hedgeflow_1.analyzeHedgeFlow; } });
 // Client

package/dist/types/index.d.ts

@@ -172,6 +172,52 @@ export interface StrikeExposure {
     /** Net exposure (gamma + vanna + charm) */
     netExposure: number;
 }
+/**
+ * Input options for exposure calculations.
+ */
+export interface ExposureCalculationOptions {
+    /**
+     * Reference timestamp in milliseconds.
+     * If omitted, Date.now() is used.
+     */
+    asOfTimestamp?: number;
+}
+/**
+ * Exposure vector used by variant outputs.
+ */
+export interface ExposureVector {
+    gammaExposure: number;
+    vannaExposure: number;
+    charmExposure: number;
+    netExposure: number;
+}
+/**
+ * Per-strike exposure variants (canonical, state-weighted, and flow delta).
+ */
+export interface StrikeExposureVariants {
+    strikePrice: number;
+    canonical: ExposureVector;
+    stateWeighted: ExposureVector;
+    flowDelta: ExposureVector;
+}
+/**
+ * Full exposure breakdown for one mode.
+ */
+export interface ExposureModeBreakdown {
+    totalGammaExposure: number;
+    totalVannaExposure: number;
+    totalCharmExposure: number;
+    totalNetExposure: number;
+    strikeOfMaxGamma: number;
+    strikeOfMinGamma: number;
+    strikeOfMaxVanna: number;
+    strikeOfMinVanna: number;
+    strikeOfMaxCharm: number;
+    strikeOfMinCharm: number;
+    strikeOfMaxNet: number;
+    strikeOfMinNet: number;
+    strikeExposures: StrikeExposure[];
+}
 /**
  * Exposure metrics per expiration
  */
@@ -207,6 +253,26 @@ export interface ExposurePerExpiry {
     /** Per-strike exposures */
     strikeExposures: StrikeExposure[];
 }
+/**
+ * Exposure variants per expiration.
+ * canonical: classic per-1% / per-vol-point / per-day definitions
+ * stateWeighted: level-weighted vanna/charm (gamma remains canonical)
+ * flowDelta: exposure deltas from intraday OI changes (liveOpenInterest - openInterest)
+ */
+export interface ExposureVariantsPerExpiry {
+    /** Current spot price */
+    spotPrice: number;
+    /** Expiration timestamp in milliseconds */
+    expiration: number;
+    /** Canonical exposure mode */
+    canonical: ExposureModeBreakdown;
+    /** State-weighted exposure mode */
+    stateWeighted: ExposureModeBreakdown;
+    /** Flow-delta exposure mode */
+    flowDelta: ExposureModeBreakdown;
+    /** Per-strike variants */
+    strikeExposureVariants: StrikeExposureVariants[];
+}
 /**
  * Dealer Gamma Exposure (GEX) metrics
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackcraftllc/floe",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Production-ready options analytics toolkit. Normalize broker data structures and calculate Black-Scholes, Greeks, and exposures with a clean, type-safe API. Built for trading platforms and fintech applications.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,7 +8,9 @@
     "build": "tsc",
     "test": "jest",
     "prepublishOnly": "npm run build",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "prepare": "husky",
+    "copy-whitepaper": "cp whitepaper/whitepaper.pdf site/public/whitepaper.pdf"
   },
   "keywords": [
     "options",
@@ -42,6 +44,7 @@
     "@types/jest": "^29.5.0",
     "@types/node": "^20.0.0",
     "dotenv": "^17.2.3",
+    "husky": "^9.1.7",
     "jest": "^29.5.0",
     "ts-jest": "^29.1.0",
     "typescript": "^5.9.3"