@paro.io/expert-shared-components 1.14.55 → 1.14.57

package/lib/tax-axis/components/clientReport/Methodology.js

@@ -10,13 +10,13 @@ const SectionOpener_1 = require("./SectionOpener");
 function Methodology({ profile, eligible, palette }) {
     return (react_1.default.createElement(react_1.default.Fragment, null,
         react_1.default.createElement(SectionOpener_1.SectionOpener, { number: "04", eyebrow: "METHODOLOGY", headline: "How TaxAxis arrives at these numbers.", bullets: [
-                "25 federal strategies evaluated against your profile via deterministic, rule-based computation at temperature zero \u2014 every recommendation traces to a specific IRC section, revenue ruling, or OBBBA provision.",
+                "25 federal strategies evaluated against your profile through a two-stage AI and deterministic pipeline \u2014 every recommendation traces to a specific IRC section, revenue ruling, or OBBBA provision.",
                 "Confidence bands reflect data quality: \u00B130% on single-year data, narrowing to \u00B115% with multi-year history.",
                 "Aggregate savings on the cover chart are adjusted by an interaction-discount factor reflecting strategy stacking, marginal-rate exhaustion, and \u00A76694 reasonableness.",
             ], palette: palette }),
         react_1.default.createElement("div", { style: { marginBottom: 28 } },
             react_1.default.createElement("div", { style: { fontSize: 10, fontWeight: 700, textTransform: "uppercase", letterSpacing: "0.12em", color: palette.gray400, fontFamily: palette.mono, marginBottom: 8 } }, "EVAL PIPELINE"),
-            react_1.default.createElement("div", { style: { fontSize: 13, color: palette.gray700, lineHeight: 1.8, fontFamily: palette.body } }, "TaxAxis evaluates 25 federal tax strategies against each client profile. The computation is entirely deterministic and rule-based, operating at temperature zero \u2014 no generative model is involved at any stage. Each strategy passes through a three-phase pipeline: an eligibility filter removes strategies that do not apply to the entity type, industry, or fact pattern, then the computation engine calculates savings ranges against IRC-cited rules using the client's actual financial data. Every recommendation is reviewed by a qualified tax professional before the report is issued.")),
+            react_1.default.createElement("div", { style: { fontSize: 13, color: palette.gray700, lineHeight: 1.8, fontFamily: palette.body } }, "TaxAxis evaluates 25 federal tax strategies against each client profile through a two-stage pipeline. An AI model (Claude Sonnet 4.5 via AWS Bedrock) reads your financial documents, identifies applicable strategies, and drafts narrative content. A deterministic post-processing engine then recomputes savings ranges against IRC-cited rules, corrects confidence bands based on data quality, and validates every output through an 8-gate compliance check \u2014 covering schema integrity, strategy coverage, profile consistency, mathematical accuracy, business rules, \u00A76694 compliance, narrative quality, and entity eligibility. Every recommendation is reviewed by a qualified tax professional before the report is issued.")),
         react_1.default.createElement("div", { style: { marginBottom: 28 } },
             react_1.default.createElement("div", { style: { fontSize: 10, fontWeight: 700, textTransform: "uppercase", letterSpacing: "0.12em", color: palette.gray400, fontFamily: palette.mono, marginBottom: 8 } }, "CONFIDENCE BANDS"),
             react_1.default.createElement("div", { style: { fontSize: 13, color: palette.gray700, lineHeight: 1.8, fontFamily: palette.body, marginBottom: 12 } }, "Savings ranges reflect data quality. Clients who provide multiple years of financial history receive tighter bands of \u00B115%, because multi-year data reveals trends and reduces estimation variance. Single-year data widens the bands to \u00B130%. Within each band, the low estimate uses conservative inputs at the minimum applicable rate, while the high estimate uses full applicable inputs at the client's marginal rate."),

package/lib/tax-axis/components/dashboard/StrategyDetailPanel.js

@@ -25,49 +25,46 @@ function positionStrengthLabel(positionStrength) {
     return { label: positionStrength, color: "#9498B8", dots: 2 };
 }
 /**
- * Split engagement_recommendation into two parts:
- * - savingsSection: sentences/paragraphs that contain dollar figures or formula references
- *   → shown as "HOW SAVINGS BREAK DOWN"
- * - cpaSection: the remaining implementation/CPA-action paragraphs
- *   → shown as "CPA ENGAGEMENT NOTES"
+ * Split engagement_recommendation at the implementation/action boundary.
  *
- * Strategy: split on double-newlines or sentence boundaries. Sentences with "$" or
- * formulas go to savings; implementation/deadline/CPA sentences go to cpa.
+ * The LLM writes engagement_recommendation as a single paragraph covering both
+ * the savings math AND the CPA implementation steps. We split at the first
+ * implementation keyword so the savings math shows under "HOW SAVINGS BREAK DOWN"
+ * and the CPA action steps show under "CPA ENGAGEMENT NOTES".
+ *
+ * Heuristic: split at "Implementation:", "CPA should", "CPA must", or numbered
+ * action lists "(1)". If no split point found, entire text goes to savings section.
  */
 function splitEngagementText(text) {
     if (!text)
         return { savingsSection: "", cpaSection: "" };
-    // Split into paragraphs first, then sentences within paragraphs
-    const rawParas = text.split(/\n{2,}/).map((p) => p.trim()).filter(Boolean);
-    const savingsParas = [];
-    const cpaParas = [];
-    for (const para of rawParas) {
-        const hasDollar = /\$[\d,]+/.test(para);
-        const hasFormula = /SAVINGS\s*=|CREDIT\s*=|DEDUCTION\s*=|ADDITIONAL_CONTRIBUTION/i.test(para);
-        const hasPercent = /\d+\.?\d*%/.test(para);
-        const hasCpaKeyword = /\bCPA\b|actuar|implement|deadline|establish|file|form\s+\d|verify|engage|model|recommend/i.test(para);
-        if ((hasDollar || hasFormula || hasPercent) && !hasCpaKeyword) {
-            savingsParas.push(para);
-        }
-        else if (savingsParas.length === 0) {
-            // First para with dollar amounts seeds savings section even if it has CPA keywords
-            if (hasDollar || hasFormula)
-                savingsParas.push(para);
-            else
-                cpaParas.push(para);
-        }
-        else {
-            cpaParas.push(para);
-        }
+    // Try splitting on double-newline first (well-structured LLM output)
+    const paraBreak = text.indexOf("\n\n");
+    if (paraBreak !== -1) {
+        return {
+            savingsSection: text.slice(0, paraBreak).trim(),
+            cpaSection: text.slice(paraBreak).trim(),
+        };
     }
-    // If everything ended up in one bucket, put first para in savings, rest in cpa
-    if (!savingsParas.length && cpaParas.length) {
-        savingsParas.push(cpaParas.shift());
+    // Single-paragraph: find the first implementation boundary
+    const splitPatterns = [
+        /\s+Implementation:\s+/i,
+        /\s+CPA should\s+/i,
+        /\s+CPA must\s+/i,
+        /\s+To implement:\s+/i,
+        /\s+\(1\)\s+/, // numbered list start
+    ];
+    for (const pattern of splitPatterns) {
+        const match = text.search(pattern);
+        if (match > 80) { // only split if there's meaningful content before it
+            return {
+                savingsSection: text.slice(0, match).trim(),
+                cpaSection: text.slice(match).trim(),
+            };
+        }
     }
-    return {
-        savingsSection: savingsParas.join("\n\n"),
-        cpaSection: cpaParas.join("\n\n"),
-    };
+    // No clean split point — show everything as savings breakdown, nothing as CPA notes
+    return { savingsSection: text, cpaSection: "" };
 }
 function SourceDocRows({ docs, trace }) {
     if (docs && docs.length > 0) {

package/lib/tax-axis/components/dashboard/TaxAxisDashboard.js

@@ -26,7 +26,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TaxAxisDashboard = TaxAxisDashboard;
 const react_1 = __importStar(require("react"));
 const data_1 = require("../../lib/data");
+const strategyNarrative_1 = require("../../lib/data/strategyNarrative");
 const compute_1 = require("../../lib/compute");
+const useEngineOutput_1 = require("../../lib/adapters/useEngineOutput");
 const TaxAxisButton_1 = require("../shared/TaxAxisButton");
 const TaxAxisBadge_1 = require("../shared/TaxAxisBadge");
 const DashboardSummary_1 = require("./DashboardSummary");
@@ -96,18 +98,109 @@ function buildRoadmapBucketLookup(llm) {
     }
     return map;
 }
-function mapLlmToStrategies(llm) {
+// LLM sometimes emits these literal placeholder strings as why_it_applies / next_step
+// content. When detected, we fall back to STRATEGY_NARRATIVE static content.
+const PLACEHOLDER_WHY = "This strategy may apply based on your financial profile.";
+const PLACEHOLDER_NEXT = "Discuss with your CPA to evaluate and implement this strategy.";
+function isMissingOrPlaceholder(value, knownPlaceholder) {
+    if (!value)
+        return true;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return true;
+    if (trimmed === knownPlaceholder)
+        return true;
+    return false;
+}
+// Parse "S10" -> 10. Returns null if strategyId doesn't match the SN pattern.
+function parseStrategyNumber(strategyId) {
+    if (!strategyId)
+        return null;
+    const match = strategyId.match(/^S(\d+)$/);
+    if (!match)
+        return null;
+    return parseInt(match[1], 10);
+}
+// Build a strategy_id -> client_summary entry lookup using strategy_analysis as the join table.
+function buildClientSummaryLookup(llm) {
+    var _a, _b, _c, _d;
+    const lookup = new Map();
+    const engineOutput = (_a = llm.engineOutput) !== null && _a !== void 0 ? _a : llm.rawOutput;
+    if (!engineOutput)
+        return lookup;
+    const strategyAnalysis = (_b = engineOutput.strategy_analysis) !== null && _b !== void 0 ? _b : [];
+    const clientSummaryStrategies = (_d = (_c = engineOutput.client_summary) === null || _c === void 0 ? void 0 : _c.strategies) !== null && _d !== void 0 ? _d : [];
+    // strategy_name -> client_summary entry
+    const byName = new Map();
+    for (const cs of clientSummaryStrategies) {
+        if (cs.strategy_name) {
+            byName.set(cs.strategy_name, cs);
+        }
+    }
+    // strategy_id -> client_summary entry (via strategy_analysis name lookup)
+    for (const sa of strategyAnalysis) {
+        if (sa.strategy_id && sa.strategy_name) {
+            const cs = byName.get(sa.strategy_name);
+            if (cs) {
+                lookup.set(sa.strategy_id, cs);
+            }
+        }
+    }
+    return lookup;
+}
+function mapLlmToStrategies(llm, profile) {
     const nameLookup = buildEngineNameLookup(llm);
     const bucketLookup = buildRoadmapBucketLookup(llm);
+    const clientSummaryLookup = buildClientSummaryLookup(llm);
     return llm.strategies
         .filter((s) => s.applicable)
         .map((s, idx) => {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d, _e, _f, _g;
         const id = (_a = s.strategyId) !== null && _a !== void 0 ? _a : s.strategyType;
-        // Prefer the real strategy_name from engineOutput, fall back to humanized strategyType
         const name = (_b = nameLookup.get(id)) !== null && _b !== void 0 ? _b : humanizeStrategyType(s.strategyType);
         const timelineBucket = (_c = bucketLookup.get(id)) !== null && _c !== void 0 ? _c : (s.priority === "HIGH" ? "now" : "90d");
         const weightedScore = (_d = s.weightedScore) !== null && _d !== void 0 ? _d : (s.priority === "HIGH" ? 85 : s.priority === "MEDIUM" ? 70 : 55);
+        // Lookup the client_summary entry for this strategy (top-3 strategies only)
+        const csEntry = clientSummaryLookup.get(id);
+        const llmWhy = csEntry === null || csEntry === void 0 ? void 0 : csEntry.why_it_applies;
+        const llmNext = csEntry === null || csEntry === void 0 ? void 0 : csEntry.next_step;
+        // Strategy number for STRATEGY_NARRATIVE static lookup (e.g. "S10" -> 10)
+        const strategyNumber = parseStrategyNumber(id);
+        const staticNarrative = strategyNumber !== null ? strategyNarrative_1.STRATEGY_NARRATIVE[strategyNumber] : undefined;
+        // clientBrief: prefer LLM why_it_applies, fall back to static, then neutral default
+        let clientBrief;
+        if (!isMissingOrPlaceholder(llmWhy, PLACEHOLDER_WHY)) {
+            clientBrief = llmWhy;
+        }
+        else if (staticNarrative === null || staticNarrative === void 0 ? void 0 : staticNarrative.whyMatters) {
+            clientBrief = staticNarrative.whyMatters(profile);
+        }
+        else {
+            clientBrief = "Your preparer will review this strategy and include the analysis in your engagement report.";
+        }
+        // action: prefer LLM next_step, fall back to static nextSteps, then implementationSteps[0]
+        let action;
+        if (!isMissingOrPlaceholder(llmNext, PLACEHOLDER_NEXT)) {
+            action = llmNext;
+        }
+        else if (staticNarrative === null || staticNarrative === void 0 ? void 0 : staticNarrative.nextSteps) {
+            action = staticNarrative.nextSteps;
+        }
+        else if ((_e = s.implementationSteps) === null || _e === void 0 ? void 0 : _e[0]) {
+            action = s.implementationSteps[0];
+        }
+        else {
+            action = "Work with your CPA to implement this strategy.";
+        }
+        // Pull calculation_trace fields. Defensive about shape.
+        const ct = ((_f = s.calculationTrace) !== null && _f !== void 0 ? _f : {});
+        const sourceDocuments = Array.isArray(ct.source_documents) ? ct.source_documents : undefined;
+        const specialistNote = typeof ct.specialist_note === "string" && ct.specialist_note.trim() !== ""
+            ? ct.specialist_note
+            : ((_g = staticNarrative === null || staticNarrative === void 0 ? void 0 : staticNarrative.whySpecialist) !== null && _g !== void 0 ? _g : undefined);
+        const positionStrength = typeof ct.position_strength === "string" ? ct.position_strength : undefined;
+        const authority = typeof ct.irs_cite === "string" ? ct.irs_cite : undefined;
+        const formsFromTrace = Array.isArray(ct.forms_required) ? ct.forms_required.join(", ") : undefined;
         return {
             rank: idx + 1,
             code: id,
@@ -120,13 +213,18 @@ function mapLlmToStrategies(llm) {
             hi: s.estimatedSavings.max,
             timeline: timelineBucket === "now" ? "Act now" : timelineBucket === "30d" ? "Within 30 days" : "Within 90 days",
             timelineBucket,
-            clientBrief: s.summary,
-            action: (_e = s.implementationSteps[0]) !== null && _e !== void 0 ? _e : s.summary,
-            forms: s.requiredForms.join(", "),
+            clientBrief,
+            action,
+            forms: formsFromTrace !== null && formsFromTrace !== void 0 ? formsFromTrace : s.requiredForms.join(", "),
             abstract: s.summary,
             sources: [],
             trace: [],
             cost: undefined,
+            sourceDocuments,
+            specialistNote,
+            positionStrength,
+            authority,
+            quickWin: s.quickWin,
         };
     });
 }
@@ -163,8 +261,29 @@ function TaxAxisDashboard({ profile, llmResult, parsedDocuments, onDownloadClien
     // Extracted documents: live from session if provided, otherwise empty (no mock fallback)
     const extractionDocs = parsedDocuments !== null && parsedDocuments !== void 0 ? parsedDocuments : [];
     // ─── Derived data ──────────────────────────────────────────────
-    const llmStrategies = (0, react_1.useMemo)(() => (hasLlm ? mapLlmToStrategies(llmResult) : []), [hasLlm, llmResult]);
-    const llmComputed = (0, react_1.useMemo)(() => (hasLlm ? buildLlmComputed(llmStrategies) : new Map()), [hasLlm, llmStrategies]);
+    // Prefer useEngineOutput (full rich data: sourceDocuments, positionStrength,
+    // clientBrief from why_it_applies, etc.) over the thin mapLlmToStrategies fallback.
+    // engineOutput is at llmResult.engineOutput or llmResult.rawOutput (both present).
+    const engineOutputForAdapter = (0, react_1.useMemo)(() => { var _a, _b; return (_b = (_a = llmResult === null || llmResult === void 0 ? void 0 : llmResult.engineOutput) !== null && _a !== void 0 ? _a : llmResult === null || llmResult === void 0 ? void 0 : llmResult.rawOutput) !== null && _b !== void 0 ? _b : null; }, [llmResult]);
+    const adapted = (0, useEngineOutput_1.useEngineOutput)(engineOutputForAdapter);
+    const llmStrategies = (0, react_1.useMemo)(() => {
+        var _a;
+        if (!hasLlm)
+            return [];
+        // Use adapted strategies when available — they carry the full engine data.
+        if ((_a = adapted === null || adapted === void 0 ? void 0 : adapted.strategies) === null || _a === void 0 ? void 0 : _a.length)
+            return adapted.strategies;
+        // Fallback to thin mapping for old payload shapes without engineOutput.
+        return mapLlmToStrategies(llmResult, profile);
+    }, [hasLlm, adapted, llmResult, profile]);
+    const llmComputed = (0, react_1.useMemo)(() => {
+        var _a;
+        if (!hasLlm)
+            return new Map();
+        if ((_a = adapted === null || adapted === void 0 ? void 0 : adapted.computedMap) === null || _a === void 0 ? void 0 : _a.size)
+            return adapted.computedMap;
+        return buildLlmComputed(llmStrategies);
+    }, [hasLlm, adapted, llmStrategies]);
     const computed = (0, react_1.useMemo)(() => (hasLlm ? llmComputed : (0, compute_1.computeAllStrategies)(profile)), [hasLlm, llmComputed, profile]);
     const dashEligible = (0, react_1.useMemo)(() => (hasLlm ? llmStrategies : (0, compute_1.filterEligibleStrategies)(profile)), [hasLlm, llmStrategies, profile]);
     const maxSavings = Math.max(...dashEligible.map((s) => { var _a, _b; return (_b = (_a = computed.get(s.rank)) === null || _a === void 0 ? void 0 : _a.hi) !== null && _b !== void 0 ? _b : s.hi; }), 1);

package/lib/tax-axis/components/processing/TaxAxisProcessing.js

@@ -26,10 +26,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TaxAxisProcessing = TaxAxisProcessing;
 const react_1 = __importStar(require("react"));
 const ProcessingStages_1 = require("./ProcessingStages");
-const CRAWL_CEILING = 80; // hold here until reportReady
-const CRAWL_TICK_MS = 180; // interval between crawl ticks
-const CRAWL_STEP = 0.35; // % added each tick (reaches 80% in ~41s)
-const FINISH_MS = 600; // ms to animate from current% → 100% once ready
+const CRAWL_CEILING = 99; // pause here until reportReady
+const CRAWL_TICK_MS = 300; // interval between crawl ticks
+const CRAWL_STEP = 0.27; // % added each tick → 0.27 / 0.3s = 0.9%/s
+const FINISH_MS = 400; // ms to animate from 99% → 100% once ready
 const STAGE_ADVANCE_MS = 3200; // how often the displayed stage advances
 function buildStages(profile) {
     var _a;
@@ -69,6 +69,30 @@ function TaxAxisProcessing({ onComplete, profile, reportReady = false, userConte
     // Track current progress in a ref so the finish animation can read it synchronously
     // without relying on the async functional-updater pattern.
     const progressRef = (0, react_1.useRef)(0);
+    // ── Stall detection: show patience message after 35s of no progress change ──
+    const [showPatience, setShowPatience] = (0, react_1.useState)(false);
+    const lastProgressRef = (0, react_1.useRef)(0);
+    const stallTimerRef = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        if (finishingRef.current) {
+            setShowPatience(false);
+            return;
+        }
+        if (progress !== lastProgressRef.current) {
+            lastProgressRef.current = progress;
+            setShowPatience(false);
+            if (stallTimerRef.current)
+                clearTimeout(stallTimerRef.current);
+            stallTimerRef.current = setTimeout(() => {
+                if (!finishingRef.current)
+                    setShowPatience(true);
+            }, 8000);
+        }
+        return () => {
+            if (stallTimerRef.current)
+                clearTimeout(stallTimerRef.current);
+        };
+    }, [progress]);
     const setProgressSync = (v) => {
         progressRef.current = v;
         setProgress(v);
@@ -147,5 +171,6 @@ function TaxAxisProcessing({ onComplete, profile, reportReady = false, userConte
                     transition: isFinishing ? "none" : "width 0.18s linear",
                 } })),
         react_1.default.createElement(ProcessingStages_1.ProcessingStages, { stages: stages, progress: stageIdx + 1 }),
-        pct >= CRAWL_CEILING && !isFinishing && (react_1.default.createElement("p", { className: "text-[11px] text-tax-axis-text-4 font-tax-axis-mono mt-4 animate-pulse" }, "Finalizing analysis\u2026"))));
+        pct >= CRAWL_CEILING && !isFinishing && (react_1.default.createElement("p", { className: "text-[11px] text-tax-axis-text-4 font-tax-axis-mono mt-4 animate-pulse" }, "Finalizing analysis\u2026")),
+        showPatience && !isFinishing && (react_1.default.createElement("p", { className: "text-[13px] text-tax-axis-text-3 font-tax-axis-body mt-4 text-center" }, "Still running \u2014 document analysis typically takes 2\u20133 minutes. Do not navigate away."))));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paro.io/expert-shared-components",
-  "version": "1.14.55",
+  "version": "1.14.57",
   "description": "",
   "main": "lib/index.js",
   "scripts": {