perfgraph 0.1.0

package/dist/causal/rules/lcp.js

@@ -0,0 +1,250 @@
+/**
+ * LCP-related causal rules.
+ *
+ * Chains covered:
+ *   1. High TTFB → delayed HTML parse → delayed CSS discovery → blocked render → ↑LCP
+ *   2. Render-blocking resources → blocked render → ↑LCP
+ *   3. Slow LCP resource load → ↑LCP
+ *
+ * @packageDocumentation
+ */
+// ---------------------------------------------------------------------------
+// Thresholds (Google Web Vitals + common perf engineering)
+// ---------------------------------------------------------------------------
+const TTFB_WARN = 800; // ms — needs improvement
+const TTFB_CRIT = 2_500; // ms — poor
+const LCP_WARN = 2_500; // ms
+const LCP_CRIT = 4_000; // ms
+const RESOURCE_DELAY_WARN = 500; // ms
+const RENDER_DELAY_WARN = 500; // ms
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function confidenceFromDelta(value, warnThreshold, critThreshold) {
+    if (value >= critThreshold)
+        return 'strong';
+    if (value >= warnThreshold)
+        return 'medium';
+    return 'weak';
+}
+function severityFromDelta(value, warnThreshold, critThreshold) {
+    if (value >= critThreshold)
+        return 'critical';
+    if (value >= warnThreshold)
+        return 'warning';
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Rule 1: TTFB → LCP chain
+// ---------------------------------------------------------------------------
+export const ttfbLcpChain = {
+    id: 'lcp-ttfb-chain',
+    label: 'TTFB → delayed HTML → blocked render → LCP',
+    applies(features) {
+        return features.lcpBreakdown?.ttfb != null && features.lcpBreakdown.ttfb > TTFB_WARN;
+    },
+    build(features) {
+        const ttfb = features.lcpBreakdown.ttfb;
+        const conf = confidenceFromDelta(ttfb, TTFB_WARN, TTFB_CRIT);
+        const sev = severityFromDelta(ttfb, TTFB_WARN, TTFB_CRIT);
+        const ttfbEvidence = {
+            metric: { name: 'TTFB', value: ttfb, unit: 'ms' },
+        };
+        const nodes = [
+            {
+                id: 'high-ttfb',
+                label: 'TTFB exceeds normal threshold',
+                type: 'metric',
+                severity: sev,
+                value: ttfb,
+                unit: 'ms',
+                threshold: TTFB_WARN,
+                evidence: ttfbEvidence,
+            },
+            {
+                id: 'delayed-html-parse',
+                label: 'Delayed HTML parsing',
+                type: 'bottleneck',
+                severity: sev,
+            },
+            {
+                id: 'delayed-css-discovery',
+                label: 'Delayed CSS discovery',
+                type: 'bottleneck',
+                severity: sev,
+            },
+            {
+                id: 'blocked-render',
+                label: 'Render blocked',
+                type: 'bottleneck',
+                severity: 'warning',
+            },
+            {
+                id: 'increased-lcp',
+                label: 'Increased LCP',
+                type: 'impact',
+                severity: sev,
+                value: features.lcpBreakdown?.totalLCP,
+                unit: 'ms',
+                threshold: LCP_WARN,
+            },
+        ];
+        const edges = [
+            {
+                source: 'high-ttfb',
+                target: 'delayed-html-parse',
+                confidence: conf,
+                label: 'High TTFB delays HTML parsing start',
+                ruleId: 'lcp-ttfb-chain',
+            },
+            {
+                source: 'delayed-html-parse',
+                target: 'delayed-css-discovery',
+                confidence: conf,
+                label: 'HTML parsing needed for CSS resource discovery',
+                ruleId: 'lcp-ttfb-chain',
+            },
+            {
+                source: 'delayed-css-discovery',
+                target: 'blocked-render',
+                confidence: conf,
+                label: 'CSS is critical for rendering (render-blocking by default)',
+                ruleId: 'lcp-ttfb-chain',
+            },
+            {
+                source: 'blocked-render',
+                target: 'increased-lcp',
+                confidence: conf,
+                label: 'Blocked render increases LCP',
+                ruleId: 'lcp-ttfb-chain',
+            },
+        ];
+        return { nodes, edges };
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 2: Render-blocking resources → LCP
+// ---------------------------------------------------------------------------
+export const renderBlockingLcpChain = {
+    id: 'lcp-render-blocking-chain',
+    label: 'Render-blocking resources → blocked render → LCP',
+    applies(features) {
+        const rb = features.renderBlocking;
+        return rb != null && rb.blockingRequestCount >= 2;
+    },
+    build(features) {
+        const rb = features.renderBlocking;
+        // Downgrade low-impact render-blocking (≤ 3 requests) to warning:
+        // "Document + 2 small stylesheets" should not be critical
+        const isHeavy = rb.renderBlockingScore > 0.5 && rb.blockingRequestCount > 3;
+        const rbEvidence = {
+            urls: rb.resources?.map((r) => r.url),
+        };
+        const lcpRbEvidence = {
+            metric: features.lcpBreakdown?.totalLCP != null
+                ? { name: 'LCP', value: features.lcpBreakdown.totalLCP, unit: 'ms' }
+                : undefined,
+        };
+        const nodes = [
+            {
+                id: 'rb-resources',
+                label: `${rb.blockingRequestCount} render-blocking resources`,
+                type: 'metric',
+                severity: isHeavy ? 'critical' : 'warning',
+                value: rb.blockingRequestCount,
+                unit: 'requests',
+                threshold: 2,
+                evidence: rbEvidence,
+            },
+            {
+                id: 'blocked-render-rb',
+                label: 'Render blocked (render-blocking)',
+                type: 'bottleneck',
+                severity: isHeavy ? 'critical' : 'warning',
+            },
+            {
+                id: 'increased-lcp-rb',
+                label: 'Increased LCP',
+                type: 'impact',
+                value: features.lcpBreakdown?.totalLCP,
+                unit: 'ms',
+                threshold: LCP_WARN,
+                evidence: lcpRbEvidence.metric ? lcpRbEvidence : undefined,
+            },
+        ];
+        const edges = [
+            {
+                source: 'rb-resources',
+                target: 'blocked-render-rb',
+                confidence: isHeavy ? 'strong' : 'medium',
+                label: `Render-blocking resources block rendering`,
+                ruleId: 'lcp-render-blocking-chain',
+            },
+            {
+                source: 'blocked-render-rb',
+                target: 'increased-lcp-rb',
+                confidence: isHeavy ? 'strong' : 'medium',
+                label: 'Render blocking directly increases LCP',
+                ruleId: 'lcp-render-blocking-chain',
+            },
+        ];
+        return { nodes, edges };
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 3: Slow LCP resource load delay
+// ---------------------------------------------------------------------------
+export const lcpResourceDelayChain = {
+    id: 'lcp-resource-delay-chain',
+    label: 'LCP resource delay → increased LCP',
+    applies(features) {
+        const lcp = features.lcpBreakdown;
+        return lcp != null && (lcp.resourceLoadDelay > RESOURCE_DELAY_WARN || lcp.elementRenderDelay > RENDER_DELAY_WARN);
+    },
+    build(features) {
+        const lcp = features.lcpBreakdown;
+        const isDelayed = lcp.resourceLoadDelay > RENDER_DELAY_WARN || lcp.resourceLoadTime > 1000;
+        const delayEvidence = {
+            metric: { name: 'LCP resource delay', value: lcp.resourceLoadDelay, unit: 'ms' },
+        };
+        const nodes = [
+            {
+                id: 'lcp-resource-delay',
+                label: `LCP resource delay: ${Math.round(lcp.resourceLoadDelay)}ms`,
+                type: 'bottleneck',
+                severity: isDelayed ? 'warning' : 'info',
+                value: lcp.resourceLoadDelay,
+                unit: 'ms',
+                threshold: RESOURCE_DELAY_WARN,
+                evidence: delayEvidence,
+            },
+            {
+                id: 'increased-lcp-resource',
+                label: 'Increased LCP',
+                type: 'impact',
+                value: lcp.totalLCP,
+                unit: 'ms',
+                threshold: LCP_WARN,
+            },
+        ];
+        const edges = [
+            {
+                source: 'lcp-resource-delay',
+                target: 'increased-lcp-resource',
+                confidence: isDelayed ? 'medium' : 'weak',
+                label: 'Slow LCP resource load increases total LCP',
+                ruleId: 'lcp-resource-delay-chain',
+            },
+        ];
+        return { nodes, edges };
+    },
+};
+// ---------------------------------------------------------------------------
+// Aggregated LCP rule list
+// ---------------------------------------------------------------------------
+export const lcpRules = [
+    ttfbLcpChain,
+    renderBlockingLcpChain,
+    lcpResourceDelayChain,
+];
+//# sourceMappingURL=lcp.js.map

package/dist/causal/rules/lcp.js.map

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

package/dist/causal/rules/network.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Network-related causal rules.
+ *
+ * Chains covered:
+ *   1. Deep critical chain → delayed page load
+ *   2. Excessive request count → bandwidth contention → slower loads
+ *
+ * @packageDocumentation
+ */
+import type { FeatureSet } from '../../extract/types.js';
+import type { CausalNode, CausalEdge } from '../types.js';
+export declare const criticalPathChain: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+};
+export declare const excessiveRequestsChain: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+};
+export declare const networkRules: {
+    id: string;
+    label: string;
+    applies(features: FeatureSet): boolean;
+    build(features: FeatureSet): {
+        nodes: CausalNode[];
+        edges: CausalEdge[];
+    };
+}[];
+//# sourceMappingURL=network.d.ts.map

package/dist/causal/rules/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../src/causal/rules/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAc,UAAU,EAAE,UAAU,EAAY,MAAM,aAAa,CAAC;AAehF,eAAO,MAAM,iBAAiB;;;sBAIV,UAAU,GAAG,OAAO;oBAKtB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;CAmD1E,CAAC;AAMF,eAAO,MAAM,sBAAsB;;;sBAIf,UAAU,GAAG,OAAO;oBAKtB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;CAmD1E,CAAC;AAMF,eAAO,MAAM,YAAY;;;sBAhIL,UAAU,GAAG,OAAO;oBAKtB,UAAU,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE;GA8H1E,CAAC"}

package/dist/causal/rules/network.js

@@ -0,0 +1,140 @@
+/**
+ * Network-related causal rules.
+ *
+ * Chains covered:
+ *   1. Deep critical chain → delayed page load
+ *   2. Excessive request count → bandwidth contention → slower loads
+ *
+ * @packageDocumentation
+ */
+// ---------------------------------------------------------------------------
+// Thresholds
+// ---------------------------------------------------------------------------
+const CHAIN_DEPTH_WARN = 5;
+const CHAIN_DEPTH_CRIT = 10;
+const REQUEST_COUNT_WARN = 50;
+const REQUEST_COUNT_CRIT = 100;
+// ---------------------------------------------------------------------------
+// Rule 1: Deep critical chain → slow page load
+// ---------------------------------------------------------------------------
+export const criticalPathChain = {
+    id: 'net-critical-path-chain',
+    label: 'Deep critical chain → slow page load',
+    applies(features) {
+        const cp = features.criticalPath;
+        return cp != null && cp.deepestChainDepth >= CHAIN_DEPTH_WARN;
+    },
+    build(features) {
+        const cp = features.criticalPath;
+        const isDeep = cp.deepestChainDepth >= CHAIN_DEPTH_CRIT;
+        const conf = isDeep ? 'strong' : 'medium';
+        const chainEvidence = {
+            urls: cp.urlsOnLongestPath,
+        };
+        const nodes = [
+            {
+                id: 'deep-critical-chain',
+                label: `Deep critical chain (${cp.deepestChainDepth} levels)`,
+                type: 'metric',
+                severity: isDeep ? 'critical' : 'warning',
+                value: cp.deepestChainDepth,
+                threshold: CHAIN_DEPTH_WARN,
+                evidence: chainEvidence,
+            },
+            {
+                id: 'waterfall-delay',
+                label: 'Cascading load delay',
+                type: 'bottleneck',
+                severity: isDeep ? 'critical' : 'warning',
+            },
+            {
+                id: 'slow-page-load',
+                label: 'Slow page load',
+                type: 'impact',
+            },
+        ];
+        const edges = [
+            {
+                source: 'deep-critical-chain',
+                target: 'waterfall-delay',
+                confidence: conf,
+                label: 'Deep sequential load chain delays critical path',
+                ruleId: 'net-critical-path-chain',
+            },
+            {
+                source: 'waterfall-delay',
+                target: 'slow-page-load',
+                confidence: conf,
+                label: 'Cascading delay increases total load time',
+                ruleId: 'net-critical-path-chain',
+            },
+        ];
+        return { nodes, edges };
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 2: Excessive requests → bandwidth contention
+// ---------------------------------------------------------------------------
+export const excessiveRequestsChain = {
+    id: 'net-excessive-requests-chain',
+    label: 'Too many requests → bandwidth contention',
+    applies(features) {
+        const cp = features.criticalPath;
+        return cp != null && cp.requestCount >= REQUEST_COUNT_WARN;
+    },
+    build(features) {
+        const cp = features.criticalPath;
+        const isExcessive = cp.requestCount >= REQUEST_COUNT_CRIT;
+        const conf = isExcessive ? 'strong' : 'medium';
+        const reqEvidence = {
+            metric: { name: 'Requests', value: cp.requestCount, unit: 'count' },
+        };
+        const nodes = [
+            {
+                id: 'excessive-requests',
+                label: `${cp.requestCount} requests on critical path`,
+                type: 'metric',
+                severity: isExcessive ? 'critical' : 'warning',
+                value: cp.requestCount,
+                threshold: REQUEST_COUNT_WARN,
+                evidence: reqEvidence,
+            },
+            {
+                id: 'bandwidth-contention',
+                label: 'Bandwidth contention',
+                type: 'bottleneck',
+                severity: isExcessive ? 'warning' : 'info',
+            },
+            {
+                id: 'slow-load-many-requests',
+                label: 'Slow page load',
+                type: 'impact',
+            },
+        ];
+        const edges = [
+            {
+                source: 'excessive-requests',
+                target: 'bandwidth-contention',
+                confidence: conf,
+                label: 'Multiple requests compete for limited bandwidth',
+                ruleId: 'net-excessive-requests-chain',
+            },
+            {
+                source: 'bandwidth-contention',
+                target: 'slow-load-many-requests',
+                confidence: 'medium',
+                label: 'Contention slows down loading',
+                ruleId: 'net-excessive-requests-chain',
+            },
+        ];
+        return { nodes, edges };
+    },
+};
+// ---------------------------------------------------------------------------
+// Aggregated
+// ---------------------------------------------------------------------------
+export const networkRules = [
+    criticalPathChain,
+    excessiveRequestsChain,
+];
+//# sourceMappingURL=network.js.map

package/dist/causal/rules/network.js.map

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

package/dist/causal/types.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Causal Graph types — Zod schemas and TypeScript types.
+ *
+ * These define the output of Phase 4: a typed DAG where nodes represent
+ * performance signals (metrics, bottlenecks, impacts) and edges represent
+ * causal relationships with confidence scores.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** Confidence level for a causal edge */
+export declare const ConfidenceSchema: z.ZodEnum<{
+    medium: "medium";
+    strong: "strong";
+    weak: "weak";
+}>;
+export type Confidence = z.infer<typeof ConfidenceSchema>;
+/** Node severity (user-facing classification) */
+export declare const SeveritySchema: z.ZodEnum<{
+    critical: "critical";
+    info: "info";
+    warning: "warning";
+}>;
+export type Severity = z.infer<typeof SeveritySchema>;
+/** Node role in the causal chain */
+export declare const NodeTypeSchema: z.ZodEnum<{
+    impact: "impact";
+    metric: "metric";
+    bottleneck: "bottleneck";
+}>;
+export type NodeType = z.infer<typeof NodeTypeSchema>;
+/** Evidence payload attached to a causal node */
+export declare const EvidenceSchema: z.ZodObject<{
+    urls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    selector: z.ZodOptional<z.ZodString>;
+    lighthouseAuditId: z.ZodOptional<z.ZodString>;
+    metric: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodNumber;
+        unit: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Evidence = z.infer<typeof EvidenceSchema>;
+export declare const CausalNodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        impact: "impact";
+        metric: "metric";
+        bottleneck: "bottleneck";
+    }>;
+    severity: z.ZodOptional<z.ZodEnum<{
+        critical: "critical";
+        info: "info";
+        warning: "warning";
+    }>>;
+    value: z.ZodOptional<z.ZodNumber>;
+    unit: z.ZodOptional<z.ZodString>;
+    threshold: z.ZodOptional<z.ZodNumber>;
+    evidence: z.ZodOptional<z.ZodObject<{
+        urls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        selector: z.ZodOptional<z.ZodString>;
+        lighthouseAuditId: z.ZodOptional<z.ZodString>;
+        metric: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodNumber;
+            unit: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CausalNode = z.infer<typeof CausalNodeSchema>;
+export declare const CausalEdgeSchema: z.ZodObject<{
+    source: z.ZodString;
+    target: z.ZodString;
+    confidence: z.ZodEnum<{
+        medium: "medium";
+        strong: "strong";
+        weak: "weak";
+    }>;
+    label: z.ZodString;
+    ruleId: z.ZodString;
+}, z.core.$strip>;
+export type CausalEdge = z.infer<typeof CausalEdgeSchema>;
+export declare const CausalGraphMetadataSchema: z.ZodObject<{
+    featureCount: z.ZodNumber;
+    ruleCount: z.ZodNumber;
+    totalNodes: z.ZodNumber;
+    totalEdges: z.ZodNumber;
+    hasCycle: z.ZodBoolean;
+    targetUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CausalGraphMetadata = z.infer<typeof CausalGraphMetadataSchema>;
+export declare const CausalGraphSchema: z.ZodObject<{
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            impact: "impact";
+            metric: "metric";
+            bottleneck: "bottleneck";
+        }>;
+        severity: z.ZodOptional<z.ZodEnum<{
+            critical: "critical";
+            info: "info";
+            warning: "warning";
+        }>>;
+        value: z.ZodOptional<z.ZodNumber>;
+        unit: z.ZodOptional<z.ZodString>;
+        threshold: z.ZodOptional<z.ZodNumber>;
+        evidence: z.ZodOptional<z.ZodObject<{
+            urls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            selector: z.ZodOptional<z.ZodString>;
+            lighthouseAuditId: z.ZodOptional<z.ZodString>;
+            metric: z.ZodOptional<z.ZodObject<{
+                name: z.ZodString;
+                value: z.ZodNumber;
+                unit: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        target: z.ZodString;
+        confidence: z.ZodEnum<{
+            medium: "medium";
+            strong: "strong";
+            weak: "weak";
+        }>;
+        label: z.ZodString;
+        ruleId: z.ZodString;
+    }, z.core.$strip>>;
+    metadata: z.ZodObject<{
+        featureCount: z.ZodNumber;
+        ruleCount: z.ZodNumber;
+        totalNodes: z.ZodNumber;
+        totalEdges: z.ZodNumber;
+        hasCycle: z.ZodBoolean;
+        targetUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CausalGraph = z.infer<typeof CausalGraphSchema>;
+//# sourceMappingURL=types.d.ts.map

package/dist/causal/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/causal/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,yCAAyC;AACzC,eAAO,MAAM,gBAAgB;;;;EAAuC,CAAC;AACrE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;;EAA0C,CAAC;AACtE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,oCAAoC;AACpC,eAAO,MAAM,cAAc;;;;EAA6C,CAAC;AACzE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAMtD,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;;;;;;;iBAezB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAMtD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;iBAa3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAM1D,eAAO,MAAM,gBAAgB;;;;;;;;;;iBAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAM1D,eAAO,MAAM,yBAAyB;;;;;;;iBAUpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAI5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}