@growth-labs/cms 0.5.24 → 0.5.26

package/src/integration/options.ts

@@ -41,6 +41,13 @@ export const cmsIntegrationOptionsSchema = z
 		activeWorkspaceId: z.string().optional(),
 		adminBasePath: z.string().default('/admin'),
 		searchEnabled: z.boolean().default(true),
+		// Drops @puckeditor/core's lazily imported RichTextRender chunk (tiptap +
+		// prosemirror, ~176KB gzip) from SSR/worker bundles. Safe because the
+		// createPuckConfig component library never declares a `richtext` field —
+		// RichText blocks store Portable Text and render via renderRichTextHtml.
+		// Disable only if a host site adds its own `richtext`-typed Puck field to
+		// a server-rendered config.
+		stubPuckSsrRichtext: z.boolean().default(true),
 		theme: themeSchema,
 		socialSharing: socialSharingSchema,
 		surveyResults: surveyResultsSchema.optional(),

package/src/integration/vite-plugin.ts

@@ -4,6 +4,39 @@ import type { ResolvedCmsIntegrationOptions } from './options.js'
 const VIRTUAL_MODULE_ID = 'virtual:growth-labs/cms/config'
 const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`
 
+export const PUCK_SSR_RICHTEXT_STUB_ID = '\0growth-labs/cms/puck-ssr-richtext-stub'
+
+// @puckeditor/core's rsc entry wires `lazy(() => import('./Render-<hash>.mjs'))`
+// for `richtext`-typed fields, so every SSR bundle that renders <Render> ships
+// the whole tiptap/prosemirror editor even though createPuckConfig never
+// declares such a field (RichText blocks store Portable Text; see
+// src/puck/config.tsx). Stubbing the dynamic import at resolve time lets
+// Rollup drop that dead subtree from worker bundles. Client builds are left
+// alone: the admin editor legitimately code-splits the same chunk.
+export function growthLabsPuckSsrRichtextStubPlugin(): Plugin {
+	return {
+		name: 'growth-labs-cms-puck-ssr-richtext-stub',
+		enforce: 'pre',
+		resolveId(source, importer, options) {
+			if (!options?.ssr) return undefined
+			if (!importer || !/@puckeditor[\\/]core[\\/]dist[\\/]/.test(importer)) return undefined
+			if (!/^\.\/Render-[\w-]+\.mjs$/.test(source)) return undefined
+			return PUCK_SSR_RICHTEXT_STUB_ID
+		},
+		load(id) {
+			if (id !== PUCK_SSR_RICHTEXT_STUB_ID) return undefined
+			// A loud marker, same convention as data-pt-unknown / gl-layout-unknown:
+			// if a host ever server-renders a real `richtext` field with the stub
+			// active, the gap is visible and greppable instead of silent.
+			return [
+				"import { jsx } from 'react/jsx-runtime'",
+				'export const RichTextRender = () =>',
+				"\tjsx('div', { 'data-gl-layout-unknown': 'puck-richtext-ssr-stubbed' })",
+			].join('\n')
+		},
+	}
+}
+
 export function growthLabsCmsPlugin(config: ResolvedCmsIntegrationOptions): Plugin {
 	const needsTransform = config.adminBasePath !== '/admin'
 	const replacePath = `${config.adminBasePath}/api`

package/src/providers/null.ts

@@ -59,6 +59,14 @@ export const nullAnalytics: AnalyticsProvider = {
 			},
 			readsTimeSeries: [],
 			sources: [],
+			funnel: {
+				views: null,
+				uniqueVisitors: null,
+				readCompletionRate: null,
+				paywallShown: null,
+				subscribeClicks: null,
+				boundaryConversionRate: null,
+			},
 		})
 	},
 }

package/src/providers/types.ts

@@ -5,6 +5,13 @@ export type ProviderStatus = 'live' | 'partial' | 'empty'
 export interface ProviderResult<T> {
 	status: ProviderStatus
 	data: T
+	/**
+	 * Optional per-key data lineage: where each number in `data` comes from
+	 * (e.g. `{ subscriptionsStarted: 'billing (site D1)', reads: 'rollup' }`).
+	 * The UI shows these so a reader never has to guess whether a figure is
+	 * ground truth or a derived rollup.
+	 */
+	sources?: Record<string, string>
 }
 
 export interface DateRange {
@@ -23,6 +30,24 @@ export interface ArticleAnalyticsSource {
 	paidStarts: number
 }
 
+/**
+ * Per-article free/premium boundary funnel. Every stage is `number | null`:
+ * null means NOT MEASURED for this article/range (event not instrumented,
+ * history predates slug attribution, or the fact table has no rows) and the
+ * UI must say so — never render a silent zero.
+ */
+export interface ArticleFunnelStages {
+	views: number | null
+	uniqueVisitors: number | null
+	/** 0..1 fraction of views that reached the 90% scroll mark. */
+	readCompletionRate: number | null
+	paywallShown: number | null
+	/** Boundary clicks: paywall CTA + inline membership CTA, per article. */
+	subscribeClicks: number | null
+	/** subscribeClicks / paywallShown (or the host's documented equivalent). */
+	boundaryConversionRate: number | null
+}
+
 export interface ArticleAnalyticsDetail {
 	id: string
 	slug: string
@@ -61,10 +86,11 @@ export interface ArticleAnalyticsDetail {
 	}
 	readsTimeSeries: Array<{ t: number; reads: number }>
 	sources: ArticleAnalyticsSource[]
+	funnel?: ArticleFunnelStages
 }
 
 export interface AnalyticsProvider {
-	getKpis(range: DateRange): Promise<ProviderResult<Record<string, number>>>
+	getKpis(range: DateRange): Promise<ProviderResult<Record<string, number | null>>>
 	getReadsTimeSeries(range: DateRange): Promise<ProviderResult<Array<{ t: number; reads: number }>>>
 	getTopContent(
 		range: DateRange,

package/src/ui/editor/boundary-marks.ts

@@ -0,0 +1,116 @@
+// Pure JSONContent boundary-mark normalization. Split from
+// trim-boundary-marks.ts so server-safe consumers (serialize.ts,
+// portable-text.ts, and through them the @growth-labs/cms/puck subpath) can
+// use it without dragging the Tiptap/ProseMirror runtime into SSR bundles —
+// the live-editor Extension stays in trim-boundary-marks.ts.
+import type { JSONContent } from '@tiptap/core'
+
+export const BOUNDARY_MARKS = ['link'] as const
+
+function markKey(mark: NonNullable<JSONContent['marks']>[number]): string {
+	return `${mark.type}:${JSON.stringify(mark.attrs ?? {})}`
+}
+
+function sameMarks(
+	a: JSONContent['marks'] | undefined,
+	b: JSONContent['marks'] | undefined,
+): boolean {
+	return JSON.stringify(a ?? []) === JSON.stringify(b ?? [])
+}
+
+function mergeAdjacentText(nodes: JSONContent[]): JSONContent[] {
+	const merged: JSONContent[] = []
+	for (const node of nodes) {
+		const previous = merged.at(-1)
+		if (
+			previous?.type === 'text' &&
+			node.type === 'text' &&
+			sameMarks(previous.marks, node.marks)
+		) {
+			previous.text = (previous.text ?? '') + (node.text ?? '')
+		} else {
+			merged.push(node)
+		}
+	}
+	return merged
+}
+
+function trimJsonMark(nodes: JSONContent[], markType: (typeof BOUNDARY_MARKS)[number]) {
+	const output: JSONContent[] = []
+	let index = 0
+
+	while (index < nodes.length) {
+		const node = nodes[index]
+		const mark =
+			node.type === 'text'
+				? node.marks?.find((candidate) => candidate.type === markType)
+				: undefined
+		if (!mark) {
+			output.push(node)
+			index += 1
+			continue
+		}
+
+		const key = markKey(mark)
+		const run: JSONContent[] = []
+		while (index < nodes.length) {
+			const candidate = nodes[index]
+			const candidateMark =
+				candidate.type === 'text'
+					? candidate.marks?.find((item) => item.type === markType && markKey(item) === key)
+					: undefined
+			if (!candidateMark) break
+			run.push(candidate)
+			index += 1
+		}
+
+		const text = run.map((item) => item.text ?? '').join('')
+		const leading = text.match(/^\s+/u)?.[0].length ?? 0
+		const trailing = text.match(/\s+$/u)?.[0].length ?? 0
+		const markedEnd = Math.max(leading, text.length - trailing)
+		let offset = 0
+
+		for (const item of run) {
+			const itemText = item.text ?? ''
+			const itemStart = offset
+			const itemEnd = offset + itemText.length
+			const cuts = [itemStart, Math.max(itemStart, leading), Math.min(itemEnd, markedEnd), itemEnd]
+				.filter(
+					(value, cutIndex, all) =>
+						value >= itemStart && value <= itemEnd && all.indexOf(value) === cutIndex,
+				)
+				.sort((a, b) => a - b)
+
+			for (let cutIndex = 0; cutIndex < cuts.length - 1; cutIndex += 1) {
+				const from = cuts[cutIndex]
+				const to = cuts[cutIndex + 1]
+				if (from === to) continue
+				const keepMark = from >= leading && to <= markedEnd
+				const marks = keepMark
+					? item.marks
+					: item.marks?.filter((candidate) => candidate.type !== markType)
+				output.push({
+					...item,
+					text: itemText.slice(from - itemStart, to - itemStart),
+					...(marks?.length ? { marks } : { marks: undefined }),
+				})
+			}
+			offset = itemEnd
+		}
+	}
+
+	return mergeAdjacentText(output)
+}
+
+/**
+ * Remove link and underline marks from leading/trailing whitespace in every
+ * inline mark run. Underline follows the same rule as links: whitespace is
+ * layout, not editorial emphasis, and pasted underline is the visible half of
+ * the malformed-link report.
+ */
+export function normalizeBoundaryMarks(node: JSONContent): JSONContent {
+	if (!node.content) return node
+	let content = node.content.map(normalizeBoundaryMarks)
+	for (const markType of BOUNDARY_MARKS) content = trimJsonMark(content, markType)
+	return { ...node, content }
+}

package/src/ui/editor/portable-text.ts

@@ -19,7 +19,7 @@
 
 import type { JSONContent } from '@tiptap/core'
 import type { PortableTextObject } from '../../schema/portable-text.js'
-import { normalizeBoundaryMarks } from './trim-boundary-marks.js'
+import { normalizeBoundaryMarks } from './boundary-marks.js'
 
 type KeyGenerator = () => string
 

package/src/ui/editor/serialize.ts

@@ -29,7 +29,7 @@
 //   (inner markdown re-serializes byte-identically)
 
 import type { JSONContent } from '@tiptap/core'
-import { normalizeBoundaryMarks } from './trim-boundary-marks.js'
+import { normalizeBoundaryMarks } from './boundary-marks.js'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // docToMarkdown — JSONContent → string

package/src/ui/editor/trim-boundary-marks.ts

@@ -1,116 +1,11 @@
-import { Extension, type JSONContent } from '@tiptap/core'
+import { Extension } from '@tiptap/core'
 import type { Mark, MarkType, Node as ProseMirrorNode } from '@tiptap/pm/model'
 import { Plugin } from '@tiptap/pm/state'
+import { BOUNDARY_MARKS, normalizeBoundaryMarks } from './boundary-marks.js'
 
-const BOUNDARY_MARKS = ['link'] as const
-
-function markKey(mark: NonNullable<JSONContent['marks']>[number]): string {
-	return `${mark.type}:${JSON.stringify(mark.attrs ?? {})}`
-}
-
-function sameMarks(
-	a: JSONContent['marks'] | undefined,
-	b: JSONContent['marks'] | undefined,
-): boolean {
-	return JSON.stringify(a ?? []) === JSON.stringify(b ?? [])
-}
-
-function mergeAdjacentText(nodes: JSONContent[]): JSONContent[] {
-	const merged: JSONContent[] = []
-	for (const node of nodes) {
-		const previous = merged.at(-1)
-		if (
-			previous?.type === 'text' &&
-			node.type === 'text' &&
-			sameMarks(previous.marks, node.marks)
-		) {
-			previous.text = (previous.text ?? '') + (node.text ?? '')
-		} else {
-			merged.push(node)
-		}
-	}
-	return merged
-}
-
-function trimJsonMark(nodes: JSONContent[], markType: (typeof BOUNDARY_MARKS)[number]) {
-	const output: JSONContent[] = []
-	let index = 0
-
-	while (index < nodes.length) {
-		const node = nodes[index]
-		const mark =
-			node.type === 'text'
-				? node.marks?.find((candidate) => candidate.type === markType)
-				: undefined
-		if (!mark) {
-			output.push(node)
-			index += 1
-			continue
-		}
-
-		const key = markKey(mark)
-		const run: JSONContent[] = []
-		while (index < nodes.length) {
-			const candidate = nodes[index]
-			const candidateMark =
-				candidate.type === 'text'
-					? candidate.marks?.find((item) => item.type === markType && markKey(item) === key)
-					: undefined
-			if (!candidateMark) break
-			run.push(candidate)
-			index += 1
-		}
-
-		const text = run.map((item) => item.text ?? '').join('')
-		const leading = text.match(/^\s+/u)?.[0].length ?? 0
-		const trailing = text.match(/\s+$/u)?.[0].length ?? 0
-		const markedEnd = Math.max(leading, text.length - trailing)
-		let offset = 0
-
-		for (const item of run) {
-			const itemText = item.text ?? ''
-			const itemStart = offset
-			const itemEnd = offset + itemText.length
-			const cuts = [itemStart, Math.max(itemStart, leading), Math.min(itemEnd, markedEnd), itemEnd]
-				.filter(
-					(value, cutIndex, all) =>
-						value >= itemStart && value <= itemEnd && all.indexOf(value) === cutIndex,
-				)
-				.sort((a, b) => a - b)
-
-			for (let cutIndex = 0; cutIndex < cuts.length - 1; cutIndex += 1) {
-				const from = cuts[cutIndex]
-				const to = cuts[cutIndex + 1]
-				if (from === to) continue
-				const keepMark = from >= leading && to <= markedEnd
-				const marks = keepMark
-					? item.marks
-					: item.marks?.filter((candidate) => candidate.type !== markType)
-				output.push({
-					...item,
-					text: itemText.slice(from - itemStart, to - itemStart),
-					...(marks?.length ? { marks } : { marks: undefined }),
-				})
-			}
-			offset = itemEnd
-		}
-	}
-
-	return mergeAdjacentText(output)
-}
-
-/**
- * Remove link and underline marks from leading/trailing whitespace in every
- * inline mark run. Underline follows the same rule as links: whitespace is
- * layout, not editorial emphasis, and pasted underline is the visible half of
- * the malformed-link report.
- */
-export function normalizeBoundaryMarks(node: JSONContent): JSONContent {
-	if (!node.content) return node
-	let content = node.content.map(normalizeBoundaryMarks)
-	for (const markType of BOUNDARY_MARKS) content = trimJsonMark(content, markType)
-	return { ...node, content }
-}
+// Server-safe callers import normalizeBoundaryMarks from ./boundary-marks.js
+// directly; this re-export keeps the historical editor-side import path alive.
+export { normalizeBoundaryMarks }
 
 function matchingMark(
 	node: ProseMirrorNode,

package/src/ui/screens/AnalyticsScreen.tsx

@@ -21,7 +21,11 @@
 // a .card-title + .masthead-rule hairline. NO BData, NO mock numbers.
 
 import { useCallback, useEffect, useReducer, useState } from 'react'
-import type { ArticleAnalyticsDetail, ProviderResult } from '../../providers/types.js'
+import type {
+	ArticleAnalyticsDetail,
+	ArticleFunnelStages,
+	ProviderResult,
+} from '../../providers/types.js'
 import { Icon } from '../icons.js'
 import {
 	type AnalyticsData,
@@ -358,6 +362,8 @@ function ArticleAnalyticsDetailBody({
 				/>
 			</div>
 
+			<ArticleFunnelPanel funnel={detail.funnel} />
+
 			<div className="grid-split-wide">
 				<ReadsChart series={readsResult} />
 				<ScrollDepthPanel detail={detail} />
@@ -368,6 +374,63 @@ function ArticleAnalyticsDetailBody({
 	)
 }
 
+// ---------------------------------------------------------------------------
+// ArticleFunnelPanel — the free/premium boundary, per article
+// ---------------------------------------------------------------------------
+// Each stage is number | null; null renders an explicit "not measured", never
+// a silent zero (unmeasured history and uninstrumented events must look
+// different from a genuinely quiet article).
+
+const FUNNEL_STAGE_DEFS: Array<{
+	key: keyof ArticleFunnelStages & string
+	label: string
+	fmt: 'num' | 'pct'
+}> = [
+	{ key: 'views', label: 'Views', fmt: 'num' },
+	{ key: 'uniqueVisitors', label: 'Unique visitors', fmt: 'num' },
+	{ key: 'readCompletionRate', label: 'Read completion', fmt: 'pct' },
+	{ key: 'paywallShown', label: 'Boundary shown', fmt: 'num' },
+	{ key: 'subscribeClicks', label: 'Boundary clicks', fmt: 'num' },
+	{ key: 'boundaryConversionRate', label: 'Boundary conversion', fmt: 'pct' },
+]
+
+export function ArticleFunnelPanel({ funnel }: { funnel: ArticleFunnelStages | undefined }) {
+	return (
+		<div className="panel panel-pad">
+			<div className="kicker" style={{ marginBottom: 10 }}>
+				Conversion funnel
+			</div>
+			<div className="grid-stats">
+				{FUNNEL_STAGE_DEFS.map((stage) => {
+					const raw = funnel?.[stage.key] ?? null
+					const measured = typeof raw === 'number' && Number.isFinite(raw)
+					return (
+						<div key={stage.key}>
+							<div style={{ fontSize: 11, color: 'var(--ink-muted)' }}>{stage.label}</div>
+							<div
+								className="serif tnum"
+								style={{ fontSize: 22, fontWeight: 600, color: 'var(--ink)', margin: '4px 0 2px' }}
+							>
+								{measured ? (
+									stage.fmt === 'pct' ? (
+										formatPercent(raw)
+									) : (
+										formatNumber(raw)
+									)
+								) : (
+									<span style={{ fontSize: 13, color: 'var(--ink-faint)', fontStyle: 'italic' }}>
+										not measured
+									</span>
+								)}
+							</div>
+						</div>
+					)
+				})}
+			</div>
+		</div>
+	)
+}
+
 function ScrollDepthPanel({ detail }: { detail: ArticleAnalyticsDetail }) {
 	const rows = [
 		{ label: '25%', count: detail.scrollDepth.scroll25, rate: detail.scrollDepth.scroll25Rate },
@@ -520,7 +583,7 @@ function AnalyticsBody({ data, isPartial }: { data: AnalyticsData; isPartial: bo
 	return (
 		<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--gap)' }}>
 			{isPartial && (
-				<PartialBanner message="Showing reads only — full metrics arrive with the analytics rollup." />
+				<PartialBanner message="Some metrics are unavailable for this range — each tile shows its own state and source." />
 			)}
 
 			{/* KPI cards */}
@@ -561,6 +624,12 @@ const KPI_DEFS: Array<{
 		fmt: 'num',
 		emptyNote: 'No visitor data',
 	},
+	{
+		key: 'subscriptionsStarted',
+		label: 'New subscriptions',
+		fmt: 'num',
+		emptyNote: 'No subscription data',
+	},
 	{
 		key: 'conversionRate',
 		label: 'Conversion',
@@ -569,7 +638,7 @@ const KPI_DEFS: Array<{
 	},
 ]
 
-function KpiCards({ kpis }: { kpis: ProviderResult<Record<string, number | null>> }) {
+export function KpiCards({ kpis }: { kpis: ProviderResult<Record<string, number | null>> }) {
 	const kpiStatus = selectKpiState(kpis)
 
 	if (kpiStatus === 'empty') {
@@ -586,19 +655,22 @@ function KpiCards({ kpis }: { kpis: ProviderResult<Record<string, number | null>
 			{KPI_DEFS.map((def) => {
 				const raw = kpis.data?.[def.key] ?? null
 				const formatted = formatKpi(raw, def.fmt)
-				const isPending =
+				const isUnmeasured =
 					formatted !== null && typeof formatted === 'object' && (formatted as KpiPending).pending
 
-				const displayValue = isPending ? null : (formatted as string)
-				const displayNote = isPending ? '— pending backfill' : null
+				const displayValue = isUnmeasured ? null : (formatted as string)
+				// A null KPI is an honest gap — the provider could not measure it
+				// for this range — not a promise that a backfill will fill it.
+				const displayNote = isUnmeasured ? 'not measured' : null
 
 				return (
 					<KpiCard
 						key={def.key}
 						label={def.label}
-						status={isPending ? 'partial' : kpiStatus}
+						status={isUnmeasured ? 'partial' : kpiStatus}
 						value={displayValue}
 						note={displayNote}
+						source={kpis.sources?.[def.key] ?? null}
 					/>
 				)
 			})}
@@ -611,11 +683,13 @@ function KpiCard({
 	status,
 	value,
 	note,
+	source,
 }: {
 	label: string
 	status: 'live' | 'partial' | 'empty'
 	value: string | null
 	note: string | null
+	source?: string | null
 }) {
 	const empty = status === 'empty' || value === null
 	return (
@@ -631,6 +705,11 @@ function KpiCard({
 			{status === 'partial' && !note && (
 				<span style={{ fontSize: 11, fontWeight: 600, color: 'var(--amber)' }}>partial</span>
 			)}
+			{source && (
+				<div style={{ fontSize: 10, color: 'var(--ink-faint)', marginTop: 4 }} title="Data source">
+					{source}
+				</div>
+			)}
 		</div>
 	)
 }

package/src/ui/screens/analytics-data.ts

@@ -24,14 +24,28 @@ function providerStatus(value: unknown): ProviderStatus {
 	return value === 'live' || value === 'partial' || value === 'empty' ? value : 'empty'
 }
 
+function normalizeSources(value: unknown): Record<string, string> | undefined {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+	const out: Record<string, string> = {}
+	for (const [key, label] of Object.entries(value as Record<string, unknown>)) {
+		if (typeof label === 'string' && label.length > 0) out[key] = label
+	}
+	return Object.keys(out).length > 0 ? out : undefined
+}
+
 function normalizeObjectResult(result: unknown): ProviderResult<Record<string, number | null>> {
 	if (!result || typeof result !== 'object') return { status: 'empty', data: {} }
-	const record = result as { status?: unknown; data?: unknown }
+	const record = result as { status?: unknown; data?: unknown; sources?: unknown }
 	const data =
 		record.data && typeof record.data === 'object' && !Array.isArray(record.data)
 			? (record.data as Record<string, number | null>)
 			: {}
-	return { status: providerStatus(record.status), data }
+	const sources = normalizeSources(record.sources)
+	return {
+		status: providerStatus(record.status),
+		data,
+		...(sources ? { sources } : {}),
+	}
 }
 
 function normalizeArrayResult<T>(result: unknown): ProviderResult<T[]> {