@startsimpli/billing 0.4.18 → 0.4.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.18",
+  "version": "0.4.20",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -8,6 +8,7 @@
     ".": "./src/index.ts",
     "./client": "./src/index.ts",
     "./server": "./src/server/index.ts",
+    "./plan": "./src/utils/plan.ts",
     "./types": "./src/types/index.ts",
     "./mock": "./src/mock/index.ts"
   },

package/src/components/PricingDetailPage.tiers.test.tsx

@@ -0,0 +1,178 @@
+/**
+ * Tiers are cumulative: a paid plan includes what the cheaper plan includes.
+ *
+ * Real offer data only lists what a tier ADDS — crochet-pro declares
+ * advanced_generation / stitch_library / pdf_export / custom_sizing and omits
+ * the basic_generation and save_patterns that crochet-free declares. The table
+ * rendered every omission as an em-dash, so the paid plan showed a dash exactly
+ * where the free plan showed a tick, and read as though Pro could not save
+ * patterns. Reported as "the paid plan doesn't look like it has more checks".
+ *
+ * The fixture in PricingDetailPage.test.tsx restates every feature on every
+ * tier, which is why this never showed up there. This one is shaped like the
+ * data production actually serves.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import React from "react";
+import { BillingProvider } from "../hooks/BillingProvider";
+import { PricingDetailPage } from "./PricingDetailPage";
+import type { BillingProduct, OfferFeature } from "../types";
+
+function offer(
+  over: Partial<BillingProduct["offers"][number]> & { name: string; slug: string; features: OfferFeature[] },
+) {
+  return {
+    id: over.slug,
+    unitPrice: "0.00",
+    currency: "USD",
+    pricingModel: "flat" as const,
+    intervalUnit: "month" as const,
+    intervalCount: 1,
+    intervalDisplay: "per month",
+    isRecurring: true,
+    isFree: false,
+    isActive: true,
+    isFeatured: false,
+    trialDays: 0,
+    sortOrder: 0,
+    ctaText: "Choose",
+    ...over,
+  };
+}
+
+/** Shaped like the live crochet-patterns product. */
+const product: BillingProduct = {
+  id: "prod-crochet",
+  slug: "crochet-patterns",
+  name: "Crochet Patterns",
+  description: "AI-powered crochet pattern generator",
+  offers: [
+    offer({
+      name: "Free",
+      slug: "crochet-free",
+      isFree: true,
+      sortOrder: 0,
+      features: [
+        { key: "patterns_per_month", name: "Patterns per month", value: 3, limit: 3 },
+        { key: "basic_generation", name: "Basic pattern generation", value: true },
+        { key: "save_patterns", name: "Save patterns", value: true },
+      ],
+    }),
+    offer({
+      name: "Pro",
+      slug: "crochet-pro",
+      unitPrice: "9.00",
+      sortOrder: 1,
+      isFeatured: true,
+      features: [
+        { key: "patterns_per_month", name: "Patterns per month", value: -1 },
+        { key: "advanced_generation", name: "Advanced pattern generation", value: true },
+        { key: "pdf_export", name: "PDF export", value: true },
+      ],
+    }),
+  ],
+};
+
+function renderPricing(p: BillingProduct = product) {
+  const fetcher = vi.fn().mockResolvedValue({
+    ok: true,
+    json: () => Promise.resolve(p),
+  }) as unknown as typeof fetch;
+
+  return render(
+    <BillingProvider apiBaseUrl="https://api.test.com/api/v1" fetcher={fetcher}>
+      <PricingDetailPage productId={p.slug} />
+    </BillingProvider>,
+  );
+}
+
+/** The cell for one offer in one feature row, by column position. */
+function cell(featureKey: string, column: number) {
+  const row = screen.getByTestId(`comparison-row-${featureKey}`);
+  // column 0 is the feature name.
+  return within(row).getAllByRole("cell")[column + 1];
+}
+
+describe("comparison table — cumulative tiers", () => {
+  it("shows the paid plan as including what the free plan includes", async () => {
+    renderPricing();
+    await waitFor(() => expect(screen.getByTestId("comparison-table")).toBeDefined());
+
+    for (const key of ["basic_generation", "save_patterns"]) {
+      const pro = cell(key, 1);
+      expect(within(pro).queryByLabelText("Included"), key).not.toBeNull();
+      expect(pro.textContent, key).not.toContain("—");
+    }
+  });
+
+  it("gives the paid plan more ticks than the free plan, which is the whole point", async () => {
+    renderPricing();
+    await waitFor(() => expect(screen.getByTestId("comparison-table")).toBeDefined());
+
+    const ticks = (column: number) =>
+      ["basic_generation", "save_patterns", "advanced_generation", "pdf_export"].filter(
+        (key) => within(cell(key, column)).queryByLabelText("Included") !== null,
+      ).length;
+
+    expect(ticks(1)).toBeGreaterThan(ticks(0));
+  });
+
+  it("still lets a higher tier opt out by saying so explicitly", async () => {
+    renderPricing({
+      ...product,
+      offers: [
+        product.offers[0],
+        {
+          ...product.offers[1],
+          features: [
+            ...product.offers[1].features,
+            { key: "save_patterns", name: "Save patterns", value: false },
+          ],
+        },
+      ],
+    });
+    await waitFor(() => expect(screen.getByTestId("comparison-table")).toBeDefined());
+
+    expect(within(cell("save_patterns", 1)).queryByLabelText("Not included")).not.toBeNull();
+  });
+
+  it("never inherits a numeric allowance — a bigger plan must state its own", async () => {
+    renderPricing({
+      ...product,
+      offers: [
+        product.offers[0],
+        {
+          ...product.offers[1],
+          // Pro forgot to declare patterns_per_month.
+          features: product.offers[1].features.filter((f) => f.key !== "patterns_per_month"),
+        },
+      ],
+    });
+    await waitFor(() => expect(screen.getByTestId("comparison-table")).toBeDefined());
+
+    // Claiming Pro is capped at the free plan's 3 would be worse than saying nothing.
+    expect(cell("patterns_per_month", 1).textContent).not.toContain("3");
+  });
+
+  it("leaves the cheapest plan alone — nothing below it to inherit", async () => {
+    renderPricing();
+    await waitFor(() => expect(screen.getByTestId("comparison-table")).toBeDefined());
+
+    for (const key of ["advanced_generation", "pdf_export"]) {
+      expect(within(cell(key, 0)).queryByLabelText("Included"), key).toBeNull();
+    }
+  });
+
+  it("tells the reader on the card that a paid plan builds on the free one", async () => {
+    renderPricing();
+    await waitFor(() => expect(screen.getByTestId("detail-card-crochet-pro")).toBeDefined());
+
+    const proCard = screen.getByTestId("detail-card-crochet-pro");
+    expect(within(proCard).getByText(/everything in free/i)).toBeDefined();
+
+    const freeCard = screen.getByTestId("detail-card-crochet-free");
+    expect(within(freeCard).queryByText(/everything in/i)).toBeNull();
+  });
+});

package/src/components/PricingDetailPage.tsx

@@ -11,6 +11,7 @@
 import React from "react";
 import { useProduct } from "../hooks/useProduct";
 import type { ProductOffer, OfferFeature } from "../types";
+import { cumulativeFeatureLookup, tierBelow } from "../utils/tiers";
 
 export interface PricingDetailPageProps {
   /** Product slug (e.g., "raise-simpli") */
@@ -83,6 +84,7 @@ export function PricingDetailPage({
             key={offer.id}
             offer={offer}
             onSelect={onSelectOffer}
+            buildsOn={tierBelow(product.offers, offer)?.name ?? null}
           />
         ))}
       </div>
@@ -101,9 +103,11 @@ export function PricingDetailPage({
 interface DetailCardProps {
   offer: ProductOffer;
   onSelect?: (offer: ProductOffer) => void;
+  /** Name of the tier just below this one, when there is one. */
+  buildsOn?: string | null;
 }
 
-function DetailCard({ offer, onSelect }: DetailCardProps) {
+function DetailCard({ offer, onSelect, buildsOn }: DetailCardProps) {
   const isFeatured = offer.isFeatured;
 
   return (
@@ -146,6 +150,12 @@ function DetailCard({ offer, onSelect }: DetailCardProps) {
         </span>
       )}
 
+      {buildsOn && (
+        <p className="text-sm font-semibold text-gray-900 mb-1">
+          Everything in {buildsOn}, plus:
+        </p>
+      )}
+
       <ul className="list-none p-0 m-0 mb-7 flex-1 space-y-0">
         {offer.features.map((feature) => (
           <li
@@ -202,14 +212,9 @@ interface ComparisonTableProps {
 }
 
 function ComparisonTable({ offers, featureKeys, featureNameMap }: ComparisonTableProps) {
-  // Build a lookup: offer slug -> feature key -> feature
-  const featureLookup: Record<string, Record<string, OfferFeature>> = {};
-  for (const offer of offers) {
-    featureLookup[offer.slug] = {};
-    for (const feature of offer.features) {
-      featureLookup[offer.slug][feature.key] = feature;
-    }
-  }
+  // offer slug -> feature key -> feature, with cheaper tiers' capabilities
+  // carried upward so a paid plan never shows a dash where free shows a tick.
+  const featureLookup = cumulativeFeatureLookup(offers);
 
   return (
     <div data-testid="comparison-table" className="overflow-x-auto">

package/src/components/PricingSection.test.tsx

@@ -315,4 +315,24 @@ describe("PricingSection", () => {
       expect(screen.getByText(/unable to load/i)).toBeDefined();
     });
   });
+
+  // The home-page cards sit next to /pricing, which says "Everything in Free,
+  // plus:" on the paid tier. Without it, a card that lists only what the tier
+  // ADDS reads as a plan that lost the cheaper tier's features.
+  it("says a paid tier builds on the one below it", async () => {
+    const Wrapper = createWrapper(mockFetchSuccess());
+
+    render(
+      <Wrapper>
+        <PricingSection productId="raise-simpli" />
+      </Wrapper>
+    );
+
+    await waitFor(() => expect(screen.getByTestId("pricing-section")).toBeDefined());
+
+    expect(screen.getAllByText(/everything in starter, plus/i).length).toBeGreaterThan(0);
+    // The cheapest tier has nothing below it.
+    const starter = screen.getByTestId("section-card-starter-monthly");
+    expect(starter.textContent).not.toMatch(/everything in/i);
+  });
 });

package/src/components/PricingSection.tsx

@@ -11,6 +11,7 @@
 import React from "react";
 import { useProduct } from "../hooks/useProduct";
 import type { ProductOffer } from "../types";
+import { tierBelow } from "../utils/tiers";
 
 export interface PricingSectionProps {
   /** Product slug (e.g., "raise-simpli") */
@@ -63,6 +64,7 @@ export function PricingSection({
             offer={offer}
             onSelect={onSelectOffer}
             maxFeatures={maxFeatures}
+            buildsOn={tierBelow(product.offers, offer)?.name ?? null}
           />
         ))}
       </div>
@@ -74,9 +76,11 @@ interface SectionCardProps {
   offer: ProductOffer;
   onSelect?: (offer: ProductOffer) => void;
   maxFeatures: number;
+  /** Name of the tier just below this one, when there is one. */
+  buildsOn?: string | null;
 }
 
-function SectionCard({ offer, onSelect, maxFeatures }: SectionCardProps) {
+function SectionCard({ offer, onSelect, maxFeatures, buildsOn }: SectionCardProps) {
   const isFeatured = offer.isFeatured;
   const visibleFeatures = offer.features.slice(0, maxFeatures);
 
@@ -116,6 +120,12 @@ function SectionCard({ offer, onSelect, maxFeatures }: SectionCardProps) {
         </span>
       )}
 
+      {buildsOn && (
+        <p className="text-sm font-semibold text-gray-900 mb-1">
+          Everything in {buildsOn}, plus:
+        </p>
+      )}
+
       <ul className="list-none p-0 m-0 mb-4 flex-1 space-y-0">
         {visibleFeatures.map((feature) => (
           <li

package/src/index.ts

@@ -57,4 +57,5 @@ export type {
 export { BillingApiClient } from "./utils/api";
 
 // Pure helpers
-export { isPaidSubscription } from "./utils/plan";
+export { isPaidSubscription, getFeatureLimit, resolvePlanEntitlement, resolveUsageWindow } from "./utils/plan";
+export type { PlanEntitlement, ResolvePlanEntitlementOptions, UsageWindow } from "./utils/plan";

package/src/utils/plan.test.ts

@@ -85,3 +85,230 @@ describe('isPaidSubscription', () => {
     expect(isPaidSubscription(sub)).toBe(false)
   })
 })
+
+// ---------------------------------------------------------------------------
+// Entitlement resolution (startsim-ol36d.9 / .12)
+//
+// `isPaidSubscription` answers "is this a paid plan". Gating needs three more
+// things it cannot express:
+//   1. what to do when billing is LOADING or ERRORED — the old crochet gate
+//      treated "unknown" as paid and opened Pro features to everyone;
+//   2. how big the allowance is — read from the offer's own feature list, not
+//      hardcoded in each app;
+//   3. which window to count usage in — a free subscription's
+//      current_period_start is frozen at signup and never rolls.
+// ---------------------------------------------------------------------------
+
+import { getFeatureLimit, resolvePlanEntitlement, resolveUsageWindow } from './plan'
+
+const freeOffer = makeOffer({
+  slug: 'crochet-free',
+  isFree: true,
+  unitPrice: '0.00',
+  features: [
+    { key: 'patterns_per_month', name: 'Patterns per month', value: 3, limit: 3 },
+    { key: 'save_patterns', name: 'Save patterns', value: true, limit: null },
+  ],
+})
+
+const proOffer = makeOffer({
+  slug: 'crochet-pro',
+  isFree: false,
+  unitPrice: '9.00',
+  trialDays: 7,
+  features: [
+    { key: 'patterns_per_month', name: 'Patterns per month', value: -1, limit: null },
+    { key: 'pdf_export', name: 'PDF export', value: true, limit: null },
+  ],
+})
+
+describe('getFeatureLimit', () => {
+  it('reads the numeric allowance from the offer', () => {
+    expect(getFeatureLimit(freeOffer, ['patterns_per_month'])).toBe(3)
+  })
+
+  it('maps -1 to Infinity (unlimited)', () => {
+    expect(getFeatureLimit(proOffer, ['patterns_per_month'])).toBe(Infinity)
+  })
+
+  it('maps the string "unlimited" to Infinity', () => {
+    const offer = makeOffer({
+      features: [{ key: 'patterns_per_month', name: 'x', value: 'unlimited', limit: null }],
+    })
+    expect(getFeatureLimit(offer, ['patterns_per_month'])).toBe(Infinity)
+  })
+
+  it('prefers `limit` over `value` when both are set', () => {
+    const offer = makeOffer({
+      features: [{ key: 'patterns_per_month', name: 'x', value: 99, limit: 3 }],
+    })
+    expect(getFeatureLimit(offer, ['patterns_per_month'])).toBe(3)
+  })
+
+  it('accepts an alias key', () => {
+    const offer = makeOffer({
+      features: [{ key: 'monthly_generations', name: 'x', value: 7, limit: null }],
+    })
+    expect(getFeatureLimit(offer, ['patterns_per_month', 'monthly_generations'])).toBe(7)
+  })
+
+  it('returns null when the offer declares no such feature', () => {
+    expect(getFeatureLimit(makeOffer(), ['patterns_per_month'])).toBeNull()
+  })
+
+  it('returns null for a missing offer rather than throwing', () => {
+    expect(getFeatureLimit(null, ['patterns_per_month'])).toBeNull()
+  })
+})
+
+describe('resolvePlanEntitlement', () => {
+  const opts = { featureKeys: ['patterns_per_month'], freeFallbackLimit: 3 }
+
+  it('treats an active FREE offer as free and uses the offer allowance', () => {
+    const e = resolvePlanEntitlement(makeSub({ status: 'active', offer: freeOffer }), opts)
+    expect(e.isFree).toBe(true)
+    expect(e.isPaid).toBe(false)
+    expect(e.limit).toBe(3)
+    expect(e.isUnlimited).toBe(false)
+    expect(e.unknown).toBe(false)
+  })
+
+  it('does NOT depend on the offer slug being the literal "free"', () => {
+    // The real slug is `crochet-free`. A slug === 'free' test silently
+    // misclassified all 120 real free holders as paid.
+    const e = resolvePlanEntitlement(makeSub({ status: 'active', offer: freeOffer }), opts)
+    expect(e.isFree).toBe(true)
+  })
+
+  it('treats an active PAID offer as paid and unlimited', () => {
+    const e = resolvePlanEntitlement(makeSub({ status: 'active', offer: proOffer }), opts)
+    expect(e.isPaid).toBe(true)
+    expect(e.isFree).toBe(false)
+    expect(e.isUnlimited).toBe(true)
+    expect(e.limit).toBe(Infinity)
+  })
+
+  it('treats a TRIALING paid plan as paid, not free', () => {
+    // A 7-day Pro trial is a paying customer mid-trial; the old gate gave them
+    // free limits because it tested `status === 'active'`.
+    const e = resolvePlanEntitlement(makeSub({ status: 'trialing', offer: proOffer }), opts)
+    expect(e.isPaid).toBe(true)
+    expect(e.isFree).toBe(false)
+    expect(e.isUnlimited).toBe(true)
+  })
+
+  it('fails CLOSED while billing is loading', () => {
+    const e = resolvePlanEntitlement(null, { ...opts, loading: true })
+    expect(e.isFree).toBe(true)
+    expect(e.isPaid).toBe(false)
+    expect(e.unknown).toBe(true)
+    expect(e.limit).toBe(3)
+  })
+
+  it('fails CLOSED when the billing call errored', () => {
+    // The old gate did `!subscriptionError && (...)`, so an error made
+    // isFreeUser false — i.e. an outage handed everyone Pro.
+    const e = resolvePlanEntitlement(null, { ...opts, error: new Error('boom') })
+    expect(e.isFree).toBe(true)
+    expect(e.isPaid).toBe(false)
+    expect(e.unknown).toBe(true)
+  })
+
+  it('treats no subscription at all as free', () => {
+    const e = resolvePlanEntitlement(null, opts)
+    expect(e.isFree).toBe(true)
+    expect(e.unknown).toBe(false)
+    expect(e.limit).toBe(3)
+  })
+
+  it('treats a subscription with no offer as free', () => {
+    const sub = { ...makeSub(), offer: null as unknown as ProductOffer }
+    expect(resolvePlanEntitlement(sub, opts).isFree).toBe(true)
+  })
+
+  const deadStatuses = ['past_due', 'cancelled', 'unpaid', 'trial_expired'] as const
+  for (const status of deadStatuses) {
+    it(`treats status=${status} on a paid offer as NOT paid`, () => {
+      const e = resolvePlanEntitlement(makeSub({ status, offer: proOffer }), opts)
+      expect(e.isPaid).toBe(false)
+      expect(e.isFree).toBe(true)
+      expect(e.limit).toBe(3)
+    })
+  }
+
+  it('falls back to freeFallbackLimit when a free offer declares no allowance', () => {
+    const bare = makeOffer({ isFree: true, features: [] })
+    expect(resolvePlanEntitlement(makeSub({ offer: bare }), opts).limit).toBe(3)
+  })
+
+  it('reads the allowance from the offer rather than the fallback when both exist', () => {
+    const e = resolvePlanEntitlement(makeSub({ offer: freeOffer }), {
+      ...opts,
+      freeFallbackLimit: 5,
+    })
+    expect(e.limit).toBe(3)
+  })
+
+  it('has a hasFeature() that gates a named Pro capability', () => {
+    const pro = resolvePlanEntitlement(makeSub({ offer: proOffer }), opts)
+    const free = resolvePlanEntitlement(makeSub({ offer: freeOffer }), opts)
+    expect(pro.hasFeature('pdf_export')).toBe(true)
+    expect(free.hasFeature('pdf_export')).toBe(false)
+  })
+
+  it('hasFeature() is false while unknown (fail closed)', () => {
+    const e = resolvePlanEntitlement(null, { ...opts, error: new Error('boom') })
+    expect(e.hasFeature('pdf_export')).toBe(false)
+  })
+})
+
+describe('resolveUsageWindow', () => {
+  const now = new Date('2026-09-18T12:00:00.000Z')
+
+  it('uses the calendar month when the subscription has no period bounds', () => {
+    const w = resolveUsageWindow(null, now)
+    expect(w.start.toISOString()).toBe('2026-09-01T00:00:00.000Z')
+    expect(w.end.toISOString()).toBe('2026-10-01T00:00:00.000Z')
+  })
+
+  it('IGNORES a frozen free-subscription period that never rolls', () => {
+    // SubscribeFreeViewSet writes current_period_start=now, end=None at signup
+    // and never updates it. Counting from that start is "count patterns ever"
+    // wearing a different hat — the exact bug startsim-ol36d.12 names.
+    const frozen = makeSub({
+      currentPeriodStart: '2026-03-04T09:00:00.000Z',
+      currentPeriodEnd: null,
+    })
+    const w = resolveUsageWindow(frozen, now)
+    expect(w.start.toISOString()).toBe('2026-09-01T00:00:00.000Z')
+  })
+
+  it('ignores a period whose end is already in the past', () => {
+    const stale = makeSub({
+      currentPeriodStart: '2026-07-01T00:00:00.000Z',
+      currentPeriodEnd: '2026-08-01T00:00:00.000Z',
+    })
+    expect(resolveUsageWindow(stale, now).start.toISOString()).toBe('2026-09-01T00:00:00.000Z')
+  })
+
+  it('uses a real, current billing period when both bounds are present', () => {
+    const real = makeSub({
+      currentPeriodStart: '2026-09-04T09:00:00.000Z',
+      currentPeriodEnd: '2026-10-04T09:00:00.000Z',
+    })
+    const w = resolveUsageWindow(real, now)
+    expect(w.start.toISOString()).toBe('2026-09-04T09:00:00.000Z')
+    expect(w.end.toISOString()).toBe('2026-10-04T09:00:00.000Z')
+  })
+
+  it('falls back to the calendar month on an unparseable period start', () => {
+    const bad = makeSub({ currentPeriodStart: 'not-a-date', currentPeriodEnd: 'also-bad' })
+    expect(resolveUsageWindow(bad, now).start.toISOString()).toBe('2026-09-01T00:00:00.000Z')
+  })
+
+  it('rolls into the next calendar month at the boundary', () => {
+    const w = resolveUsageWindow(null, new Date('2026-12-31T23:59:59.000Z'))
+    expect(w.start.toISOString()).toBe('2026-12-01T00:00:00.000Z')
+    expect(w.end.toISOString()).toBe('2027-01-01T00:00:00.000Z')
+  })
+})

package/src/utils/plan.ts

@@ -7,7 +7,7 @@
  * they don't.
  */
 
-import type { SubscriptionInfo } from "../types";
+import type { OfferFeature, ProductOffer, SubscriptionInfo } from "../types";
 
 const PAID_STATUSES: ReadonlyArray<SubscriptionInfo["status"]> = ["active", "trialing"];
 
@@ -28,3 +28,176 @@ export function isPaidSubscription(
   if (sub.offer.isFree) return false;
   return PAID_STATUSES.includes(sub.status);
 }
+
+/**
+ * Read a numeric allowance out of an offer's declared features.
+ *
+ * `keys` is tried in order so an app can accept an alias
+ * (e.g. `patterns_per_month` or `monthly_generations`).
+ *
+ * Returns `Infinity` for an explicit unlimited marker (`-1` or `"unlimited"`),
+ * and `null` when the offer declares no such allowance — which is NOT the same
+ * as zero, and callers must decide what an undeclared allowance means for them.
+ *
+ * `limit` wins over `value`: the backend puts the enforceable number in
+ * `limit` and uses `value` for display, and they can disagree.
+ */
+export function getFeatureLimit(
+  offer: ProductOffer | null | undefined,
+  keys: readonly string[]
+): number | null {
+  if (!offer) return null;
+  const features: OfferFeature[] = offer.features ?? [];
+  for (const key of keys) {
+    const feature = features.find((f) => f?.key === key);
+    if (!feature) continue;
+    const raw = feature.limit ?? feature.value;
+    if (raw === -1 || raw === "unlimited") return Infinity;
+    if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) return raw;
+  }
+  return null;
+}
+
+export interface PlanEntitlement {
+  /**
+   * True when the user is on a free plan — or when we could not prove they
+   * are not. Gates read this, so it fails CLOSED: the worst case is showing
+   * an upgrade prompt to someone who has already paid, which is recoverable.
+   * The opposite mistake hands Pro away during a billing outage.
+   */
+  isFree: boolean;
+  /** True only when an active or trialing PAID subscription is proven. */
+  isPaid: boolean;
+  /** The allowance for the metered feature. `Infinity` when unlimited. */
+  limit: number;
+  isUnlimited: boolean;
+  /**
+   * True when billing could not be resolved (still loading, or the call
+   * failed), so `isFree` is a fail-closed assumption rather than a fact.
+   * Use it to soften the copy ("checking your plan…"), never to open a gate.
+   */
+  unknown: boolean;
+  /**
+   * True when the plan's offer explicitly declares the named capability.
+   * Always false while `unknown`.
+   */
+  hasFeature: (key: string) => boolean;
+}
+
+export interface ResolvePlanEntitlementOptions {
+  /** Feature keys to read the metered allowance from, in priority order. */
+  featureKeys?: readonly string[];
+  /**
+   * Allowance to assume for a free user whose offer declares none — e.g. a
+   * user with no subscription row at all, who therefore has no offer to read.
+   */
+  freeFallbackLimit?: number;
+  /** Billing is still in flight. */
+  loading?: boolean;
+  /** The billing call failed. */
+  error?: unknown;
+}
+
+/**
+ * Derive what a subscription actually entitles someone to.
+ *
+ * This exists because the same three-line derivation was copied into every
+ * gate, and each copy got it wrong in a different way: testing
+ * `offer.slug === 'free'` when the real slug is `crochet-free`, testing
+ * `status === 'active'` so a paid trial counted as free, and treating a
+ * billing error as proof of a paid plan.
+ */
+export function resolvePlanEntitlement(
+  sub: SubscriptionInfo | null | undefined,
+  options: ResolvePlanEntitlementOptions = {}
+): PlanEntitlement {
+  const {
+    featureKeys = [],
+    freeFallbackLimit = Infinity,
+    loading = false,
+    error = null,
+  } = options;
+
+  // Unresolved billing is not evidence of a paid plan.
+  if (loading || error) {
+    return {
+      isFree: true,
+      isPaid: false,
+      limit: freeFallbackLimit,
+      isUnlimited: freeFallbackLimit === Infinity,
+      unknown: true,
+      hasFeature: () => false,
+    };
+  }
+
+  const offer = sub?.offer ?? null;
+  const paid = isPaidSubscription(sub);
+  const declared = getFeatureLimit(offer, featureKeys);
+
+  // An offer's allowance only counts while that offer is actually in force.
+  // A paid plan with no declared ceiling is unlimited; a free plan falls back
+  // to what the caller says free means. A LAPSED paid plan (cancelled,
+  // past_due, unpaid, expired trial) must not keep spending its old ceiling —
+  // it drops to the free allowance like anyone else.
+  let limit: number;
+  if (paid) {
+    limit = declared ?? Infinity;
+  } else if (offer?.isFree) {
+    limit = declared ?? freeFallbackLimit;
+  } else {
+    limit = freeFallbackLimit;
+  }
+
+  return {
+    isFree: !paid,
+    isPaid: paid,
+    limit,
+    isUnlimited: limit === Infinity,
+    unknown: false,
+    hasFeature: (key: string) =>
+      (offer?.features ?? []).some((f) => f?.key === key && f.value !== false),
+  };
+}
+
+export interface UsageWindow {
+  start: Date;
+  end: Date;
+}
+
+function startOfUtcMonth(d: Date): Date {
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1));
+}
+
+function parse(value: string | null | undefined): Date | null {
+  if (!value) return null;
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * The window a per-period allowance should be counted over.
+ *
+ * Prefers the subscription's real billing period, but only when BOTH bounds
+ * are present and the period has not already ended. Free subscriptions are
+ * created with `current_period_start = now` and `current_period_end = NULL`
+ * and are never rolled forward, so trusting that start would count every
+ * pattern the user has ever made — which is the bug this replaces, not a fix
+ * for it. Everything else falls back to the calendar month.
+ */
+export function resolveUsageWindow(
+  sub: SubscriptionInfo | null | undefined,
+  now: Date = new Date()
+): UsageWindow {
+  const start = parse(sub?.currentPeriodStart);
+  const end = parse(sub?.currentPeriodEnd);
+
+  if (start && end && end.getTime() > now.getTime() && start.getTime() <= now.getTime()) {
+    return { start, end };
+  }
+
+  const monthStart = startOfUtcMonth(now);
+  const monthEnd = new Date(
+    Date.UTC(monthStart.getUTCFullYear(), monthStart.getUTCMonth() + 1, 1)
+  );
+  return { start: monthStart, end: monthEnd };
+}

package/src/utils/tiers.ts

@@ -0,0 +1,55 @@
+/**
+ * How plan tiers relate to each other.
+ *
+ * Shared by the pricing cards and the comparison table so both read the offer
+ * data the same way — they disagreed before, and the table was the one that
+ * showed a paid plan as missing what the free plan had.
+ */
+import type { ProductOffer, OfferFeature } from "../types";
+/**
+ * Plans are cumulative: a paid tier includes what the cheaper tier includes.
+ *
+ * Offer data in the wild only lists what a tier ADDS — crochet-pro declares its
+ * advanced features and omits the "Save patterns" that crochet-free declares.
+ * Rendering that omission as "not included" put a dash on the paid plan exactly
+ * where the free plan had a tick, so the expensive plan looked WORSE.
+ *
+ * So a capability (`value === true`) established by a cheaper tier carries up
+ * into dearer ones. Two things deliberately do not carry:
+ *  - an explicit `false`, which is how a tier opts out and stops the carry; and
+ *  - numbers and strings, because an allowance is not a capability. Inheriting
+ *    the free plan's "3 patterns" onto Pro would state something untrue; a tier
+ *    has to declare its own allowance or say nothing.
+ */
+export function cumulativeFeatureLookup(
+  offers: ProductOffer[],
+): Record<string, Record<string, OfferFeature>> {
+  const cheapestFirst = [...offers].sort((a, b) => a.sortOrder - b.sortOrder);
+  const lookup: Record<string, Record<string, OfferFeature>> = {};
+  const carried: Record<string, OfferFeature> = {};
+
+  for (const offer of cheapestFirst) {
+    const own: Record<string, OfferFeature> = {};
+    for (const feature of offer.features) own[feature.key] = feature;
+
+    // Own declarations always win over anything inherited.
+    lookup[offer.slug] = { ...carried, ...own };
+
+    for (const feature of offer.features) {
+      if (feature.value === true) carried[feature.key] = feature;
+      // Anything else ends the run, so a tier that opts out does not have the
+      // capability silently handed back to the tier above it.
+      else delete carried[feature.key];
+    }
+  }
+
+  return lookup;
+}
+
+/** The tier immediately below each offer, for the "Everything in X" line. */
+export function tierBelow(offers: ProductOffer[], offer: ProductOffer): ProductOffer | null {
+  const cheapestFirst = [...offers].sort((a, b) => a.sortOrder - b.sortOrder);
+  const index = cheapestFirst.findIndex((o) => o.slug === offer.slug);
+  const below = index > 0 ? cheapestFirst[index - 1] : null;
+  return below && below.features.length > 0 ? below : null;
+}