@growth-operations/ui-shared 1.21.1 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-operations/ui-shared",
-  "version": "1.21.1",
+  "version": "1.22.0",
   "description": "Shared HubSpot UI-extension modules (Home, Billing) for Growth Operations apps.",
   "license": "MIT",
   "private": false,

package/src/billing/BillingBanner.jsx

@@ -19,6 +19,11 @@ import { resolveBillingBanner } from "../lib/creditDisplay";
 //                     successful top-up): actions are paused until the next
 //                     billing period or a successful top-up.
 //
+// Andrew 2026-10-13 (banner consolidation): this is the ONE banner — the
+// free-grant trial states (out of credits / trial ended -> RED, trial active
+// -> YELLOW, with the "Need help?" footer) fly HERE on every page; the
+// separate Home-mounted TrialBanner is retired. Copy reused verbatim from it.
+//
 // Legacy metered accounts are unchanged: they only ever see threshold_state
 // "healthy"/"depleted" with over_included doing the talking — overage is
 // "paying overage, not blocked" (the 2026-09-02 incident: a paid account
@@ -35,6 +40,8 @@ import { resolveBillingBanner } from "../lib/creditDisplay";
 //   actionsNoun — short noun phrase for the running-low / paused messages,
 //                 e.g. "file actions" / "task actions". Falls back to
 //                 "actions".
+//   appName     — display name override for the trial-state copy; defaults to
+//                 state.app.name, then "this app".
 //   onNavigate  — in-app PageLink-equivalent callback (the host owns the
 //                 router — see ui-shared's OnboardingChecklist for the same
 //                 pattern). Renders the in-app Billing CTA when provided;
@@ -49,10 +56,11 @@ import { resolveBillingBanner } from "../lib/creditDisplay";
 //                 and the external portal CTA (kind "portal") is NOT
 //                 suppressed. Omitting the prop keeps the legacy behavior
 //                 (button always rendered), so non-updated hosts don't break.
-export function BillingBanner({ state, actionLabel, actionsNoun, onNavigate, context, currentPath }) {
+export function BillingBanner({ state, actionLabel, actionsNoun, appName, onNavigate, context, currentPath }) {
   const banner = resolveBillingBanner(state?.entitlement, {
     actionLabel,
     actionsNoun,
+    appName: appName ?? state?.app?.name,
   });
   if (!banner) return null;
 
@@ -88,6 +96,9 @@ export function BillingBanner({ state, actionLabel, actionsNoun, onNavigate, con
     <Alert title={banner.title} variant={banner.variant}>
       <Flex direction="column" gap="extra-small">
         <Text>{banner.message}</Text>
+        {/* The support footer line rides the trial-state banners (the same
+            microcopy the retired Home TrialBanner rendered). */}
+        {banner.footer && <Text variant="microcopy">{banner.footer}</Text>}
         {banner.cta?.kind === "portal" && portalStartUrl ? (
           <Button
             variant="secondary"

package/src/billing/BillingTab.jsx

@@ -16,7 +16,7 @@ import {
   TableRow,
   TableCell,
 } from "@hubspot/ui-extensions";
-import { fmtDate, fmtMoney, daysUntil } from "../lib/format";
+import { fmtDate, fmtMoney, daysUntil, SUPPORT_FOOTER } from "../lib/format";
 import { useStrictModeEffect } from "../lib/useStrictModeEffect";
 import { CreditMeter } from "../home/CreditMeter";
 import { PlanGrid } from "./PlanGrid";
@@ -82,7 +82,14 @@ function useRefreshedBillingActionTokens(billingBaseUrl, initialTokens) {
 // Color-coded account-status panel (per Andrew's billing feedback): trial =>
 // yellow + days left + end date; active => green + next renewal; past_due =>
 // red + warning. Replaces the low-value flat-rate invoice chart.
-function StatusPanel({ entitlement }) {
+//
+// plansAvailable / restartAvailable describe what the canceled customer can
+// actually SEE below the panel (exported for tests). When a catalog gap
+// leaves plans EMPTY (2026-10-13 sparkfly incident) the "below" copy would
+// promise a grid that isn't there — so it swaps to copy that matches the
+// standalone restart button (or, without a restart token, the Stripe link
+// above), plus the support footer the dead end needs.
+export function StatusPanel({ entitlement, plansAvailable = true, restartAvailable = false }) {
   if (!entitlement) return null;
   const {
     status,
@@ -207,8 +214,15 @@ function StatusPanel({ entitlement }) {
   }
 
   if (status === "canceled") {
-    const resumeCta =
-      mode === "credits"
+    // plansAvailable === false means the catalog mirror came back EMPTY — no
+    // grid renders below, so the copy must not say "below". With a restart
+    // token the standalone one-click restart button (rendered under this
+    // panel) is the recovery path; without one, the Stripe link above is.
+    const resumeCta = !plansAvailable
+      ? restartAvailable
+        ? "Restart your previous plan in one click — we charge your card on file and your data starts syncing again."
+        : "Manage your billing in Stripe with the link above to resume — your data starts syncing again."
+      : mode === "credits"
         ? "Choose a plan below to start a new subscription."
         : "Restart your previous plan below in one click, or choose a different one — either way your data starts syncing again.";
     return (
@@ -216,6 +230,9 @@ function StatusPanel({ entitlement }) {
         <Flex direction="column" gap="extra-small">
           <Text format={{ fontWeight: "bold" }}>Your subscription was canceled</Text>
           <Text>{resumeCta}</Text>
+          {!plansAvailable && (
+            <Text variant="microcopy">{SUPPORT_FOOTER}</Text>
+          )}
         </Flex>
       </Alert>
     );
@@ -228,7 +245,8 @@ function StatusPanel({ entitlement }) {
   );
 }
 
-function TrialSubscriptionBilling({ context, state, appKey, openIframe = null }) {
+// Exported for tests (the canceled/empty-catalog restart fallback).
+export function TrialSubscriptionBilling({ context, state, appKey, openIframe = null }) {
   const ent = state?.entitlement;
 
   // Install not provisioned with a Stripe customer yet — calm "finish setup"
@@ -316,6 +334,21 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
     (isTrialing && currentOrder != null && plans.length > 0) ||
     (needsCheckout && plans.length > 0);
 
+  // Empty-catalog restart fallback (2026-10-13 sparkfly incident): a catalog
+  // data gap can leave `plans` EMPTY for a canceled account — showPicker then
+  // hides the grid while the panel copy still promised one. With no grid to
+  // pick from, the one-click restart becomes THE recovery path: a standalone
+  // primary button hitting /v1/billing/restart/start with NO price_id (the
+  // billing service resolves the account's last subscription price
+  // server-side). Requires the restart action token; legacy/Anvil-mode
+  // entitlements are excluded defensively (BillingTab's mode switch already
+  // routes mode "legacy" to LegacyBilling, so this arm is unreachable for
+  // them — the guard keeps it that way if the switch ever changes).
+  const standaloneRestartUrl =
+    isCanceled && plans.length === 0 && ent.mode !== "legacy"
+      ? keepSubscriptionUrl
+      : null;
+
   return (
     <Flex direction="column" gap="medium">
       {/* PRIMARY CTA when there's an existing subscription to manage
@@ -331,7 +364,11 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
         {portalStartUrl ? "Manage billing in Stripe" : "Preparing billing…"}
       </LoadingButton>
 
-      <StatusPanel entitlement={state?.entitlement} />
+      <StatusPanel
+        entitlement={state?.entitlement}
+        plansAvailable={!needsCheckout || plans.length > 0}
+        restartAvailable={standaloneRestartUrl != null}
+      />
 
       {/* Scheduled-cancel on an ACTIVE sub: one click flips
           cancel_at_period_end off in place (no re-checkout, no new sub) —
@@ -343,9 +380,23 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
         </Button>
       )}
 
+      {/* CANCELED with an EMPTY catalog (no grid to pick from): the
+          price_id-less one-click restart is the recovery path, rendered
+          under the status panel. Reuses keepSubscriptionUrl — the restart
+          endpoint never needed a price_id client-side. */}
+      {standaloneRestartUrl && (
+        <Button href={{ url: standaloneRestartUrl, external: true }} variant="primary">
+          Restart your previous plan
+        </Button>
+      )}
+
       <Text format={{ fontStyle: "italic" }}>
         {needsCheckout
-          ? "Choose a plan below to resume. Once you have an active subscription, use the link above to manage payment methods or view invoices."
+          ? isCanceled && plans.length === 0
+            ? standaloneRestartUrl
+              ? "Restart charges your card on file and resumes syncing immediately — no checkout page. Once you have an active subscription, use the link above to manage payment methods or view invoices."
+              : "Once you have an active subscription, use the link above to manage payment methods or view invoices."
+            : "Choose a plan below to resume. Once you have an active subscription, use the link above to manage payment methods or view invoices."
           : "Billing is managed in Stripe across all Growth Operations apps. Use the link above to update your plan, payment method, or view invoices."}
       </Text>
 

package/src/home/AppHome.jsx

@@ -5,7 +5,6 @@ import { HealthHero } from "./HealthHero";
 import { OnboardingChecklist } from "./OnboardingChecklist";
 import { SyncPulse } from "./SyncPulse";
 import { FeatureUsage } from "./FeatureUsage";
-import { TrialBanner } from "./TrialBanner";
 import { PlanFitBanner } from "./PlanFitBanner";
 import { PeriodComparison } from "./PeriodComparison";
 import { FeatureNudges } from "./FeatureNudges";
@@ -49,8 +48,9 @@ function PipelineTile({ pipeline }) {
 // Picks the single archetype activity tile (CONTRACT: at most ONE present).
 // sync_pulse -> SyncPulse; pipeline -> PipelineTile. The credit meter is
 // deliberately NOT on Home anymore (Andrew's 2026-10 feedback) — it lives at
-// the top of the Usage tab; Home's credit story is the trial banner plus the
-// post-checklist period comparison. Renders nothing when no tile applies.
+// the top of the Usage tab; Home's credit story is the top BillingBanner's
+// trial states plus the post-checklist period comparison. Renders nothing
+// when no tile applies.
 function ArchetypeTile({ state }) {
   if (state.sync_pulse) return <SyncPulse syncPulse={state.sync_pulse} />;
   if (state.pipeline) return <PipelineTile pipeline={state.pipeline} />;
@@ -63,8 +63,7 @@ function ArchetypeTile({ state }) {
 // Lifecycle composition:
 //   no state            -> LoadingSpinner (still fetching /v1/home)
 //   activation pending  -> <InstallProgress> (install isn't finished yet)
-//   activated cockpit   -> <TrialBanner> (credit apps on the free grant)
-//                          + <HealthHero> (+ "...on the right plan" when
+//   activated cockpit   -> <HealthHero> (+ "...on the right plan" when
 //                            plan_fit says so)
 //                          + <PlanFitBanner> (upgrade_recommended only)
 //                          + <OnboardingChecklist> (only if not complete)
@@ -136,10 +135,9 @@ export function AppHome({ state, onNavigate, appName, onRetry, helpfulLinks }) {
           callout above the cockpit; InstallProgress renders null when clean. */}
       <InstallProgress state={state} onRetry={onRetry} />
 
-      {/* Trial states (active countdown / ended / out of credits) fly above
-          the hero — they're the strongest call to action a free account
-          has. Renders null for paid plans and non-credits modes. */}
-      <TrialBanner state={state} appName={appName} />
+      {/* No Home trial banner anymore — Andrew 2026-10-13: trial states (and
+          every other app-stopping billing condition) fly in the ONE top
+          <BillingBanner> the app layout mounts above every route. */}
 
       <HealthHero appName={appName} state={state} />
 

package/src/home/HealthHero.jsx

@@ -26,8 +26,11 @@ export function HealthHero({ appName, state }) {
     // Plan-fit reinforcement: a healthy verdict on the right plan gets the
     // extra reassurance line; upgrade_recommended is carried by health
     // v2's "attention" reasons + the PlanFitBanner, not here.
+    // Dual-read: base nests plan_fit under payload.state; self-hosted
+    // backends MAY emit it top-level (same pattern as planFitOf).
+    const planFit = state.state?.plan_fit ?? state.plan_fit;
     const onRightPlan =
-      health.level === "healthy" && state.plan_fit?.verdict === "right_plan";
+      health.level === "healthy" && planFit?.verdict === "right_plan";
     return (
       <Flex direction="column" gap="small">
         {name && <Heading>{name}</Heading>}

package/src/home/PeriodComparison.jsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { Flex, Tile, Text, ProgressBar } from "@hubspot/ui-extensions";
-import { resolvePeriodComparison } from "../lib/homeBlocks";
+import { periodComparisonOf } from "../lib/homeBlocks";
 
 // The post-checklist Home usage block: the last full billing period vs the
 // current period-to-date, side by side — one bar per period (shared
@@ -41,7 +41,9 @@ function PeriodColumn({ period, maxTotal }) {
 }
 
 export function PeriodComparison({ state }) {
-  const view = resolvePeriodComparison(state?.period_comparison);
+  // periodComparisonOf dual-reads payload.state.period_comparison (base) ??
+  // payload.period_comparison (self-hosted).
+  const view = periodComparisonOf(state);
   if (!view) return null;
 
   return (

package/src/home/PlanFitBanner.jsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { Text, Alert } from "@hubspot/ui-extensions";
-import { resolvePlanFit } from "../lib/homeBlocks";
+import { planFitOf } from "../lib/homeBlocks";
 
 // The plan-fit savings banner: when state.plan_fit.verdict is
 // "upgrade_recommended", tell the customer what staying on their current tier
@@ -14,7 +14,10 @@ import { resolvePlanFit } from "../lib/homeBlocks";
 // Renders nothing when the block is absent or the verdict isn't
 // upgrade_recommended.
 export function PlanFitBanner({ state }) {
-  const fit = resolvePlanFit(state?.plan_fit);
+  // planFitOf dual-reads payload.state.plan_fit (base) ?? payload.plan_fit
+  // (self-hosted) — a top-level-only read left this banner dead on every
+  // base-hosted app (found 2026-10-13).
+  const fit = planFitOf(state);
   if (!fit || fit.kind !== "upgrade_recommended") return null;
 
   return (

package/src/index.js

@@ -14,7 +14,6 @@ export { FeatureNudges } from "./home/FeatureNudges";
 export { FeatureUsage } from "./home/FeatureUsage";
 export { CreditMeter } from "./home/CreditMeter";
 export { HelpfulLinks } from "./home/HelpfulLinks";
-export { TrialBanner } from "./home/TrialBanner";
 export { PlanFitBanner } from "./home/PlanFitBanner";
 export { PeriodComparison } from "./home/PeriodComparison";
 export { UsageHighlights } from "./home/UsageHighlights";
@@ -48,20 +47,22 @@ export {
   statusVariant,
   STATUS_LABELS,
   STATUS_VARIANT,
+  SUPPORT_FOOTER,
 } from "./lib/format";
 export { useStrictModeEffect } from "./lib/useStrictModeEffect";
 export { resolveFeatureUsage, featureUsageOf } from "./lib/featureUsage";
 export {
   hasTopUpBank,
+  creditsBlockOf,
   resolveCreditMeter,
   resolveBillingBanner,
   parseLimitInput,
 } from "./lib/creditDisplay";
 export {
-  TRIAL_BANNER_FOOTER,
-  resolveTrialBanner,
   resolvePlanFit,
+  planFitOf,
   resolvePeriodComparison,
+  periodComparisonOf,
 } from "./lib/homeBlocks";
 export {
   AUTO_PROVISION_TITLE,

package/src/lib/creditDisplay.js

@@ -25,6 +25,7 @@
 //   double-guards so a stale/mixed payload can't regress the 2026-09-02
 //   incident where a paying, overage account was shown a blocking
 //   "Depleted"/"out of credits" panel).
+import { daysUntil, SUPPORT_FOOTER } from "./format";
 
 // True when the account has (or ever had) a top-up bank. Note the CreditMeter
 // bank section renders only while the bank HAS credits left (bankRemaining >
@@ -98,6 +99,15 @@ function bankBarVariantFor(bankRemaining, bankGranted) {
   if (bankRemaining * 100 <= 50 * bankGranted) return "warning";
   return "success";
 }
+// The credits block lives at payload.state.credits on base-hosted backends; a
+// self-hosted backend MAY emit it top-level. Dual-read (nested wins), same as
+// featureUsageOf/planFitOf — without this the meter falls back to the legacy
+// single-bar path (no monthly/additional split, no "renews on" line).
+export function creditsBlockOf(state) {
+  if (!state || typeof state !== "object") return null;
+  return state.state?.credits ?? state.credits ?? null;
+}
+
 export function resolveCreditMeter(entitlement, creditMeter, credits = null) {
   const ent = entitlement?.mode === "credits" ? entitlement : null;
   const meter = creditMeter ?? null;
@@ -302,9 +312,77 @@ export function resolveCreditMeter(entitlement, creditMeter, credits = null) {
   };
 }
 
+// --- Free-grant trial states (consolidated into the TOP banner) ------------
+
+// Andrew 2026-10-13: ONE banner at the top of every page. Anything that STOPS
+// the app — out of credits, trial ended, payment failed — flies RED in the
+// top BillingBanner; "trial active" flies YELLOW there too. The separate
+// Home-mounted TrialBanner is retired; its copy (approved by the product
+// owner) is reused VERBATIM here — only the placement and the trial-ended
+// variant (warning -> error: it stops the app) changed.
+//
+// First match wins inside trialStateOf, mirroring the retired resolver:
+//   out of credits  — the free grant is spent (depleted / remaining <= 0).
+//                     Beats the clock: a burned-through grant is "out of
+//                     credits" even with days left.
+//   trial ended     — the grant's 30-day clock ran out with credits left.
+//   trial active    — the clock is still running: "[XX] trial days remaining".
+// Returns { kind, title, body } or null (no grant clock on record).
+function trialStateOf(ent, { appName } = {}) {
+  const name = appName ?? "this app";
+  const granted = ent.granted ?? 0;
+  const used = ent.used ?? 0;
+  const remaining = ent.remaining ?? Math.max(granted - used, 0);
+  const daysLeft =
+    ent.grant_expires_at != null ? daysUntil(ent.grant_expires_at) : null;
+
+  if (ent.depleted === true || remaining <= 0) {
+    return {
+      kind: "out_of_credits",
+      title: "You're out of credits",
+      body: `You have used ${used}/${granted} free credits. Select one of the plans below to continue use of ${name}.`,
+    };
+  }
+  if (daysLeft != null && daysLeft <= 0) {
+    return {
+      kind: "trial_ended",
+      title: "Your trial has ended",
+      body: `Your free trial has ended. Select a plan to continue use of ${name}.`,
+    };
+  }
+  if (daysLeft != null) {
+    return {
+      kind: "trial_active",
+      title: `${daysLeft} trial days remaining`,
+      body: `You have ${daysLeft} days remaining in your trial period. Select a plan to continue use of ${name}.`,
+    };
+  }
+  return null;
+}
+
+// Trial states map onto the banner shape with the shared support footer and a
+// Billing-tab CTA (the copy asks for a plan; on non-Home pages nothing is
+// "below", so the button routes to the picker). out-of-credits/trial-ended
+// are RED (they stop the app), trial-active is YELLOW — Andrew 2026-10-13.
+const TRIAL_STATE_VARIANT = {
+  out_of_credits: "error",
+  trial_ended: "error",
+  trial_active: "warning",
+};
+
+function trialBannerView(trial) {
+  return {
+    variant: TRIAL_STATE_VARIANT[trial.kind],
+    title: trial.title,
+    message: trial.body,
+    footer: SUPPORT_FOOTER,
+    cta: { kind: "billing", label: "Go to Billing →" },
+  };
+}
+
 // Resolve the app-wide BillingBanner from the credits entitlement arm.
 // Returns null to render nothing (non-credits mode, pre-install, or healthy),
-// else { variant, title, message, cta } where cta is null or:
+// else { variant, title, message, footer?, cta } where cta is null or:
 //   { kind: "portal",  label } — link out to the Stripe billing-portal entry
 //                                point (payment-method fixes)
 //   { kind: "billing", label } — in-app navigate to the Billing tab
@@ -312,7 +390,23 @@ export function resolveCreditMeter(entitlement, creditMeter, credits = null) {
 // Driven by threshold_state for the top-up model; the legacy metered branches
 // (free depleted / paid over_included / free running-low) are byte-identical
 // to the pre-top-up banner.
-export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } = {}) {
+//
+// Precedence (first match wins):
+//   1. top_up_pending  (info)    — transient in-flight top-up
+//   2. top_up_failed   (error)   — card on file failed to process
+//   3. limit_reached   (warning)
+//   4. depleted        (error)   — THE out-of-credits block; existing
+//                                  byte-identical copy wins whenever the
+//                                  explicit signals (threshold_state /
+//                                  depleted flag / entitled=false) fire
+//   5. trial out_of_credits (error) — free grant spent WITHOUT the explicit
+//                                  signals (remaining <= 0 catch-all)
+//   6. trial ended     (error)   — the grant clock ran out with credits left
+//   7. over_included   (warning) — paid metered overage (never blocked)
+//   8. running low     (warning) — free grant under low_threshold
+//   9. trial active    (warning) — the countdown; yields to running-low, the
+//                                  more urgent of the two yellow states
+export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun, appName } = {}) {
   const ent = entitlement;
   if (!ent || ent.mode !== "credits" || ent.status === "not_installed") {
     return null;
@@ -353,6 +447,14 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
     };
   }
 
+  // The free-grant trial states (null for paid plans — a paid plan is past
+  // the trial). Computed BEFORE the depleted branch: a lapsed trial clock
+  // explains a legacy `entitled: false` reading better than "out of credits"
+  // (credits remain; the GRANT expired), so trial_ended wins over that one
+  // legacy signal below — but never over an explicit depleted flag or
+  // threshold_state "depleted".
+  const trial = onPaidPlan ? null : trialStateOf(ent, { appName });
+
   // --- Hard-blocked. threshold_state "depleted" is the ONLY blocking state
   // (a topup-model paid plan blocks at true zero); `over_included` overrides
   // a depleted reading so a metered paid account in overage is never shown as
@@ -362,7 +464,9 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
   const depleted =
     thresholdState != null
       ? thresholdState === "depleted" && !overIncluded
-      : !onPaidPlan && (ent.depleted === true || ent.entitled === false);
+      : !onPaidPlan &&
+        (ent.depleted === true ||
+          (ent.entitled === false && trial?.kind !== "trial_ended"));
 
   if (depleted) {
     return {
@@ -374,6 +478,11 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
       cta: { kind: "billing", label: "Go to Billing →" },
     };
   }
+  // Free-grant blockers the explicit signals didn't catch: the spent grant
+  // (remaining <= 0 without any flag) and the lapsed trial clock.
+  if (trial && (trial.kind === "out_of_credits" || trial.kind === "trial_ended")) {
+    return trialBannerView(trial);
+  }
   if (overIncluded) {
     return {
       variant: "warning",
@@ -396,6 +505,11 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
       cta: { kind: "billing", label: "Go to Billing →" },
     };
   }
+  // Trial active — the countdown flies at the top in YELLOW for the whole
+  // trial (Andrew 2026-10-13), yielding only to running-low above.
+  if (trial?.kind === "trial_active") {
+    return trialBannerView(trial);
+  }
 
   return null;
 }

package/src/lib/format.js

@@ -1,6 +1,12 @@
 // Shared formatting + status helpers for Growth Operations app UIs.
 // Framework-agnostic (no React) so they can be unit-reasoned and reused.
 
+// The support footer line shared by customer-facing dead-end/urgency surfaces
+// (the top billing banner's trial states, the Billing tab's empty-catalog
+// canceled panel). Formerly TRIAL_BANNER_FOOTER on the retired Home
+// TrialBanner — promoted here once a second surface needed it.
+export const SUPPORT_FOOTER = "Need help? info@growthoperationsco.com";
+
 // ISO datetime string (or ms epoch) -> "Mon DD, YYYY", null-safe.
 // new Date(NaN).toLocaleDateString() would throw, so guard it.
 export function fmtDate(value) {

package/src/lib/homeBlocks.js

@@ -1,71 +1,16 @@
 // Pure resolvers for the Home cockpit blocks added for Andrew's 2026-10
-// App Home feedback: the trial banner (three states), the plan-fit signal,
-// and the period-over-period credit comparison. Framework-free (no React) so
-// the branch math is unit-testable; the components in ../home stay thin.
+// App Home feedback: the plan-fit signal and the period-over-period credit
+// comparison. Framework-free (no React) so the branch math is unit-testable;
+// the components in ../home stay thin.
+//
+// (The trial banner used to live here. Andrew 2026-10-13: ONE banner at the
+// top of every page — the trial states moved into resolveBillingBanner in
+// ./creditDisplay, copy verbatim, and the Home-mounted <TrialBanner> is
+// retired.)
 //
 // Everything here degrades gracefully: every block is additive on the
 // /v1/home payload, and a resolver returns null (render nothing) whenever
 // the fields it needs are absent.
-import { daysUntil } from "./format";
-
-// --- Trial banner ----------------------------------------------------------
-
-// Rides under every trial banner (Andrew's exact copy).
-export const TRIAL_BANNER_FOOTER = "Need help? info@growthoperationsco.com";
-
-// Resolve the Home trial banner from the credits entitlement arm.
-// Returns null (render nothing) for non-credits modes, paid plans (the trial
-// is over), pre-install, or a backend that carries no grant clock. Otherwise
-// { variant, title, body, footer } — copy verbatim from Andrew, with the app
-// display name templated in.
-//
-// State selection (first match wins):
-//   out of credits  — the free grant is spent (depleted / remaining <= 0).
-//                     Beats the clock: a burned-through grant is "out of
-//                     credits" even with days left.
-//   trial ended     — the grant's 30-day clock ran out with credits left.
-//   trial active    — the clock is still running: "[XX] trial days remaining".
-export function resolveTrialBanner(entitlement, { appName } = {}) {
-  const ent = entitlement;
-  if (!ent || ent.mode !== "credits") return null;
-  if (ent.plan) return null; // a paid plan is past the trial
-  if (ent.status === "not_installed") return null;
-  const name = appName ?? "this app";
-
-  const granted = ent.granted ?? 0;
-  const used = ent.used ?? 0;
-  const remaining = ent.remaining ?? Math.max(granted - used, 0);
-  const daysLeft =
-    ent.grant_expires_at != null ? daysUntil(ent.grant_expires_at) : null;
-
-  if (ent.depleted === true || remaining <= 0) {
-    return {
-      variant: "error",
-      title: "You're out of credits",
-      body: `You have used ${used}/${granted} free credits. Select one of the plans below to continue use of ${name}.`,
-      footer: TRIAL_BANNER_FOOTER,
-    };
-  }
-  if (daysLeft != null && daysLeft <= 0) {
-    return {
-      variant: "warning",
-      title: "Your trial has ended",
-      body: `Your free trial has ended. Select a plan to continue use of ${name}.`,
-      footer: TRIAL_BANNER_FOOTER,
-    };
-  }
-  if (daysLeft != null) {
-    return {
-      variant: "info",
-      title: `${daysLeft} trial days remaining`,
-      body: `You have ${daysLeft} days remaining in your trial period. Select a plan to continue use of ${name}.`,
-      footer: TRIAL_BANNER_FOOTER,
-    };
-  }
-  // No grant clock on record (a backend that predates grant_expires_at) —
-  // nothing to count down, so no banner.
-  return null;
-}
 
 // --- Plan fit ---------------------------------------------------------------
 
@@ -114,6 +59,15 @@ export function resolvePlanFit(planFit) {
   return null;
 }
 
+// The plan_fit block lives at payload.state.plan_fit on base-hosted backends;
+// a self-hosted backend MAY emit it top-level instead. Dual-read (nested
+// wins), same as featureUsageOf — without this the banner/hero line silently
+// never render (shipped dead 2026-10-12, found 2026-10-13).
+export function planFitOf(state) {
+  if (!state || typeof state !== "object") return null;
+  return resolvePlanFit(state.state?.plan_fit ?? state.plan_fit);
+}
+
 // --- Period comparison ------------------------------------------------------
 
 // Resolve the period_comparison block (null until the install has one full
@@ -144,3 +98,12 @@ export function resolvePeriodComparison(periodComparison) {
     maxTotal: Math.max(last.total, current.total, 1),
   };
 }
+
+// Same nested-vs-top-level duality as planFitOf: base serves
+// payload.state.period_comparison; self-hosted backends MAY go top-level.
+export function periodComparisonOf(state) {
+  if (!state || typeof state !== "object") return null;
+  return resolvePeriodComparison(
+    state.state?.period_comparison ?? state.period_comparison
+  );
+}

package/src/usage/UsageTab.jsx

@@ -27,6 +27,7 @@ import {
 } from "@hubspot/ui-extensions";
 
 import { useStrictModeEffect } from "../lib/useStrictModeEffect";
+import { creditsBlockOf } from "../lib/creditDisplay";
 import { CreditMeter } from "../home/CreditMeter";
 
 const DEFAULT_BASE_PATH = "/api/v1/usage";
@@ -56,10 +57,13 @@ export function UsageTab({
   return (
     <Flex direction="column" gap="medium">
       {state && (
+        // creditsBlockOf dual-reads payload.state.credits (base) ??
+        // payload.credits (self-hosted) — a top-level-only read silently
+        // dropped the two-pool split + "renews on" line on base-hosted apps.
         <CreditMeter
           entitlement={state.entitlement}
           creditMeter={state.credit_meter}
-          credits={state.credits}
+          credits={creditsBlockOf(state)}
         />
       )}
 

package/src/home/TrialBanner.jsx

@@ -1,32 +0,0 @@
-import React from "react";
-import { Flex, Text, Alert } from "@hubspot/ui-extensions";
-import { resolveTrialBanner } from "../lib/homeBlocks";
-
-// The Home trial banner for credit apps — Andrew's 2026-10 copy, in all three
-// states (active countdown / ended-with-credits-left / out of credits), with
-// the "Need help?" footer line. State selection + copy live in
-// ../lib/homeBlocks (unit-tested); this is pure rendering.
-//
-// Renders nothing for paid plans, non-credits modes, pre-install, or a
-// backend that carries no grant clock (resolveTrialBanner returns null).
-//
-// Props:
-//   state   — the /v1/home payload (reads entitlement + app.name).
-//   appName — display name override; defaults to state.app.name.
-export function TrialBanner({ state, appName }) {
-  const banner = resolveTrialBanner(state?.entitlement, {
-    appName: appName ?? state?.app?.name,
-  });
-  if (!banner) return null;
-
-  return (
-    <Alert title={banner.title} variant={banner.variant}>
-      <Flex direction="column" gap="extra-small">
-        <Text>{banner.body}</Text>
-        <Text variant="microcopy">{banner.footer}</Text>
-      </Flex>
-    </Alert>
-  );
-}
-
-export default TrialBanner;