@gscdump/sdk 0.24.0 → 0.25.0

package/dist/index.d.mts

@@ -781,17 +781,39 @@ interface TriageEvidence {
   label: string;
   value: string;
 }
+/**
+ * Distance-to-next-stage for one axis, so the UI never re-derives thresholds.
+ *
+ * `direction`:
+ *  - `advance` — up-path rung (waiting → emerging → growing). `pct` = value/target.
+ *  - `escape`  — off-ramp recovery (declining/faded/decayed) or a held health gate
+ *    (crawl_faults/quality_rejection). `pct` = inverse distance: closer to passing ⇒ higher.
+ *  - `sustain` — already good (growing/healthy). `nextStage` null, `pct` 1, framed as momentum.
+ *
+ * `gapLabel` is always a concrete count (pages/clicks/points), never a bare %.
+ */
+interface StageProgression {
+  nextStage: ReachStage | HealthStage | null;
+  metric: string;
+  value: number;
+  target: number;
+  pct: number;
+  gapLabel: string;
+  direction: 'advance' | 'escape' | 'sustain';
+}
 interface ReachVerdict {
   stage: ReachStage;
   summary: string;
   primaryAction: string;
   evidence: TriageEvidence[];
+  progression: StageProgression;
 }
 interface HealthVerdict {
   stage: HealthStage;
   summary: string;
   primaryAction: string;
   evidence: TriageEvidence[];
+  progression: StageProgression;
 }
 interface SiteTriage {
   reach: ReachVerdict;

package/dist/index.mjs

@@ -1911,6 +1911,57 @@ function issueCount(issues, ...types) {
 function fmt(n) {
 	return new Intl.NumberFormat("en").format(Math.max(0, Math.round(n)));
 }
+function clamp01(n) {
+	if (!Number.isFinite(n)) return 0;
+	return Math.min(1, Math.max(0, n));
+}
+function pctStr(n) {
+	return `${n >= 0 ? "+" : ""}${Math.round(n)}%`;
+}
+function advance(nextStage, metric, value, target, gapLabel) {
+	return {
+		nextStage,
+		metric,
+		value,
+		target,
+		pct: clamp01(value / target),
+		gapLabel,
+		direction: "advance"
+	};
+}
+function escapeToward(nextStage, metric, value, target, gapLabel) {
+	return {
+		nextStage,
+		metric,
+		value,
+		target,
+		pct: clamp01(value / target),
+		gapLabel,
+		direction: "escape"
+	};
+}
+function escapeReduce(nextStage, metric, value, target, gapLabel) {
+	return {
+		nextStage,
+		metric,
+		value,
+		target,
+		pct: target <= 0 ? value <= 0 ? 1 : 0 : clamp01(2 - value / target),
+		gapLabel,
+		direction: "escape"
+	};
+}
+function sustain(metric, value, gapLabel) {
+	return {
+		nextStage: null,
+		metric,
+		value,
+		target: value,
+		pct: 1,
+		gapLabel,
+		direction: "sustain"
+	};
+}
 const HEALTH_COPY = {
 	healthy: {
 		summary: "Google can crawl and index the pages that should be indexed.",
@@ -1942,30 +1993,41 @@ function classifyHealthStage(input) {
 	const intentionalDead = isIntentionalRetirementSite(input, notFound, serverError) ? notFound : 0;
 	const indexableUrls = Math.max(1, totalUrls - noindex - intentionalDead);
 	const hardBlocks = serverError + (input.crawlAuditBlockerCount ?? 0);
-	if (hardBlocks > Math.max(HARD_BLOCK_FLOOR, indexableUrls * HARD_BLOCK_SHARE)) return {
-		stage: "crawl_faults",
-		...HEALTH_COPY.crawl_faults,
-		evidence: [{
-			label: "Access faults (5xx / broken)",
-			value: fmt(hardBlocks)
-		}]
-	};
+	const faultTarget = Math.max(HARD_BLOCK_FLOOR, indexableUrls * HARD_BLOCK_SHARE);
+	if (hardBlocks > faultTarget) {
+		const toFix = Math.ceil(hardBlocks - faultTarget);
+		return {
+			stage: "crawl_faults",
+			...HEALTH_COPY.crawl_faults,
+			evidence: [{
+				label: "Access faults (5xx / broken)",
+				value: fmt(hardBlocks)
+			}],
+			progression: escapeReduce("healthy", "access faults", hardBlocks, faultTarget, `${fmt(hardBlocks)} faults — fix ~${fmt(toFix)} to clear the gate`)
+		};
+	}
 	const rejectPool = crawledNotIndexed + softFound;
-	if (totalUrls > 0 && rejectPool > REJECT_MIN && rejectPool / totalUrls >= REJECT_SHARE) return {
-		stage: "quality_rejection",
-		...HEALTH_COPY.quality_rejection,
-		evidence: [{
-			label: "Crawled, then refused",
-			value: fmt(rejectPool)
-		}, {
-			label: "Share of known URLs",
-			value: `${(rejectPool / totalUrls * 100).toFixed(0)}%`
-		}]
-	};
+	if (totalUrls > 0 && rejectPool > REJECT_MIN && rejectPool / totalUrls >= REJECT_SHARE) {
+		const share = rejectPool / totalUrls;
+		const toClear = Math.max(0, Math.ceil(rejectPool - REJECT_SHARE * totalUrls));
+		return {
+			stage: "quality_rejection",
+			...HEALTH_COPY.quality_rejection,
+			evidence: [{
+				label: "Crawled, then refused",
+				value: fmt(rejectPool)
+			}, {
+				label: "Share of known URLs",
+				value: `${(share * 100).toFixed(0)}%`
+			}],
+			progression: escapeReduce("healthy", "crawled-rejected share", share, REJECT_SHARE, `${(share * 100).toFixed(0)}% rejected — improve/consolidate ~${fmt(toClear)} pages to clear`)
+		};
+	}
 	return {
 		stage: "healthy",
 		...HEALTH_COPY.healthy,
-		evidence: []
+		evidence: [],
+		progression: sustain("indexing health", 1, "Indexable pages are getting indexed — no gate blocking reach.")
 	};
 }
 const REACH_COPY = {
@@ -1998,11 +2060,12 @@ const REACH_COPY = {
 		primaryAction: "Refresh the decayed top pages, or mark the site low-priority if it is no longer maintained."
 	}
 };
-function reach(stage, evidence) {
+function reach(stage, evidence, progression) {
 	return {
 		stage,
 		...REACH_COPY[stage],
-		evidence
+		evidence,
+		progression
 	};
 }
 function classifyReachStage(input) {
@@ -2018,27 +2081,39 @@ function classifyReachStage(input) {
 	if (imp12m != null && imp12m < LIFETIME_FLOOR) return reach("waiting_for_data", [{
 		label: "Impressions (12m)",
 		value: fmt(imp12m)
-	}]);
+	}], advance("emerging", "lifetime impressions", imp12m, LIFETIME_FLOOR, `${fmt(imp12m)} of ${fmt(LIFETIME_FLOOR)} lifetime impressions — collecting data, keep indexing`));
 	const hadRealReach = (imp12m ?? imp28d) > LIFETIME_FLOOR;
 	const isGrowing = clicks90dPct != null && clicks90dPct > GROWTH_CLICKS_PCT || imp90dPct != null && imp90dPct > GROWTH_IMPRESSIONS_PCT && posDelta != null && posDelta < 0;
 	if (hadRealReach && liveness != null && liveness < FADED_LIVENESS && !isGrowing) return reach("faded", [{
 		label: "Recent week vs peak",
 		value: `${(liveness * 100).toFixed(0)}%`
-	}]);
+	}], escapeToward("growing", "recent week vs peak (liveness)", liveness, .5, `recent week is ${(liveness * 100).toFixed(0)}% of peak — revive toward ~50%`));
 	if (clicks90dPct != null && clicks90dPct < DECLINE_CLICKS_PCT && clicks28dPct != null && clicks28dPct < DECLINE_CLICKS_PCT && priorClicks != null && priorClicks >= MIN_DECLINE_PRIOR_CLICKS) return reach("declining", [{
 		label: "Clicks 90d",
-		value: `${clicks90dPct.toFixed(0)}%`
+		value: pctStr(clicks90dPct)
 	}, {
 		label: "Clicks 28d",
-		value: `${clicks28dPct.toFixed(0)}%`
-	}]);
-	if (isGrowing) return reach("growing", [...clicks90dPct != null ? [{
-		label: "Clicks 90d",
-		value: `+${clicks90dPct.toFixed(0)}%`
-	}] : [], ...imp90dPct != null ? [{
-		label: "Impressions 90d",
-		value: `+${imp90dPct.toFixed(0)}%`
-	}] : []]);
+		value: pctStr(clicks28dPct)
+	}], {
+		nextStage: "plateaued",
+		metric: "90d clicks change",
+		value: clicks90dPct,
+		target: DECLINE_CLICKS_PCT,
+		pct: clamp01(2 - Math.abs(clicks90dPct) / Math.abs(DECLINE_CLICKS_PCT)),
+		gapLabel: `down ${pctStr(clicks90dPct)} (90d) — recover clicks above ${pctStr(DECLINE_CLICKS_PCT)} to exit`,
+		direction: "escape"
+	});
+	if (isGrowing) {
+		const growthPct = clicks90dPct ?? imp90dPct ?? 0;
+		const growthLabel = clicks90dPct != null ? `${pctStr(clicks90dPct)} 90d clicks — comfortably growing; defend & expand` : `${pctStr(growthPct)} 90d impressions — comfortably growing; defend & expand`;
+		return reach("growing", [...clicks90dPct != null ? [{
+			label: "Clicks 90d",
+			value: `+${clicks90dPct.toFixed(0)}%`
+		}] : [], ...imp90dPct != null ? [{
+			label: "Impressions 90d",
+			value: `+${imp90dPct.toFixed(0)}%`
+		}] : []], sustain("90d clicks growth", growthPct, growthLabel));
+	}
 	const ctr = clicks28d != null && imp28d > 0 ? clicks28d / imp28d : null;
 	if (hadRealReach && imp28d >= NASCENT_IMPRESSIONS_28D && ctr != null && ctr < DECAY_CTR) return reach("decayed", [{
 		label: "Impressions (28d)",
@@ -2046,19 +2121,22 @@ function classifyReachStage(input) {
 	}, {
 		label: "Clicks (28d)",
 		value: fmt(clicks28d ?? 0)
-	}]);
+	}], escapeToward("growing", "CTR (clicks/impressions)", ctr, DECAY_CTR, `${(ctr * 100).toFixed(2)}% CTR on ${fmt(imp28d)} impressions — refresh content toward ~${(DECAY_CTR * 100).toFixed(1)}%`));
+	const growthVal = clicks90dPct ?? 0;
+	const growthGap = Math.max(0, GROWTH_CLICKS_PCT - growthVal);
+	const growthProgression = (stage) => advance("growing", "90d clicks growth", growthVal, GROWTH_CLICKS_PCT, clicks90dPct != null ? `${pctStr(growthVal)} 90d clicks — need ${pctStr(growthGap)} more to clear the +${GROWTH_CLICKS_PCT}% growth bar` : `${stage === "plateaued" ? "flat" : "rising"} — reach +${GROWTH_CLICKS_PCT}% 90d clicks growth to break into growing`);
 	if (imp28d >= ESTABLISHED_IMPRESSIONS_28D) return reach("plateaued", [{
 		label: "Impressions (28d)",
 		value: fmt(imp28d)
-	}]);
+	}], growthProgression("plateaued"));
 	if (imp28d < NASCENT_IMPRESSIONS_28D) return reach("emerging", [{
 		label: "Impressions (28d)",
 		value: fmt(imp28d)
-	}]);
+	}], growthProgression("emerging"));
 	return reach("plateaued", [{
 		label: "Impressions (28d)",
 		value: fmt(imp28d)
-	}]);
+	}], growthProgression("plateaued"));
 }
 function classifySiteTriage(input) {
 	const health = classifyHealthStage(input);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/sdk",
   "type": "module",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Consumer SDK for hosted gscdump.com integrations.",
   "author": {
     "name": "Harlan Wilton",
@@ -41,7 +41,7 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "gscdump": "0.24.0"
+    "gscdump": "0.25.0"
   },
   "peerDependenciesMeta": {
     "gscdump": {
@@ -52,9 +52,9 @@
     "date-fns": "^4.3.0",
     "ofetch": "^1.5.1",
     "zod": "^4.4.3",
-    "@gscdump/analysis": "0.24.0",
-    "@gscdump/engine": "0.24.0",
-    "@gscdump/contracts": "0.24.0"
+    "@gscdump/contracts": "0.25.0",
+    "@gscdump/analysis": "0.25.0",
+    "@gscdump/engine": "0.25.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",