@robotixai/calculator-engine 0.1.0

package/dist/tax.js

@@ -0,0 +1,210 @@
+/**
+ * Multi-jurisdiction tax calculator for the retirement engine.
+ *
+ * Jurisdictions: Custom (flat rate), Cayman Islands (zero), US (progressive),
+ * UK (progressive with personal allowance taper).
+ *
+ * Also includes RMD (Required Minimum Distribution) and Roth conversion logic.
+ */
+const US_STANDARD_DEDUCTION_SINGLE = 15000;
+const US_STANDARD_DEDUCTION_MFJ = 30000;
+const US_BRACKETS_2025_SINGLE = [
+    { ceiling: 11925, rate: 0.10 },
+    { ceiling: 48475, rate: 0.12 },
+    { ceiling: 103350, rate: 0.22 },
+    { ceiling: 197300, rate: 0.24 },
+    { ceiling: 250525, rate: 0.32 },
+    { ceiling: 626350, rate: 0.35 },
+    { ceiling: Infinity, rate: 0.37 },
+];
+const US_BRACKETS_2025_MFJ = [
+    { ceiling: 23850, rate: 0.10 },
+    { ceiling: 96950, rate: 0.12 },
+    { ceiling: 206700, rate: 0.22 },
+    { ceiling: 394600, rate: 0.24 },
+    { ceiling: 501050, rate: 0.32 },
+    { ceiling: 751600, rate: 0.35 },
+    { ceiling: Infinity, rate: 0.37 },
+];
+// =============================================================================
+// UK Tax Constants (2025-26)
+// =============================================================================
+const UK_PERSONAL_ALLOWANCE = 12570;
+/** Income threshold above which the personal allowance begins to taper. */
+const UK_TAPER_THRESHOLD = 100000;
+/** Income at which the personal allowance is fully withdrawn:
+ *  100,000 + 2 * 12,570 = 125,140.
+ *
+ *  In the GBP 100,000 - 125,140 band the effective marginal rate is 60%:
+ *  for every additional GBP 1 of income, you lose GBP 0.50 of personal
+ *  allowance, so you pay 40% on GBP 1 of income PLUS 40% on GBP 0.50
+ *  of previously-sheltered income = 60p total.
+ */
+const UK_TAPER_FULL_WITHDRAWAL = 125140;
+/** Bands applied to income ABOVE the (adjusted) personal allowance. */
+const UK_BANDS_2025_26 = [
+    { ceiling: 37700, rate: 0.20 },
+    { ceiling: 112570, rate: 0.40 },
+    { ceiling: Infinity, rate: 0.45 },
+];
+// =============================================================================
+// IRS Uniform Lifetime Table (ages 72-120)
+// =============================================================================
+const RMD_DIVISORS = {
+    72: 27.4, 73: 26.5, 74: 25.5, 75: 24.6, 76: 23.7, 77: 22.9,
+    78: 22.0, 79: 21.1, 80: 20.2, 81: 19.4, 82: 18.5, 83: 17.7,
+    84: 16.8, 85: 16.0, 86: 15.2, 87: 14.4, 88: 13.7, 89: 12.9,
+    90: 12.2, 91: 11.5, 92: 10.8, 93: 10.1, 94: 9.5, 95: 8.9,
+    96: 8.4, 97: 7.8, 98: 7.3, 99: 6.8, 100: 6.4, 101: 6.0,
+    102: 5.6, 103: 5.2, 104: 4.9, 105: 4.6, 106: 4.3, 107: 4.1,
+    108: 3.9, 109: 3.7, 110: 3.5, 111: 3.4, 112: 3.3, 113: 3.1,
+    114: 3.0, 115: 2.9, 116: 2.8, 117: 2.7, 118: 2.5, 119: 2.3,
+    120: 2.0,
+};
+// =============================================================================
+// Progressive bracket calculation (shared by US and UK)
+// =============================================================================
+/**
+ * Compute total tax by walking through progressive brackets.
+ * @param taxableIncome - Income subject to tax (after deductions/allowances).
+ * @param brackets - Ordered array of brackets (ceiling is cumulative, not width).
+ */
+function applyProgressiveBrackets(taxableIncome, brackets) {
+    if (taxableIncome <= 0)
+        return 0;
+    let tax = 0;
+    let prev = 0;
+    for (const { ceiling, rate } of brackets) {
+        if (taxableIncome <= prev)
+            break;
+        const taxableInBracket = Math.min(taxableIncome, ceiling) - prev;
+        tax += taxableInBracket * rate;
+        prev = ceiling;
+    }
+    return tax;
+}
+// =============================================================================
+// US Tax
+// =============================================================================
+function calculateUSTax(grossIncome, filingStatus) {
+    if (grossIncome <= 0)
+        return 0;
+    const deduction = filingStatus === 'Married Filing Jointly'
+        ? US_STANDARD_DEDUCTION_MFJ
+        : US_STANDARD_DEDUCTION_SINGLE;
+    const brackets = filingStatus === 'Married Filing Jointly'
+        ? US_BRACKETS_2025_MFJ
+        : US_BRACKETS_2025_SINGLE;
+    const taxableIncome = Math.max(0, grossIncome - deduction);
+    return applyProgressiveBrackets(taxableIncome, brackets);
+}
+// =============================================================================
+// UK Tax
+// =============================================================================
+/**
+ * Compute the adjusted personal allowance after the taper.
+ *
+ * For gross income above GBP 100,000 the allowance is reduced by GBP 1 for
+ * every GBP 2 of income above 100K. This creates an effective 60% marginal
+ * rate in the GBP 100,000 - 125,140 band.
+ */
+function ukAdjustedAllowance(grossIncome) {
+    if (grossIncome <= UK_TAPER_THRESHOLD) {
+        return UK_PERSONAL_ALLOWANCE;
+    }
+    const reduction = Math.floor((grossIncome - UK_TAPER_THRESHOLD) / 2);
+    return Math.max(0, UK_PERSONAL_ALLOWANCE - reduction);
+}
+function calculateUKTax(grossIncome) {
+    if (grossIncome <= 0)
+        return 0;
+    const allowance = ukAdjustedAllowance(grossIncome);
+    const taxableIncome = Math.max(0, grossIncome - allowance);
+    return applyProgressiveBrackets(taxableIncome, UK_BANDS_2025_26);
+}
+// =============================================================================
+// Main entry point
+// =============================================================================
+/**
+ * Calculate income tax for the given jurisdiction.
+ *
+ * @param taxableIncome - Gross income before deductions/allowances.
+ * @param config - The scenario's TaxConfig.
+ * @param jurisdiction - One of 'Custom', 'Cayman Islands', 'US', 'UK'.
+ * @returns Tax amount (always >= 0).
+ */
+export function calculateTax(taxableIncome, config, jurisdiction) {
+    if (taxableIncome <= 0)
+        return 0;
+    switch (jurisdiction) {
+        case 'Cayman Islands':
+            return 0;
+        case 'US':
+            return calculateUSTax(taxableIncome, config.filing_status);
+        case 'UK':
+            return calculateUKTax(taxableIncome);
+        case 'Custom':
+        default:
+            return taxableIncome * (config.flat_rate_pct / 100);
+    }
+}
+// =============================================================================
+// RMD (Required Minimum Distributions)
+// =============================================================================
+/**
+ * Determine the age at which RMDs must begin based on birth year.
+ *
+ * - Born <= 1950: age 72
+ * - Born 1951-1959: age 73
+ * - Born >= 1960: age 75
+ */
+export function getRMDStartAge(birthYear) {
+    if (birthYear <= 1950)
+        return 72;
+    if (birthYear <= 1959)
+        return 73;
+    return 75;
+}
+/**
+ * Calculate the Required Minimum Distribution for a given age and balance.
+ *
+ * @param age - The individual's current age.
+ * @param taxDeferredBalance - End-of-prior-year tax-deferred account balance.
+ * @param birthYear - Birth year, used to determine RMD start age.
+ * @returns The RMD amount, or 0 if not yet required or age > 120.
+ */
+export function getRMDAmount(age, taxDeferredBalance, birthYear) {
+    const startAge = getRMDStartAge(birthYear);
+    if (age < startAge || age > 120)
+        return 0;
+    if (taxDeferredBalance <= 0)
+        return 0;
+    const divisor = RMD_DIVISORS[age];
+    if (divisor === undefined || divisor <= 0)
+        return 0;
+    return taxDeferredBalance / divisor;
+}
+// =============================================================================
+// Roth Conversion
+// =============================================================================
+/**
+ * Calculate the Roth conversion amount for a given age and tax config.
+ *
+ * If the current age is within the configured conversion window
+ * (roth_conversion_start_age <= age <= roth_conversion_end_age) and
+ * conversions are enabled, returns the configured conversion amount.
+ * Otherwise returns 0.
+ *
+ * Note: the converted amount adds to taxable income for the conversion year.
+ * The caller is responsible for clamping the conversion to the available
+ * tax-deferred balance and adding it to taxable income.
+ */
+export function calculateRothConversion(age, config) {
+    if (!config.enable_roth_conversion)
+        return 0;
+    if (age < config.roth_conversion_start_age)
+        return 0;
+    if (age > config.roth_conversion_end_age)
+        return 0;
+    return config.roth_conversion_amount;
+}

package/dist/types.d.ts

@@ -0,0 +1,250 @@
+export type CurrencyCode = 'USD' | 'EUR' | 'GBP' | 'CHF' | 'HKD' | 'SGD' | 'AED' | 'JPY' | 'CAD' | 'AUD' | 'NZD' | 'ZAR' | 'INR' | 'BRL' | 'MXN' | 'KYD';
+export type Cadence = 'Annual' | 'Monthly' | 'Bi-Weekly' | 'Weekly';
+export interface ContribStep {
+    start_age: number;
+    end_age: number;
+    amount: number;
+}
+export interface ProfitStep {
+    age: number;
+    end_age?: number;
+    pct: number;
+}
+export interface RaiseStep {
+    start_age: number;
+    end_age: number;
+    raise_pct: number;
+}
+export interface YieldStep {
+    start_age: number;
+    end_age: number;
+    rate_pct: number;
+}
+export interface IncomeStep {
+    start_age: number;
+    end_age: number;
+    amount: number;
+    frequency?: 'Annual' | 'Monthly';
+}
+export interface LoanDraw {
+    age: number;
+    amount: number;
+}
+export interface LumpRepayment {
+    age: number;
+    amount: number;
+}
+export interface SpendingPhase {
+    start_age: number;
+    end_age: number;
+    mode: 'percent' | 'amount';
+    amount: number;
+}
+export interface TaxConfig {
+    jurisdiction: string;
+    flat_rate_pct: number;
+    filing_status: 'Single' | 'Married Filing Jointly';
+    enable_rmd: boolean;
+    enable_roth_conversion: boolean;
+    roth_conversion_amount: number;
+    roth_conversion_start_age: number;
+    roth_conversion_end_age: number;
+}
+export interface IncomeSource {
+    label: string;
+    type: 'Other' | 'Social Security' | 'Pension' | 'Annuity' | 'Part-Time' | 'Retirement Income' | 'Rental';
+    amount: number;
+    frequency: 'Annual' | 'Monthly';
+    start_age: number;
+    end_age: number;
+    inflation_adjusted: boolean;
+    taxable: boolean;
+    tax_rate: number;
+    enabled: boolean;
+}
+export interface Asset {
+    [key: string]: unknown;
+    label: string;
+    current_value: number;
+    is_liquid: boolean;
+    rate_pct: number;
+    enabled: boolean;
+    sell_at_age: number | null;
+    sale_amount_override: number | null;
+}
+export interface LiquidityEvent {
+    type: 'Credit' | 'Debit';
+    label: string;
+    start_age: number;
+    end_age: number;
+    amount: number;
+    recurrence: 'One-Time' | 'Annual' | 'Monthly';
+    enabled: boolean;
+    taxable: boolean;
+    tax_rate: number;
+}
+export type FinancialItemCategory = 'Cash' | 'Investment' | 'Property' | 'Collectables' | 'Salary' | 'Pension' | 'Social Security' | 'Annuity' | 'Retirement Income' | 'Other' | 'Loan';
+export interface FinancialItem {
+    label: string;
+    category: FinancialItemCategory;
+    enabled: boolean;
+    current_value: number;
+    rate_pct: number;
+    fee_pct: number;
+    perf_fee_pct: number;
+    is_liquid: boolean;
+    contrib_mode: 'flat' | 'staggered';
+    contrib_amount: number;
+    contrib_cadence: Cadence;
+    contrib_start_age: number | null;
+    contrib_end_age: number | null;
+    contrib_increase_pct: number;
+    contrib_steps: ContribStep[];
+    invest_start_age: number | null;
+    purchase_age: number | null;
+    profit_taking_mode: 'single' | 'staggered';
+    sell_at_age: number | null;
+    sale_amount_override: number | null;
+    profit_taking_steps: ProfitStep[];
+    taxable_on_sale: boolean;
+    sale_tax_rate: number;
+    estate_pct: number;
+    rental_amount: number;
+    rental_frequency: 'Monthly' | 'Annual';
+    rental_start_age: number;
+    rental_end_age: number;
+    rental_inflation_adjusted: boolean;
+    rental_taxable: boolean;
+    rental_tax_rate: number;
+    mortgage_payment: number;
+    mortgage_frequency: 'Monthly' | 'Annual';
+    mortgage_end_age: number;
+    income_amount: number;
+    income_frequency: 'Annual' | 'Monthly';
+    income_start_age: number;
+    income_end_age: number;
+    inflation_adjusted: boolean;
+    taxable: boolean;
+    tax_rate: number;
+    income_destination: string;
+    reinvest_target_item_index: number | null;
+    income_mode: 'flat' | 'staggered';
+    income_steps: IncomeStep[];
+    salary_raise_pct: number;
+    salary_raise_mode: 'flat' | 'staggered';
+    salary_raise_steps: RaiseStep[];
+    salary_bonus_pct: number;
+    cash_yield_mode: 'flat' | 'staggered';
+    cash_yield_steps: YieldStep[];
+    loan_opening_principal: number;
+    loan_interest_rate_pct: number;
+    loan_payment_mode: 'principal_and_interest' | 'interest_only';
+    loan_annual_principal_payment: number;
+    loan_draws: LoanDraw[];
+    loan_term_years: number;
+    loan_start_age: number;
+    loan_credit_at_start: boolean;
+    loan_lump_repayments: LumpRepayment[];
+}
+export interface Scenario {
+    [key: string]: unknown;
+    name: string;
+    current_age: number;
+    retirement_age: number;
+    end_age: number;
+    current_balance: number;
+    contrib_amount: number;
+    contrib_cadence: Cadence;
+    contrib_increase_pct: number;
+    nominal_return_pct: number;
+    return_stdev_pct: number;
+    return_distribution: 'log-normal' | 'normal';
+    inflation_pct: number;
+    inflation_enabled: boolean;
+    fee_pct: number;
+    perf_fee_pct: number;
+    withdrawal_method: 'Fixed % of prior-year end balance' | 'Fixed real-dollar amount';
+    withdrawal_pct: number;
+    withdrawal_real_amount: number;
+    withdrawal_frequency: 'Annual' | 'Monthly';
+    withdrawal_strategy: 'Standard' | 'Guyton-Klinger' | 'Age-Banded';
+    gk_ceiling_pct: number;
+    gk_floor_pct: number;
+    gk_prosperity_threshold: number;
+    gk_capital_preservation_threshold: number;
+    spending_phases: SpendingPhase[];
+    enable_mc: boolean;
+    mc_runs: number;
+    enable_taxes: boolean;
+    effective_tax_rate_pct: number;
+    tax_jurisdiction: 'Custom' | 'Cayman Islands' | 'US' | 'UK';
+    tax_config: TaxConfig | null;
+    tax_deferred_pct: number;
+    planning_mode: 'Individual' | 'Couple';
+    partner_name: string;
+    partner_current_age: number | null;
+    partner_retirement_age: number | null;
+    partner_income_sources: IncomeSource[];
+    assets: Asset[];
+    liquid_pct: number;
+    detail_mode: 'basic' | 'advanced';
+    financial_items: FinancialItem[];
+    income_sources: IncomeSource[];
+    liquidity_events: LiquidityEvent[];
+    desired_estate: number;
+    black_swan_enabled: boolean;
+    black_swan_age: number;
+    black_swan_loss_pct: number;
+    currency_code: string;
+    currency_symbol: string;
+    withdrawal_order: string;
+}
+export interface TimelineRow {
+    age: number;
+    start_balance_nominal: number;
+    contributions: number;
+    liquidity_net: number;
+    income: number;
+    withdrawals: number;
+    desired_spending: number;
+    fees: number;
+    taxes: number;
+    income_taxes: number;
+    growth: number;
+    end_balance_nominal: number;
+    cpi_index: number;
+    end_balance_real: number;
+    end_cash_nominal: number;
+    end_debt_nominal: number;
+    end_investments_nominal: number;
+    end_liquid_nominal: number;
+    end_illiquid_nominal: number;
+    loan_interest: number;
+    loan_principal_repaid: number;
+    mortgage_paid: number;
+    cash_yield: number;
+    insolvency: boolean;
+    shortfall_mandatory: number;
+    shortfall_contributions: number;
+    shortfall_withdrawals: number;
+}
+export interface FanChartRow {
+    age: number;
+    p10: number;
+    p25: number;
+    p50: number;
+    p75: number;
+    p90: number;
+}
+export interface Metrics {
+    terminal_nominal: number;
+    terminal_real: number;
+    first_shortfall_age: number | null;
+    readiness_score: number;
+    total_contributions: number;
+    total_withdrawals: number;
+    total_fees: number;
+    total_taxes: number;
+    estate_value: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// Engine Types — standalone type definitions (no Zod dependency)
+//
+// These are plain TypeScript equivalents of the subset of @shorecrest/schemas
+// types that the engine uses for computation.
+// ---------------------------------------------------------------------------
+export {};

package/dist/withdrawal.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Withdrawal Strategy Implementations
+ *
+ * Three strategies: Standard, Guyton-Klinger, Age-Banded.
+ * Dispatched via calculateWithdrawal() based on scenario.withdrawal_strategy.
+ *
+ * Edge cases handled:
+ * - Near-zero threshold ($100): prevents asymptotic depletion with high withdrawal rates
+ * - Age-Banded gaps: return 0, log warning
+ * - Age-Banded overlaps: first-match wins (Array.find behavior)
+ * - GK oscillation: bounded by floor/ceiling — no special handling needed
+ * - RMD override: caller responsibility (if RMD > withdrawal, caller uses RMD)
+ */
+import type { Scenario, SpendingPhase } from './types';
+/** Balance below this threshold is treated as depleted (prevents asymptotic depletion). */
+export declare const NEAR_ZERO_THRESHOLD = 100;
+export interface GKState {
+    /** The withdrawal amount from the first retirement year (nominal). */
+    initialWithdrawal: number;
+    /** The initial withdrawal rate (withdrawal / balance * 100). */
+    initialRate: number;
+    /** The most recent withdrawal amount (nominal). */
+    priorWithdrawal: number;
+}
+export interface StandardWithdrawalParams {
+    withdrawalMethod: Scenario['withdrawal_method'];
+    withdrawalPct: number;
+    withdrawalRealAmount: number;
+    withdrawalFrequency: Scenario['withdrawal_frequency'];
+    priorEndBalance: number;
+    availableBalance: number;
+    cpiIndex: number;
+}
+export interface GuytonKlingerWithdrawalParams {
+    currentBalance: number;
+    availableBalance: number;
+    cpiIndex: number;
+    /** GK state from prior year, or null if this is the first retirement year. */
+    gkState: GKState | null;
+    /** Standard withdrawal params used to compute the first-year withdrawal. */
+    standardParams: StandardWithdrawalParams;
+    /** Guardrail configuration from the scenario. */
+    gkCeilingPct: number;
+    gkFloorPct: number;
+    gkProsperityThreshold: number;
+    gkCapitalPreservationThreshold: number;
+}
+export interface AgeBandedWithdrawalParams {
+    age: number;
+    currentBalance: number;
+    availableBalance: number;
+    spendingPhases: SpendingPhase[];
+    cpiIndex: number;
+}
+/**
+ * Calculate withdrawal using the Standard strategy.
+ *
+ * - "Fixed % of prior-year end balance": priorEndBalance * (withdrawal_pct / 100)
+ * - "Fixed real-dollar amount": withdrawal_real_amount * cpiIndex
+ *
+ * Monthly frequency is annualized (multiply by 12).
+ * Result is capped at available balance.
+ */
+export declare function calculateStandardWithdrawal(params: StandardWithdrawalParams): number;
+/**
+ * Calculate withdrawal using the Guyton-Klinger guardrail strategy.
+ *
+ * First retirement year: compute via standard calculation to set the initial
+ * withdrawal and initial rate.
+ *
+ * Subsequent years:
+ *   current_rate = priorWithdrawal / currentBalance * 100
+ *
+ *   Prosperity rule (balance grew, rate dropped):
+ *     if current_rate < initialRate * (1 - prosperity_threshold/100):
+ *       withdrawal = priorWithdrawal * 1.10  (increase 10%)
+ *
+ *   Capital preservation rule (balance dropped, rate rose):
+ *     if current_rate > initialRate * (1 + preservation_threshold/100):
+ *       withdrawal = priorWithdrawal * 0.90  (decrease 10%)
+ *
+ *   Else: withdrawal = priorWithdrawal (no change)
+ *
+ *   Hard limits:
+ *     max = initialWithdrawal * (1 + ceiling_pct/100)
+ *     min = initialWithdrawal * (1 - floor_pct/100)
+ *     withdrawal = clamp(withdrawal, min, max)
+ *
+ * Capped at available balance.
+ */
+export declare function calculateGuytonKlingerWithdrawal(params: GuytonKlingerWithdrawalParams): {
+    withdrawal: number;
+    gkState: GKState;
+};
+/**
+ * Calculate withdrawal using the Age-Banded strategy.
+ *
+ * Finds the first spending phase where start_age <= age <= end_age.
+ * - If mode = 'percent': withdrawal = currentBalance * (amount / 100)
+ * - If mode = 'amount': withdrawal = amount * cpiIndex (inflation-adjusted)
+ *
+ * If no phase covers the current age, returns 0 and logs a warning (gap).
+ * If phases overlap, the first match wins (Array.find behavior).
+ */
+export declare function calculateAgeBandedWithdrawal(params: AgeBandedWithdrawalParams): number;
+/** Parameters for the main dispatcher, combining scenario config and simulation state. */
+export interface WithdrawalParams {
+    /** The full scenario configuration. */
+    scenario: Scenario;
+    /** Current simulation state. */
+    state: {
+        age: number;
+        currentBalance: number;
+        priorEndBalance: number;
+        availableBalance: number;
+        cpiIndex: number;
+        gkState: GKState | null;
+    };
+}
+/** Result from the withdrawal dispatcher. */
+export interface WithdrawalResult {
+    /** The withdrawal amount for this year (capped at available balance). */
+    withdrawal: number;
+    /** Updated GK state (only present for Guyton-Klinger strategy). */
+    gkState?: GKState;
+    /** True if the balance is below the near-zero threshold post-withdrawal. */
+    effectivelyDepleted: boolean;
+}
+/**
+ * Main withdrawal dispatcher.
+ *
+ * Routes to the correct strategy based on scenario.withdrawal_strategy, then
+ * applies the near-zero depletion threshold ($100).
+ */
+export declare function calculateWithdrawal(scenario: Scenario, state: WithdrawalParams['state']): WithdrawalResult;
+//# sourceMappingURL=withdrawal.d.ts.map

package/dist/withdrawal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withdrawal.d.ts","sourceRoot":"","sources":["../src/withdrawal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAMvD,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAMvC,MAAM,WAAW,OAAO;IACtB,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;CACzB;AAMD,MAAM,WAAW,wBAAwB;IACvC,gBAAgB,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,MAAM,WAAW,6BAA6B;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IAEjB,8EAA8E;IAC9E,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAExB,4EAA4E;IAC5E,cAAc,EAAE,wBAAwB,CAAC;IAEzC,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8BAA8B,EAAE,MAAM,CAAC;CACxC;AAMD,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,wBAAwB,GAC/B,MAAM,CA2BR;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,6BAA6B,GACpC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAkF1C;AAMD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,yBAAyB,GAChC,MAAM,CA6BR;AAMD,0FAA0F;AAC1F,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,QAAQ,EAAE,QAAQ,CAAC;IAEnB,gCAAgC;IAChC,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAC;QACZ,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;KACzB,CAAC;CACH;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAC/B,gBAAgB,CA0FlB"}