@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/sql-engine-advanced.d.ts

@@ -0,0 +1,476 @@
+/**
+ * Moteur SQL avancé : analyse, plan de requête, autocomplétion, validation,
+ * exécution sûre.
+ *
+ * Cinq briques, volontairement séparées, toutes déterministes et sans I/O :
+ *
+ * 1. **Parseur** — un parseur descendant récursif (`SELECT`/`WITH`, jointures,
+ *    agrégations, `CASE`, `CAST`, sous-requêtes) produit un AST typé. Aucune
+ *    évaluation de constante n'est exécutée : le moteur n'exécute jamais de SQL
+ *    écrit par l'utilisateur, il l'analyse.
+ * 2. **Plan de requête** — coût estimé, étapes ordonnées, hints d'index et
+ *    avertissements. Le plan est une *estimation* statique : il ne prétend
+ *    jamais avoir interrogé la base.
+ * 3. **Autocomplétion** — contexte de saisie (clause, préfixe, qualificateur)
+ *    puis suggestions triées, à partir d'un catalogue de tables.
+ * 4. **Validation** — erreurs bloquantes (table inconnue, colonne inconnue,
+ *    requête non en lecture seule, plusieurs statements) et avertissements
+ *    (absence de `LIMIT`, `SELECT *`, jointure cartésienne).
+ * 5. **Exécution sûre** — un wrapper qui refuse tout statement non
+ *    `SELECT`/`WITH`, borne le nombre de lignes, applique un `LIMIT` même
+ *    quand l'utilisateur l'a oublié, impose un délai maximal et interrompt la
+ *    requête en cours de route.
+ *
+ * Le garde-fou « lecture seule » s'appuie sur la liste canonique
+ * `FORBIDDEN_KEYWORDS` de `semantic/sql-guard`, mais elle est appliquée à
+ * l'**AST** et non à la chaîne brute : `SELECT 'drop table'` est un SELECT
+ * légitime, alors qu'une colonne nommée `drop` ne l'est pas. Une seule liste
+ * de mots interdits, une seule règle, appliquée au bon niveau.
+ *
+ * Aucune dépendance externe, aucun accès réseau, aucun état global.
+ */
+export type SqlColumnType = "text" | "integer" | "real" | "boolean" | "date" | "timestamp" | "json" | "blob" | "unknown";
+export interface SqlColumnDef {
+    name: string;
+    type: SqlColumnType;
+    nullable?: boolean;
+    primaryKey?: boolean;
+    description?: string;
+}
+export interface SqlIndexDef {
+    name: string;
+    columns: string[];
+    unique?: boolean;
+}
+export interface SqlTableDef {
+    name: string;
+    columns: SqlColumnDef[];
+    indexes?: SqlIndexDef[];
+    description?: string;
+    /** Estimation de cardinalité, utilisée par le planificateur. */
+    rowCount?: number;
+}
+export interface SqlCatalog {
+    tables: SqlTableDef[];
+}
+export type SqlTokenType = "keyword" | "identifier" | "number" | "string" | "operator" | "punct" | "parameter" | "eof";
+export interface SqlToken {
+    type: SqlTokenType;
+    /** Texte brut, tel qu'il apparaît dans la source. */
+    text: string;
+    /** Valeur normalisée : majuscules pour un mot-clé, texte déquoted pour un identifiant. */
+    value: string;
+    start: number;
+    end: number;
+}
+/**
+ * Découpe une requête en jetons. Les commentaires sont ignorés (ils ne
+ * portent aucune sémantique), les chaînes et identifiants quotés sont lus
+ * comme un seul jeton.
+ */
+export declare function tokenizeSql(sql: string): SqlToken[];
+export type SqlExpr = SqlLiteralExpr | SqlPlaceholderExpr | SqlColumnRefExpr | SqlStarExpr | SqlFunctionExpr | SqlBinaryExpr | SqlUnaryExpr | SqlInExpr | SqlBetweenExpr | SqlIsNullExpr | SqlLikeExpr | SqlCaseExpr | SqlCastExpr | SqlSubqueryExpr | SqlExistsExpr | SqlListExpr;
+export interface SqlLiteralExpr {
+    kind: "literal";
+    value: string | number | boolean | null;
+    dataType: "string" | "number" | "boolean" | "null";
+    raw: string;
+}
+export interface SqlPlaceholderExpr {
+    kind: "placeholder";
+    name: string;
+    raw: string;
+}
+export interface SqlColumnRefExpr {
+    kind: "column";
+    /** Qualificateur (table ou alias), `null` si la colonne est non qualifiée. */
+    table: string | null;
+    name: string;
+}
+export interface SqlStarExpr {
+    kind: "star";
+    table: string | null;
+}
+export interface SqlFunctionExpr {
+    kind: "function";
+    name: string;
+    args: SqlExpr[];
+    distinct: boolean;
+    star: boolean;
+}
+export type SqlBinaryOperator = "or" | "and" | "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=" | "+" | "-" | "*" | "/" | "%" | "||";
+export interface SqlBinaryExpr {
+    kind: "binary";
+    operator: SqlBinaryOperator;
+    left: SqlExpr;
+    right: SqlExpr;
+}
+export interface SqlUnaryExpr {
+    kind: "unary";
+    operator: "not" | "-" | "+";
+    operand: SqlExpr;
+}
+export interface SqlInExpr {
+    kind: "in";
+    expr: SqlExpr;
+    list: SqlExpr[];
+    subquery: SqlSelectStatement | null;
+    negated: boolean;
+}
+export interface SqlBetweenExpr {
+    kind: "between";
+    expr: SqlExpr;
+    lower: SqlExpr;
+    upper: SqlExpr;
+    negated: boolean;
+}
+export interface SqlIsNullExpr {
+    kind: "is_null";
+    expr: SqlExpr;
+    negated: boolean;
+}
+export interface SqlLikeExpr {
+    kind: "like";
+    expr: SqlExpr;
+    pattern: SqlExpr;
+    negated: boolean;
+    caseInsensitive: boolean;
+}
+export interface SqlCaseExpr {
+    kind: "case";
+    operand: SqlExpr | null;
+    branches: {
+        when: SqlExpr;
+        then: SqlExpr;
+    }[];
+    fallback: SqlExpr | null;
+}
+export interface SqlCastExpr {
+    kind: "cast";
+    expr: SqlExpr;
+    targetType: string;
+}
+export interface SqlSubqueryExpr {
+    kind: "subquery";
+    statement: SqlSelectStatement;
+}
+export interface SqlExistsExpr {
+    kind: "exists";
+    statement: SqlSelectStatement;
+    negated: boolean;
+}
+export interface SqlListExpr {
+    kind: "list";
+    items: SqlExpr[];
+}
+export type SqlJoinType = "inner" | "left" | "right" | "full" | "cross";
+export interface SqlTableRef {
+    kind: "table" | "subquery";
+    name: string;
+    alias: string | null;
+    statement: SqlSelectStatement | null;
+}
+export interface SqlJoinRef {
+    joinType: SqlJoinType;
+    table: SqlTableRef;
+    condition: SqlExpr | null;
+    using: string[];
+}
+export interface SqlFromClause {
+    base: SqlTableRef;
+    joins: SqlJoinRef[];
+}
+export interface SqlSelectItem {
+    expr: SqlExpr;
+    alias: string | null;
+}
+export interface SqlOrderItem {
+    expr: SqlExpr;
+    direction: "asc" | "desc";
+}
+export interface SqlLimitClause {
+    /** Valeur littérale, `null` si la limite est un paramètre. */
+    value: number | null;
+    /** Offset du mot-clé `LIMIT` dans la source. */
+    keywordAt: number;
+    /** Offset de la valeur littérale, `null` si dynamique. */
+    valueAt: number | null;
+    valueEnd: number | null;
+    dynamic: boolean;
+}
+export interface SqlOffsetClause {
+    value: number | null;
+    keywordAt: number;
+    dynamic: boolean;
+}
+export interface SqlCte {
+    name: string;
+    columns: string[];
+    statement: SqlSelectStatement;
+}
+export interface SqlSelectStatement {
+    type: "select";
+    ctes: SqlCte[];
+    distinct: boolean;
+    items: SqlSelectItem[];
+    from: SqlFromClause | null;
+    where: SqlExpr | null;
+    groupBy: SqlExpr[];
+    having: SqlExpr | null;
+    orderBy: SqlOrderItem[];
+    limit: SqlLimitClause | null;
+    offset: SqlOffsetClause | null;
+    /** Début du statement dans la source. */
+    start: number;
+    /** Fin du statement (dernier jeton consommé) dans la source. */
+    end: number;
+}
+export declare class SqlParseError extends Error {
+    readonly position: number;
+    readonly expected: string;
+    constructor(message: string, position: number, expected?: string);
+}
+/**
+ * Analyse une requête SQL et retourne son AST.
+ *
+ * @throws {SqlParseError} si la requête est syntaxiquement invalide.
+ */
+export declare function parseSql(sql: string): SqlSelectStatement;
+export type SqlParseResult = {
+    ok: true;
+    statement: SqlSelectStatement;
+} | {
+    ok: false;
+    error: SqlParseError;
+};
+/** Variante non bloquante de {@link parseSql}. */
+export declare function tryParseSql(sql: string): SqlParseResult;
+/** Re-rend un statement en SQL lisible. */
+export declare function formatStatement(statement: SqlSelectStatement): string;
+export interface SqlScopeTable {
+    name: string;
+    alias: string | null;
+    columns: SqlColumnDef[] | null;
+}
+export interface SqlScope {
+    tables: SqlScopeTable[];
+}
+export declare function collectColumnRefs(expr: SqlExpr, out?: SqlColumnRefExpr[]): SqlColumnRefExpr[];
+export declare const SQL_AGGREGATE_FUNCTIONS: Set<string>;
+export declare const SCALAR_FUNCTIONS: string[];
+export declare const SQL_KEYWORD_SUGGESTIONS: string[];
+export type SqlPlanStepKind = "scan" | "index_scan" | "filter" | "join" | "aggregate" | "sort" | "limit" | "project";
+export interface SqlPlanStep {
+    id: string;
+    kind: SqlPlanStepKind;
+    label: string;
+    detail: string;
+    estimatedRows: number;
+    estimatedCost: number;
+    tables: string[];
+    index: string | null;
+}
+export interface SqlIndexHint {
+    table: string;
+    index: string | null;
+    columns: string[];
+    /** `false` quand l'index est suggéré mais n'existe pas encore. */
+    available: boolean;
+    reason: string;
+}
+export interface SqlQueryPlan {
+    sql: string;
+    statement: SqlSelectStatement;
+    steps: SqlPlanStep[];
+    tables: string[];
+    estimatedRows: number;
+    estimatedCost: number;
+    /** Score de complexité 0..100. */
+    complexity: number;
+    indexHints: SqlIndexHint[];
+    warnings: string[];
+}
+export interface SqlPlanOptions {
+    catalog?: SqlCatalog;
+    /** Cardinalité supposée pour une table absente du catalogue. */
+    defaultTableRows?: number;
+    /** Sélectivité supposée pour un prédicat de filtrage. */
+    defaultSelectivity?: number;
+}
+/**
+ * Construit le plan de requête : étapes ordonnées, coût estimé, hints d'index,
+ * avertissements.
+ *
+ * Le plan est **statique** : il s'appuie sur le catalogue fourni et sur des
+ * hypothèses explicites, jamais sur une base interrogée.
+ */
+export declare function planSql(sql: string, options?: SqlPlanOptions): SqlQueryPlan;
+/** Résumé textuel du plan, une ligne par étape. */
+export declare function formatQueryPlan(plan: SqlQueryPlan): string[];
+export type SqlCompletionKind = "table" | "column" | "function" | "aggregate" | "keyword" | "alias";
+export interface SqlCompletion {
+    label: string;
+    kind: SqlCompletionKind;
+    insertText: string;
+    detail: string;
+    score: number;
+}
+export type SqlCompletionClause = "select" | "from" | "join" | "on" | "where" | "group" | "order" | "having" | "unknown";
+export interface SqlCompletionContext {
+    clause: SqlCompletionClause;
+    prefix: string;
+    qualifier: string | null;
+    tables: {
+        name: string;
+        alias: string | null;
+    }[];
+}
+export interface SqlCompletionOptions {
+    catalog?: SqlCatalog;
+    /** Position du curseur dans la chaîne (par défaut : fin de la chaîne). */
+    cursor?: number;
+    limit?: number;
+}
+/**
+ * Analyse tolérante du `FROM` : la requête est en cours de saisie, elle n'est
+ * pas forcément parsable. On lit donc les jetons comme un flux, sans exiger
+ * une grammaire complète.
+ */
+export declare function scanSqlScope(sql: string): {
+    name: string;
+    alias: string | null;
+}[];
+/** Détecte la clause, le préfixe et le qualificateur au curseur. */
+export declare function detectSqlContext(sql: string, options?: SqlCompletionOptions): SqlCompletionContext;
+/**
+ * Propose des complétions pour la position du curseur.
+ *
+ * Le catalogue est optionnel : sans catalogue, le moteur propose mots-clés et
+ * fonctions, ce qui reste utile pour un éditeur SQL vierge.
+ */
+export declare function completeSql(sql: string, options?: SqlCompletionOptions): SqlCompletion[];
+export type SqlValidationSeverity = "error" | "warning" | "info";
+export type SqlValidationCode = "empty_query" | "syntax_error" | "unsupported_statement" | "not_read_only" | "multiple_statements" | "unknown_table" | "unknown_column" | "ambiguous_column" | "aggregate_in_where" | "select_star" | "missing_limit" | "limit_too_high" | "dynamic_limit" | "cartesian_join";
+export interface SqlValidationIssue {
+    code: SqlValidationCode;
+    severity: SqlValidationSeverity;
+    message: string;
+    table: string | null;
+    column: string | null;
+    position: number | null;
+    hint: string | null;
+}
+export interface SqlValidationResult {
+    ok: boolean;
+    issues: SqlValidationIssue[];
+    errors: SqlValidationIssue[];
+    warnings: SqlValidationIssue[];
+    statement: SqlSelectStatement | null;
+    tables: string[];
+    columns: string[];
+}
+export interface SqlValidationOptions {
+    catalog?: SqlCatalog;
+    /** Exige une clause LIMIT (erreur bloquante). */
+    requireLimit?: boolean;
+    /** Plafond de lignes ; au-delà, avertissement. */
+    maxLimit?: number;
+    /** Interdit tout statement autre que SELECT/WITH. Défaut : `true`. */
+    readOnly?: boolean;
+}
+/**
+ * Valide une requête SQL : erreurs bloquantes d'abord, puis avertissements.
+ *
+ * Le catalogue est optionnel ; sans lui, seules les vérifications
+ * syntaxiques et structurelles sont effectuées (jamais de fausse erreur sur
+ * une colonne simplement absente du catalogue).
+ */
+export declare function validateSql(sql: string, options?: SqlValidationOptions): SqlValidationResult;
+export interface SqlExecutionRequest {
+    sql: string;
+    params: readonly unknown[];
+    signal: AbortSignal;
+}
+export interface SqlExecutorResult {
+    rows: readonly unknown[];
+    columns?: readonly string[];
+}
+export type SqlExecutor = (request: SqlExecutionRequest) => Promise<SqlExecutorResult>;
+export type SqlExecutionErrorCode = "empty_query" | "syntax_error" | "validation_failed" | "not_read_only" | "timeout" | "executor_error";
+export interface SqlExecutionSuccess {
+    ok: true;
+    sql: string;
+    params: readonly unknown[];
+    rows: unknown[];
+    columns: string[];
+    rowCount: number;
+    truncated: boolean;
+    durationMs: number;
+    plan: SqlQueryPlan;
+    issues: SqlValidationIssue[];
+}
+export interface SqlExecutionFailure {
+    ok: false;
+    sql: string;
+    code: SqlExecutionErrorCode;
+    message: string;
+    durationMs: number;
+    plan: SqlQueryPlan | null;
+    issues: SqlValidationIssue[];
+}
+export type SqlExecutionResult = SqlExecutionSuccess | SqlExecutionFailure;
+export type SqlExecutionEventType = "start" | "success" | "failure" | "timeout";
+export interface SqlExecutionEvent {
+    type: SqlExecutionEventType;
+    sql: string;
+    durationMs: number;
+    rowCount: number;
+    error: string | null;
+}
+export interface SafeSqlOptions {
+    catalog?: SqlCatalog;
+    /** Nombre maximal de lignes renvoyées. Défaut : 1000. */
+    maxRows?: number;
+    /** `LIMIT` maximal toléré dans la requête. Défaut : 10000. */
+    maxLimit?: number;
+    /** Délai maximal d'exécution, en millisecondes. Défaut : 5000. */
+    timeoutMs?: number;
+    /** Interdit tout statement autre que SELECT/WITH. Défaut : `true`. */
+    readOnly?: boolean;
+    /** Exige une clause LIMIT (erreur bloquante). Défaut : `false`. */
+    requireLimit?: boolean;
+    /** Horloge injectable (tests). */
+    now?: () => number;
+    /** Observabilité : chaque étape émet un évènement. */
+    onEvent?: (event: SqlExecutionEvent) => void;
+}
+/**
+ * Réécrit la requête pour qu'elle renvoie au plus `limit` lignes.
+ *
+ * Trois cas : limite existante et trop large (on remplace la valeur),
+ * `OFFSET` sans `LIMIT` (on insère la limite devant l'offset), absence des
+ * deux (on insère la limite à la fin du statement).
+ */
+export declare function applyRowLimit(sql: string, statement: SqlSelectStatement, limit: number): string;
+/**
+ * Exécute une requête sous garde-fous.
+ *
+ * L'ordre des contrôles est déterministe : lecture seule, validation,
+ * bornage des lignes, délai maximal. Un échec de validation **n'atteint
+ * jamais** l'exécuteur : la base n'est pas touchée.
+ */
+export declare function executeSqlSafely(sql: string, executor: SqlExecutor, options?: SafeSqlOptions): Promise<SqlExecutionResult>;
+export interface SqlEngine {
+    parse(sql: string): SqlSelectStatement;
+    plan(sql: string): SqlQueryPlan;
+    validate(sql: string): SqlValidationResult;
+    complete(sql: string, options?: SqlCompletionOptions): SqlCompletion[];
+    execute(sql: string, params?: readonly unknown[]): Promise<SqlExecutionResult>;
+}
+/**
+ * Assemble les cinq briques derrière une façade unique.
+ *
+ * L'exécuteur est injecté : le moteur n'ouvre jamais de connexion lui-même,
+ * il ne fait qu'appliquer ses garde-fous autour de l'exécuteur fourni.
+ */
+export declare function createSqlEngine(executor: SqlExecutor, options?: SafeSqlOptions): SqlEngine;

package/dist/sql-query-builder.d.ts

@@ -0,0 +1,23 @@
+export interface SqlQuery {
+    text: string;
+    params: unknown[];
+}
+export declare class SqlQueryBuilder {
+    private table;
+    private columns;
+    private where;
+    private orderBy;
+    private limitN;
+    private offsetN;
+    from(table: string): this;
+    select(...cols: string[]): this;
+    whereEq(col: string, value: unknown): this;
+    whereLike(col: string, value: string): this;
+    whereIn(col: string, values: unknown[]): this;
+    orderByAsc(col: string): this;
+    orderByDesc(col: string): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    build(): SqlQuery;
+}
+export declare function selectFrom(table: string): SqlQueryBuilder;

package/dist/static-viz-renderer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 📊 StaticVizRenderer - Headless Pure SVG Charting Engine
+ * Rendu 100% TypeScript edge, sans runtime JVM.
+ *
+ * Génère des graphiques vectoriels SVG autonomes, ultra-légers et sans aucune
+ * dépendance DOM (zéro Puppeteer, zéro Canvas, zéro Playwright).
+ * Idéal pour :
+ * - Les rapports SEO PDF & HTML autonomes
+ * - Les cartes OpenGraph et résumés par email / webhook
+ * - Les widgets intégrables et exports statiques
+ *
+ * Implémentation : délègue la géométrie à `chart-plan/geometry` puis le rendu
+ * SVG à `chart-plan/renderers/svg` (`renderPlanToSvg`).
+ */
+import type { BarChartOptions, BarItem, GaugeOptions, MetricCardInput, SparklineOptions, TrendChartOptions, TrendPoint } from "./chart-plan/geometry";
+export type { BarChartOptions, BarItem, GaugeOptions, MetricCardInput, SparklineOptions, TimelineAnnotation, TrendChartOptions, TrendPoint, } from "./chart-plan/geometry";
+export declare const StaticVizRenderer: {
+    /** Rendu d'une sparkline SVG (headless). */
+    renderSparkline(values: number[], options?: SparklineOptions): string;
+    /** Rendu d'une courbe temporelle SVG (headless). */
+    renderTrendChart(points: TrendPoint[], options?: TrendChartOptions): string;
+    /** Rendu d'un diagramme en barres SVG (headless). */
+    renderBarChart(bars: BarItem[], options?: BarChartOptions): string;
+    /** Rendu d'une jauge SVG (headless). */
+    renderGauge(score: number, options?: GaugeOptions): string;
+    /** Rendu d'un scorecard KPI SVG (headless). */
+    renderMetricCard(card: MetricCardInput): string;
+    /** Rendu d'un scorecard KPI SVG (headless). */
+    renderMetricScorecard(card: MetricCardInput): string;
+};

package/dist/strategic-roadmap-generator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 🗺️ Strategic SEO Roadmap Generator (4-Phase Architecture)
+ *
+ * Tailors a 12-month, 4-phase SEO execution plan based on business vertical:
+ * - SaaS (pSEO, feature comparisons, AEO direct answer, high-intent BOFU)
+ * - Local Business (GBP 3-pack, geo-mesh linking, NAP citations, local schema)
+ * - E-Commerce (GTIN/Product variants, category facet pruning, merchant center)
+ * - Publisher / Media (Topical authority hubs, rapid indexing, Google News schema)
+ * - SEO Agency (Client audit cadence, white-label reporting, quick-wins backlog)
+ */
+export type BusinessVertical = "saas" | "local" | "ecommerce" | "publisher" | "agency";
+export interface RoadmapPhase {
+    phaseNumber: number;
+    phaseName: string;
+    timeframe: string;
+    objective: string;
+    keyDeliverables: string[];
+    kpisToTrack: string[];
+    falsifiabilityCheck: string;
+}
+export interface StrategicRoadmapResult {
+    businessName: string;
+    vertical: BusinessVertical;
+    executiveSummary: string;
+    phases: RoadmapPhase[];
+    projectedOrganicTrafficGrowth: string;
+    recommendedStack: string[];
+}
+export declare class StrategicRoadmapGenerator {
+    /**
+     * Generates a tailor-made 4-phase strategic roadmap.
+     */
+    static generateRoadmap(businessName: string, vertical: BusinessVertical): StrategicRoadmapResult;
+}

package/dist/supercocon-hierarchy-architect.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 🌳 Supercocon Hierarchy Architect
+ *
+ * Implements the 3-level hierarchical "Supercocon" structure:
+ * - Level 1: Page Mère (Pillar / Cocon Master)
+ * - Level 2: Pages Filles (Thematic Silos)
+ * - Level 3: Pages Petites-Filles (Long-tail Precision Articles)
+ *
+ * Enforces strict semantic hermetic linking rules:
+ * - Mother page links down to all Daughters
+ * - Daughters link up to Mother and down to their Granddaughters
+ * - Granddaughters link up to their parent Daughter and horizontally to Sibling Granddaughters
+ * - Zero link leakage between unrelated silos to concentrate topical PageRank
+ */
+export interface GranddaughterNode {
+    id: string;
+    slug: string;
+    title: string;
+    targetKeyphrase: string;
+    monthlySearchVolume: number;
+    intent: "informational" | "commercial" | "transactional";
+    recommendedAnchors: string[];
+}
+export interface DaughterNode {
+    id: string;
+    slug: string;
+    title: string;
+    targetKeyphrase: string;
+    monthlySearchVolume: number;
+    intent: "informational" | "commercial" | "transactional";
+    recommendedAnchors: string[];
+    granddaughters: GranddaughterNode[];
+}
+export interface MotherNode {
+    id: string;
+    slug: string;
+    title: string;
+    targetKeyphrase: string;
+    monthlySearchVolume: number;
+    intent: "commercial" | "informational";
+}
+export interface SupercoconInput {
+    coconName: string;
+    mother: MotherNode;
+    daughters: Array<{
+        node: Omit<DaughterNode, "granddaughters">;
+        granddaughters: GranddaughterNode[];
+    }>;
+}
+export interface InternalLinkRule {
+    fromSlug: string;
+    toSlug: string;
+    linkType: "mother_to_daughter" | "daughter_to_mother" | "daughter_to_granddaughter" | "granddaughter_to_daughter" | "sibling_horizontal";
+    anchorText: string;
+}
+export interface SupercoconTree {
+    coconName: string;
+    mother: MotherNode;
+    daughters: DaughterNode[];
+    totalNodes: number;
+    totalMonthlySearchVolume: number;
+    linkingRules: InternalLinkRule[];
+    mermaidDiagram: string;
+    siloHermeticIntegrityScore: number;
+    summary: string;
+}
+export declare class SupercoconHierarchyArchitect {
+    /**
+     * Constructs and validates a 3-level Supercocon semantic tree.
+     */
+    static buildSupercocon(input: SupercoconInput): SupercoconTree;
+    private static sanitizeMermaid;
+}

package/dist/survey-builder.d.ts

@@ -0,0 +1,59 @@
+export interface SurveyQuestion {
+    id: string;
+    type: "text" | "scale" | "choice" | "nps";
+    label: string;
+    required: boolean;
+    options?: string[];
+    min?: number;
+    max?: number;
+    step?: number;
+}
+export interface SurveyConfig {
+    id: string;
+    title: string;
+    description?: string;
+    trigger: "on_page_view" | "on_event" | "on_exit_intent" | "manual";
+    triggerConfig?: Record<string, string>;
+    questions: SurveyQuestion[];
+    targeting?: {
+        paths?: string[];
+        userSegments?: string[];
+        frequency?: "once" | "per_session" | "per_visit";
+    };
+    styling?: {
+        theme?: "light" | "dark" | "system";
+        position?: "bottom-right" | "bottom-left" | "center" | "bottom-bar";
+        accentColor?: string;
+    };
+}
+export interface SurveyResponse {
+    surveyId: string;
+    userId: string;
+    sessionId: string;
+    answers: Record<string, string | number | string[]>;
+    submittedAt: string;
+    url: string;
+    userAgent: string;
+}
+/** Survey Builder — enquêtes/micro-sondages in-app déclenchées par événements. */
+export declare class SurveyBuilder {
+    private surveys;
+    private responses;
+    create(survey: SurveyConfig): SurveyConfig;
+    get(id: string): SurveyConfig | undefined;
+    delete(id: string): boolean;
+    list(): SurveyConfig[];
+    /** Check if a survey should be shown for the current context. */
+    shouldShow(surveyId: string, context: {
+        path: string;
+        userId?: string;
+        segments?: string[];
+        event?: string;
+    }): boolean;
+    /** Submit a survey response. */
+    submit(response: Omit<SurveyResponse, "submittedAt">): SurveyResponse;
+    /** Get responses for a survey. */
+    getResponses(surveyId: string): SurveyResponse[];
+    /** Export responses as CSV. */
+    exportCsv(surveyId: string): string;
+}