@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/drill-down.d.ts

@@ -0,0 +1,41 @@
+/**
+ * G6 — Drill-Down / Drill-Through
+ *
+ * LynxSEO: drill-through.ts + DrillThroughTab.tsx + routes/api/pulse/v1/drill-through.ts
+ *          + drill-down.ts (nouveau - logique de drill-down pure)
+ * Inspiration: Metabase drill-through + Rybbit OLAP concepts
+ *
+ * NOTE: Le drill-through API existe mais ce module fournit la logique
+ * de drill-down pure (navigation arborescente dans les métriques).
+ */
+import { z } from "zod";
+/** Niveaux de drill-down disponibles */
+export type DrillLevel = "summary" | "detail" | "event" | "session";
+/** Schema for drill-down configuration */
+export declare const drillDownSchema: z.ZodObject<{
+    metric: z.ZodString;
+    level: z.ZodEnum<{
+        summary: "summary";
+        event: "event";
+        session: "session";
+        detail: "detail";
+    }>;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Type for drill-down result */
+export type DrillDownResult = {
+    metric: string;
+    level: DrillLevel;
+    data: Record<string, unknown>;
+    parentMetric?: string;
+    depth: number;
+};
+/** Navigate to a drill-down level */
+export declare function navigateDrillDown(currentLevel: DrillLevel, targetLevel: DrillLevel, metric: string, extraFilters?: Record<string, unknown>): DrillDownResult;
+/** Get available drill-down paths for a metric */
+export declare function getDrillPaths(metric: string): Array<{
+    label: string;
+    level: DrillLevel;
+    path?: string;
+}>;

package/dist/dynamic-seo-mcp-tools.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Dynamic SEO & Performance MCP Tools
+ * Registers high-impact analytical engines (Recipe Rich Results, Course Credentials,
+ * SPA Memory Leaks, Navigation Proximity Depth, IndexNow, Syndication Feeds, AI Overviews,
+ * and Structured Data Aggregator) as typed MCP tools for autonomous AI agents.
+ */
+import { z } from "zod";
+import type { AnyOpenSeoToolDefinition, McpToolRegistrar } from "./ga4-gsc-mcp-tools";
+export declare const recipeRichSnippetInputSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    description: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    prepTime: z.ZodOptional<z.ZodString>;
+    cookTime: z.ZodOptional<z.ZodString>;
+    totalTime: z.ZodOptional<z.ZodString>;
+    recipeIngredient: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    recipeInstructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodObject<{
+        text: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>>;
+    nutrition: z.ZodOptional<z.ZodObject<{
+        calories: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        proteinContent: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    aggregateRating: z.ZodOptional<z.ZodObject<{
+        ratingValue: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        reviewCount: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const recipeRichSnippetOutputSchema: z.ZodObject<{
+    isEligibleForRichSnippet: z.ZodBoolean;
+    hasNutritionalInfo: z.ZodBoolean;
+    hasRating: z.ZodBoolean;
+    qualityScore: z.ZodNumber;
+    missingRequiredFields: z.ZodArray<z.ZodString>;
+    missingRecommendedFields: z.ZodArray<z.ZodString>;
+    issues: z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            warning: "warning";
+            info: "info";
+            critical: "critical";
+        }>;
+        field: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const validateRecipeRichSnippetTool: AnyOpenSeoToolDefinition;
+export declare const courseCredentialInputSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodEnum<{
+            Organization: "Organization";
+            Person: "Person";
+        }>>;
+        name: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        sameAs: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strip>>;
+    hasCourseInstance: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        courseMode: z.ZodOptional<z.ZodString>;
+        startDate: z.ZodOptional<z.ZodString>;
+        endDate: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    offers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        price: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        priceCurrency: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    educationalCredentialAwarded: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        credentialCategory: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+export declare const validateCourseCredentialTool: AnyOpenSeoToolDefinition;
+export declare const spaMemoryLeakInputSchema: z.ZodObject<{
+    samples: z.ZodArray<z.ZodObject<{
+        route: z.ZodString;
+        timestampMs: z.ZodNumber;
+        jsHeapSizeMb: z.ZodNumber;
+        totalDomNodes: z.ZodNumber;
+        detachedDomNodes: z.ZodNumber;
+        activeEventListeners: z.ZodNumber;
+        activeTimersCount: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const detectSpaMemoryLeaksTool: AnyOpenSeoToolDefinition;
+export declare const navigationClickDepthInputSchema: z.ZodObject<{
+    nodes: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        clickDepth: z.ZodNumber;
+        incomingLinkZoneDistribution: z.ZodRecord<z.ZodEnum<{
+            header_nav: "header_nav";
+            contextual_body: "contextual_body";
+            sidebar_nav: "sidebar_nav";
+            footer_boilerplate: "footer_boilerplate";
+        }>, z.ZodNumber>;
+        totalInboundInternalLinks: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const auditNavigationClickDepthTool: AnyOpenSeoToolDefinition;
+export declare const indexNowBatchInputSchema: z.ZodObject<{
+    host: z.ZodString;
+    key: z.ZodString;
+    keyLocation: z.ZodOptional<z.ZodString>;
+    urlList: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const validateIndexNowBatchTool: AnyOpenSeoToolDefinition;
+export declare const syndicationFeedInputSchema: z.ZodObject<{
+    feedType: z.ZodEnum<{
+        rss_2_0: "rss_2_0";
+        atom_1_0: "atom_1_0";
+    }>;
+    feedUrl: z.ZodString;
+    title: z.ZodString;
+    siteUrl: z.ZodString;
+    hasAutodiscoveryInHtmlHead: z.ZodBoolean;
+    items: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        link: z.ZodString;
+        guid: z.ZodOptional<z.ZodString>;
+        pubDateOrUpdated: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const auditSyndicationFeedTool: AnyOpenSeoToolDefinition;
+export declare const aiOverviewCitationInputSchema: z.ZodObject<{
+    passages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        headingContext: z.ZodOptional<z.ZodString>;
+        text: z.ZodString;
+        isListOrTable: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const scoreAiOverviewCitationsTool: AnyOpenSeoToolDefinition;
+export declare const structuredDataAggregateInputSchema: z.ZodObject<{
+    entities: z.ZodArray<z.ZodObject<{
+        entityType: z.ZodString;
+        url: z.ZodString;
+        isEligibleForRichResult: z.ZodBoolean;
+        criticalErrorsCount: z.ZodNumber;
+        warningsCount: z.ZodNumber;
+        missingRequiredFields: z.ZodArray<z.ZodString>;
+        missingRecommendedFields: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const synthesizeStructuredDataScoreTool: AnyOpenSeoToolDefinition;
+export declare const dynamicSeoMcpTools: AnyOpenSeoToolDefinition[];
+/**
+ * Registers all 8 dynamic SEO MCP tools onto the given registrar without casts.
+ */
+export declare function registerDynamicSeoMcpTools(registrar: McpToolRegistrar, tools?: AnyOpenSeoToolDefinition[]): void;

package/dist/ecommerce-offer-ladder.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 🪜 LynxSEO E-commerce Offer Ladder & Margin-Preserving Cart Engine
+ *
+ * Inspiré des fonctionnalités phares d'Alia Popups pour Shopify / WooCommerce :
+ * 1. Paliers dynamiques d'offres (Offer Laddering) selon le montant du panier.
+ * 2. Calcul du montant manquant pour débloquer la livraison gratuite ou un cadeau.
+ * 3. Préservation des marges commerciales : adapte le discount à la valeur client.
+ * 4. Compte à rebours de session et urgence psychologique déterministe.
+ */
+export interface OfferTier {
+    id: string;
+    minCartValue: number;
+    rewardType: "discount_percent" | "discount_fixed" | "free_shipping" | "free_gift";
+    rewardValue: number | string;
+    headline: string;
+    badge: string;
+    couponCode: string;
+}
+export interface OfferLadderConfig {
+    currency: string;
+    freeShippingThreshold: number;
+    tiers: OfferTier[];
+    urgencyDurationMinutes: number;
+}
+export declare const DEFAULT_OFFER_LADDER: OfferLadderConfig;
+export declare class EcommerceOfferLadder {
+    /**
+     * Évalue le panier actuel et détermine le palier atteint et le prochain objectif.
+     */
+    static evaluateCart(cartTotal: number, config?: OfferLadderConfig): {
+        currentTier: OfferTier;
+        nextTier?: OfferTier;
+        amountNeededForNextTier: number;
+        progressPercentToNextTier: number;
+        freeShippingUnlocked: boolean;
+        amountNeededForFreeShipping: number;
+        urgencySecondsRemaining: number;
+    };
+    /**
+     * Formate le message incitatif (Smart Progress Teaser) selon le panier.
+     */
+    static formatProgressTeaser(cartTotal: number, config?: OfferLadderConfig): string;
+}

package/dist/embed-facade-generator.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ⚡ LynxSEO*
+ * .
+ * Transforms heavy render-blocking iframes (YouTube, Vimeo, Google Maps) into
+ * zero-CLS, zero-TBT lightweight facades that load the real iframe only upon user interaction.
+ *
+ * Saves >500KB to 1MB of initial JavaScript execution per embed and eliminates layout shifts.
+ */
+export interface YouTubeFacadeOptions {
+    videoId: string;
+    title?: string;
+    aspectRatio?: "16/9" | "4/3" | "1/1";
+    thumbnailQuality?: "maxresdefault" | "hqdefault" | "sddefault";
+    customThumbnailUrl?: string;
+    className?: string;
+}
+export interface VimeoFacadeOptions {
+    videoId: string;
+    title?: string;
+    aspectRatio?: "16/9" | "4/3";
+    thumbnailUrl?: string;
+    className?: string;
+}
+export interface GoogleMapsFacadeOptions {
+    embedSrc: string;
+    title?: string;
+    aspectRatio?: "16/9" | "4/3" | "21/9";
+    staticMapPlaceholderUrl?: string;
+    buttonLabel?: string;
+    className?: string;
+}
+export declare class EmbedFacadeGenerator {
+    /**
+     * Generates a lightweight YouTube facade HTML with responsive aspect ratio.
+     */
+    static generateYouTubeFacade(options: YouTubeFacadeOptions): {
+        html: string;
+        id: string;
+    };
+    /**
+     * Generates a lightweight Vimeo facade HTML.
+     */
+    static generateVimeoFacade(options: VimeoFacadeOptions): {
+        html: string;
+        id: string;
+    };
+    /**
+     * Generates a lightweight Google Maps facade HTML.
+     */
+    static generateGoogleMapsFacade(options: GoogleMapsFacadeOptions): {
+        html: string;
+        id: string;
+    };
+    /**
+     * Helper that detects unoptimized heavy iframes in raw HTML and proposes replacement facades.
+     */
+    static auditPageEmbeds(html: string): {
+        totalHeavyEmbeds: number;
+        youtubeCount: number;
+        mapsCount: number;
+        vimeoCount: number;
+        recommendation: string;
+    };
+}

package/dist/embeddable-seo-widget.d.ts

@@ -1,5 +1,5 @@
 /**
- * 🧩 Embeddable Client SEO & Discovery Widget (Inspiration: pages-seo/widget.js.js)
+ * 🧩 Embeddable Client SEO & Discovery Widget
  *
  * Provides a lightweight (< 5KB) vanilla JavaScript snippet generator that allows external
  * client sites to embed interactive directory navigation or related programmatic links.

package/dist/engine-compat.d.ts

@@ -0,0 +1,80 @@
+/**
+ * engine-compat.ts — shims de compatibilité pour les exports attendus par
+ * l'app mais non encore présents dans `@lynxseo/engine`.
+ *
+ * Ces types et stubs permettent au typecheck de passer sans inventer de
+ * comportement métier. Chaque entité est marquée `@deprecated` pour indiquer
+ * qu'il s'agit d'un placeholder à remplacer par une vraie implémentation.
+ */
+import type { BanditArm } from "./bandit-optimizer";
+export interface BanditArmObservation {
+    variantId: string;
+    visitors: number;
+    conversions: number;
+}
+export interface SequentialOptions {
+    alpha: number;
+    beta: number;
+    minimumDetectableEffect: number;
+}
+export interface BanditWinner {
+    hasWinner: boolean;
+    winningArm: BanditArm | null;
+    confidence: number;
+    liftPercent: number;
+}
+export declare function selectBanditArm(_obs: BanditArmObservation[], _opts?: {
+    seed?: string;
+}): BanditArmObservation;
+export interface SequentialResult {
+    decision: "continue" | "stop_accept_h1" | "stop_accept_h0";
+    confidence: number;
+    detail: {
+        logLikelihoodRatio: number;
+        observations: number;
+        upperBound: number;
+        lowerBound: number;
+    };
+}
+export declare function shouldStopSequential(_control: {
+    converted: boolean;
+}[], _challenger: {
+    converted: boolean;
+}[], _options: SequentialOptions): SequentialResult;
+export declare function winProbabilities(_obs: BanditArmObservation[], _opts?: {
+    samples?: number;
+}): Record<string, number>;
+export interface AbExperiment {
+    id: string;
+    name: string;
+    status: "draft" | "running" | "paused" | "completed";
+    targetUrlPattern?: string;
+    goalEvent?: string;
+}
+export interface AbExperimentEvaluation {
+    experimentId: string;
+    winnerVariantId: string | null;
+    variants: {
+        variantId: string;
+        name: string;
+        visitors: number;
+        conversions: number;
+        impressions: number;
+        conversionRate?: number;
+        relativeUplift?: number | null;
+        winProbabilityPct?: number;
+    }[];
+    hasWinner: boolean;
+    winningArm: {
+        id: string;
+        name: string;
+    } | null;
+    confidence: number;
+    liftPercent: number;
+}
+export declare namespace clickstreamHeatmap {
+    const version = "1.0.0";
+}
+export declare namespace segmentBuilder {
+    const version = "1.0.0";
+}

package/dist/engine.d.ts

@@ -25,6 +25,8 @@ import { LagoTokenMeter } from "./lago-token-meter";
 import { SiteAuditor } from "./site-auditor";
 import { SchemaGraphBuilder } from "./schema-builder";
 import { DeepCrawlerAuditor, type SiteAuditSummary, type CrawlOptions } from "./site-crawler";
+import { WaybackClient } from "./wayback-client";
+import { extractReaderContent } from "./reader-cleaner";
 export type EngineConfig = LynxSeoConfig;
 export declare class LynxSeoEngine {
     private config;
@@ -39,6 +41,8 @@ export declare class LynxSeoEngine {
     readonly crawler: typeof DeepCrawlerAuditor;
     readonly schema: typeof SchemaGraphBuilder;
     readonly indexNow: typeof IndexNowClient;
+    readonly wayback: WaybackClient;
+    readonly reader: typeof extractReaderContent;
     constructor(config: LynxSeoConfig);
     /**
      * Submits generated URLs to Bing, Yandex, Seznam, and Naver via IndexNow.

package/dist/error-tracking.d.ts

@@ -0,0 +1,20 @@
+export interface CapturedError {
+    type: string;
+    message: string;
+    stack: string | null;
+    count: number;
+    firstSeen: string;
+    lastSeen: string;
+}
+export interface ErrorTrackingState {
+    errors: CapturedError[];
+    updatedAt: string;
+}
+export declare function createErrorTrackingState(now?: Date): ErrorTrackingState;
+export declare function captureError(state: ErrorTrackingState, err: {
+    type?: string;
+    message: string;
+    stack?: string | null;
+}, now?: Date): ErrorTrackingState;
+export declare function aggregateByType(state: ErrorTrackingState): Record<string, number>;
+export declare function topErrors(state: ErrorTrackingState, n?: number): CapturedError[];

package/dist/event-taxonomy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Business-model event taxonomy: the documented event library that Pulse,
+ * the tracking-plan generator and the conversion snippet generator share.
+ *
+ * Event names are snake_case verbs in the past or present tense (`page_view`,
+ * `signup_complete`). Properties are snake_case nouns. A funnel step always
+ * references an event declared in this file, which is asserted by the tests.
+ */
+export type BusinessModel = "saas" | "ecommerce" | "lead_generation" | "marketplace" | "content_media";
+export type EventCategory = "marketing" | "product" | "monetization" | "ecommerce" | "b2b" | "lifecycle";
+export interface EventDefinition {
+    readonly name: string;
+    readonly category: EventCategory;
+    readonly description: string;
+    readonly properties: readonly string[];
+    readonly requiredProperties: readonly string[];
+}
+export interface FunnelStepDefinition {
+    readonly event: string;
+    readonly label: string;
+}
+export interface FunnelTemplate {
+    readonly id: string;
+    readonly name: string;
+    readonly businessModels: readonly BusinessModel[];
+    readonly steps: readonly FunnelStepDefinition[];
+}
+export interface EventCatalog {
+    readonly model: BusinessModel;
+    readonly categories: readonly EventCategory[];
+    readonly events: readonly EventDefinition[];
+    readonly funnels: readonly FunnelTemplate[];
+}
+export declare function validateEventName(name: string): boolean;
+export declare function getEventLibrary(model: BusinessModel): readonly EventDefinition[];
+export declare function getFunnelTemplates(model: BusinessModel): readonly FunnelTemplate[];
+export declare function getEventDefinition(name: string): EventDefinition | undefined;
+export declare function hasEvent(name: string): boolean;
+export declare function buildEventCatalog(model: BusinessModel): EventCatalog;

package/dist/executive-report-generator.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Executive Report Generator — Moteur de génération de synthèses analytiques et SEO exécutives
+ * Conçu pour les exports PDF/Print prêts pour la direction et les clients.
+ */
+export interface ExecutiveReportOptions {
+    projectId: string;
+    projectName: string;
+    clientName?: string;
+    periodLabel: string;
+    generatedAt?: string;
+    themeColor?: string;
+    metrics: {
+        totalVisitors: number;
+        visitorsChangePct: number;
+        totalPageViews: number;
+        bounceRatePct: number;
+        avgSessionDurationSeconds: number;
+        conversionRatePct: number;
+        conversionsCount: number;
+        attributedRevenue?: number;
+    };
+    topPages: {
+        path: string;
+        views: number;
+        sharePct: number;
+    }[];
+    topChannels: {
+        channel: string;
+        visitors: number;
+        sharePct: number;
+    }[];
+    aiTraffic?: {
+        totalAiVisits: number;
+        sharePct: number;
+        topAiEngines: {
+            name: string;
+            visits: number;
+        }[];
+    };
+    seoWins?: {
+        keyword: string;
+        position: number;
+        positionChange: number;
+        impressions: number;
+    }[];
+    strategicRecommendations?: string[];
+}
+export interface GeneratedExecutiveReport {
+    id: string;
+    title: string;
+    generatedAt: string;
+    html: string;
+    summary: {
+        healthScore: number;
+        growthSignal: "strong_growth" | "moderate_growth" | "stable" | "decline";
+        keyTakeaway: string;
+    };
+}
+export declare function generateExecutiveReport(options: ExecutiveReportOptions): GeneratedExecutiveReport;

package/dist/experiment-assignment.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Assignment déterministe d'un visiteur à une variante d'expérience A/B.
+ *
+ * Le visiteur est placé dans un « bucket » en hachant l'identifiant de
+ * l'expérience avec celui du visiteur : un même visiteur retombe donc toujours
+ * sur la même variante pour une expérience donnée, sur tous les runtimes et
+ * après chaque rechargement. Le calcul est pur et sans dépendance : aucune
+ * source d'aléa, aucune horloge, aucune entrée/sortie.
+ */
+export interface ExperimentAssignmentVariant {
+    /** Identifiant stable de la variante. */
+    key: string;
+    /** Poids relatif d'allocation (défaut : 1 → répartition égale). */
+    weight?: number;
+}
+export interface ExperimentAssignmentInput {
+    /** Identifiant qui sert de graine au hachage. */
+    experimentId: string;
+    /** Variantes disponibles, dans l'ordre de priorité. */
+    variants: ExperimentAssignmentVariant[];
+}
+/**
+ * Hachage FNV-1a 32 bits : stable d'un runtime à l'autre et entre deux
+ * exécutions du même processus.
+ */
+export declare function stableHash(value: string): number;
+/**
+ * Assigne un visiteur à une variante de l'expérience.
+ *
+ * Retourne `null` lorsque l'expérience est inconnue (absente), dépourvue de
+ * variante, ou sans aucun poids positif : l'appelant sert alors l'expérience de
+ * contrôle par défaut.
+ */
+export declare function assignExperimentVariant(experiment: ExperimentAssignmentInput | null | undefined, visitorId: string): string | null;

package/dist/experiment-framework.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Experimentation framework around the statistical engine: hypothesis format,
+ * ICE prioritization, sample-size planning, guardrail metrics and readout
+ * decisions. `ab-testing-significance.ts` owns the maths; this file owns the
+ * process that keeps experiments comparable across teams.
+ */
+export type ExperimentDirection = "increase" | "decrease";
+export type ExperimentMetricType = "primary" | "secondary" | "guardrail";
+export type ExperimentConfidence = 0.9 | 0.95 | 0.99;
+export type ExperimentPower = 0.8 | 0.9;
+export type ExperimentPriority = "high" | "medium" | "low";
+export type ExperimentDecision = "ship" | "iterate" | "stop" | "extend";
+export interface HypothesisInput {
+    change: string;
+    audience: string;
+    metric: string;
+    expectedDirection: ExperimentDirection;
+    /** Relative lift, e.g. 0.05 for +5%. */
+    minimumDetectableEffect: number;
+    rationale: string;
+}
+export interface ExperimentHypothesis extends HypothesisInput {
+    statement: string;
+}
+export interface IceInput {
+    /** 1–10 */
+    impact: number;
+    /** 1–10 */
+    confidence: number;
+    /** 1–10: how cheap the test is to run. */
+    ease: number;
+}
+export interface IceScore {
+    impact: number;
+    confidence: number;
+    ease: number;
+    total: number;
+    priority: ExperimentPriority;
+    recommendation: string;
+}
+export interface ExperimentMetric {
+    name: string;
+    type: ExperimentMetricType;
+    baselineRate?: number;
+    minimumDetectableEffect?: number;
+    direction?: ExperimentDirection;
+}
+export interface ExperimentPlanInput {
+    hypothesis: ExperimentHypothesis;
+    metrics: ExperimentMetric[];
+    /** Unique visitors available per day for the test surface. */
+    dailyTraffic?: number;
+    confidenceLevel?: ExperimentConfidence;
+    power?: ExperimentPower;
+}
+export interface ExperimentPlan {
+    hypothesis: ExperimentHypothesis;
+    primaryMetric: ExperimentMetric;
+    secondaryMetrics: ExperimentMetric[];
+    guardrails: ExperimentMetric[];
+    sampleSizePerVariant: number | null;
+    totalSampleSize: number | null;
+    estimatedDays: number | null;
+    minimumRuntimeDays: number;
+    decisionRules: readonly string[];
+    cadence: readonly string[];
+}
+export interface ExperimentReadout {
+    pValue: number;
+    relativeLift: number;
+    achievedSampleSizePerVariant: number;
+    requiredSampleSizePerVariant: number;
+    minimumDetectableEffect: number;
+    guardrailRegressed: boolean;
+    alpha?: number;
+}
+export interface ExperimentVerdict {
+    decision: ExperimentDecision;
+    rationale: string;
+}
+export declare const EXPERIMENT_CADENCE: readonly string[];
+export declare function buildHypothesis(input: HypothesisInput): ExperimentHypothesis;
+export declare function scoreIce(input: IceInput): IceScore;
+export declare function planExperiment(input: ExperimentPlanInput): ExperimentPlan;
+export declare function decideExperiment(readout: ExperimentReadout): ExperimentVerdict;