@growth-labs/cms 0.5.20 → 0.5.22

package/src/puck/config.tsx

@@ -0,0 +1,185 @@
+// src/puck/config.tsx
+// The cms-owned Puck component library (v1): the Config consumed by both the
+// admin editor (<Puck>) and the public renderer (<Render> from
+// @puckeditor/core/rsc). Every render function is server-safe — plain JSX,
+// no hooks, no DOM access — so the fronts Worker can render layouts with
+// zero client JS. @puckeditor/core itself is only a TYPE dependency here;
+// the runtime dependency lives with the consumer (optional peer).
+//
+// RichText stores a Portable Text envelope (schema/portable-text.ts) in its
+// props — NEVER Puck's built-in `richtext` field, whose /rsc render path
+// requires a DOM (@tiptap/html + happy-dom) and breaks on workerd. The HTML
+// projection is injected by the consumer so site render pipelines (sanitize,
+// heading ids, entity linking) stay site-owned.
+
+import type { Config } from '@puckeditor/core'
+import type { ReactNode } from 'react'
+
+export interface PuckConfigOptions {
+	/**
+	 * Portable Text envelope JSON → trusted HTML for RichText blocks. The
+	 * consumer owns this (fronts routes it through its article render
+	 * pipeline). Without it, RichText renders a loud inline marker instead of
+	 * silently dropping content.
+	 */
+	renderRichTextHtml?: (portableTextEnvelopeJson: string) => string
+}
+
+/** The v1 layout component set, in palette order. */
+export const LAYOUT_COMPONENT_TYPES = [
+	'Section',
+	'Heading',
+	'RichText',
+	'Image',
+	'CTAButton',
+	'Spacer',
+] as const
+
+export type LayoutComponentType = (typeof LAYOUT_COMPONENT_TYPES)[number]
+
+export function createPuckConfig(options: PuckConfigOptions = {}): Config {
+	const { renderRichTextHtml } = options
+	return {
+		components: {
+			Section: {
+				label: 'Section',
+				fields: {
+					width: {
+						type: 'select',
+						label: 'Width',
+						options: [
+							{ label: 'Normal', value: 'normal' },
+							{ label: 'Wide', value: 'wide' },
+						],
+					},
+					content: { type: 'slot' },
+				},
+				defaultProps: { width: 'normal', content: [] },
+				render: ({ width, content }) => (
+					<section className={`gl-layout-section gl-layout-section--${width || 'normal'}`}>
+						{typeof content === 'function' ? content() : null}
+					</section>
+				),
+			},
+			Heading: {
+				label: 'Heading',
+				fields: {
+					text: { type: 'text', label: 'Text', contentEditable: true },
+					level: {
+						type: 'select',
+						label: 'Level',
+						options: [
+							{ label: 'Heading 2', value: '2' },
+							{ label: 'Heading 3', value: '3' },
+						],
+					},
+				},
+				defaultProps: { text: '', level: '2' },
+				render: ({ text, level }) =>
+					level === '3' ? (
+						<h3 className="gl-layout-heading">{text}</h3>
+					) : (
+						<h2 className="gl-layout-heading">{text}</h2>
+					),
+			},
+			RichText: {
+				label: 'Rich text',
+				// Placeholder field until the Builder-mode editor lands its
+				// Portable Text custom field; the stored prop shape is final.
+				fields: {
+					portableText: { type: 'textarea', label: 'Portable Text envelope' },
+				},
+				defaultProps: { portableText: '' },
+				render: ({ portableText }) => {
+					const raw = typeof portableText === 'string' ? portableText : ''
+					if (renderRichTextHtml && raw !== '') {
+						return (
+							<div
+								className="gl-layout-richtext"
+								// biome-ignore lint/security/noDangerouslySetInnerHtml: the consumer-injected projection owns sanitization
+								dangerouslySetInnerHTML={{ __html: renderRichTextHtml(raw) }}
+							/>
+						)
+					}
+					// Loud, greppable marker — mirrors the fronts data-pt-unknown
+					// convention so a missing renderer never silently drops prose.
+					return (
+						<div
+							className="gl-layout-richtext"
+							data-gl-layout-unknown="richtext-renderer-missing"
+						/>
+					)
+				},
+			},
+			Image: {
+				label: 'Image',
+				fields: {
+					src: { type: 'text', label: 'Image URL' },
+					alt: { type: 'text', label: 'Alt text' },
+					caption: { type: 'text', label: 'Caption' },
+				},
+				defaultProps: { src: '', alt: '', caption: '' },
+				render: ({ src, alt, caption }) => (
+					<figure className="gl-layout-image">
+						{typeof src === 'string' && src !== '' ? (
+							<img src={src} alt={typeof alt === 'string' ? alt : ''} loading="lazy" />
+						) : null}
+						{typeof caption === 'string' && caption !== '' ? (
+							<figcaption>{caption}</figcaption>
+						) : null}
+					</figure>
+				),
+			},
+			CTAButton: {
+				label: 'CTA button',
+				fields: {
+					label: { type: 'text', label: 'Label', contentEditable: true },
+					href: { type: 'text', label: 'Link URL' },
+					tone: {
+						type: 'select',
+						label: 'Tone',
+						options: [
+							{ label: 'Primary', value: 'primary' },
+							{ label: 'Secondary', value: 'secondary' },
+						],
+					},
+				},
+				defaultProps: { label: '', href: '', tone: 'primary' },
+				render: ({ label, href, tone }) => (
+					<a
+						className={`gl-layout-cta gl-layout-cta--${tone || 'primary'}`}
+						href={typeof href === 'string' && href !== '' ? href : undefined}
+					>
+						{label}
+					</a>
+				),
+			},
+			Spacer: {
+				label: 'Spacer',
+				fields: {
+					size: {
+						type: 'select',
+						label: 'Size',
+						options: [
+							{ label: 'Small', value: 'sm' },
+							{ label: 'Medium', value: 'md' },
+							{ label: 'Large', value: 'lg' },
+						],
+					},
+				},
+				defaultProps: { size: 'md' },
+				render: ({ size }) => (
+					<div
+						className={`gl-layout-spacer gl-layout-spacer--${size || 'md'}`}
+						aria-hidden="true"
+					/>
+				),
+			},
+		},
+		root: {
+			// The page shell (nav, footer, prose width) belongs to the consumer;
+			// the layout root is deliberately chromeless.
+			render: ({ children }: { children?: ReactNode }) => <>{children}</>,
+		},
+	}
+}

package/src/puck/index.ts

@@ -0,0 +1,23 @@
+// src/puck/index.ts
+// The `@growth-labs/cms/puck` subpath: the page-builder component library
+// (Puck Config factory + server-safe React renders), the derived-markdown
+// projection, and the layout storage envelope contract. Consumers pair this
+// with @puckeditor/core (optional peer): the admin editor mounts <Puck>, the
+// public site renders with <Render> from @puckeditor/core/rsc.
+
+export {
+	LAYOUT_VERSION,
+	type LayoutComponent,
+	type LayoutData,
+	type LayoutEnvelope,
+	layoutEnvelopeSchema,
+	parseLayoutEnvelope,
+	wrapLayout,
+} from '../schema/layout.js'
+export {
+	createPuckConfig,
+	LAYOUT_COMPONENT_TYPES,
+	type LayoutComponentType,
+	type PuckConfigOptions,
+} from './config.js'
+export { layoutJsonToMarkdown, layoutToMarkdown } from './markdown.js'

package/src/puck/markdown.ts

@@ -0,0 +1,78 @@
+// src/puck/markdown.ts
+// Derived-markdown projection: turn a stored layout envelope back into a
+// classic body_markdown string. Builder-mode saves use this to keep
+// body_markdown populated (search, SEO extraction, non-layout surfaces) while
+// layout_json stays the source of truth for builder pages. The projection is
+// lossy by design — structural chrome (Section widths, Spacers) has no
+// markdown equivalent and is dropped.
+
+import { type LayoutComponent, type LayoutEnvelope, parseLayoutEnvelope } from '../schema/layout.js'
+import { parsePortableTextEnvelope } from '../schema/portable-text.js'
+import { portableTextToDoc } from '../ui/editor/portable-text.js'
+import { docToMarkdown } from '../ui/editor/serialize.js'
+
+export function layoutToMarkdown(envelope: LayoutEnvelope): string {
+	return componentsToMarkdown(envelope.data.content).join('\n\n')
+}
+
+/** Parse stored layout JSON and project it; null when the JSON is malformed. */
+export function layoutJsonToMarkdown(raw: unknown): string | null {
+	const envelope = parseLayoutEnvelope(raw)
+	if (!envelope) return null
+	return layoutToMarkdown(envelope)
+}
+
+function componentsToMarkdown(components: LayoutComponent[]): string[] {
+	const fragments: string[] = []
+	for (const component of components) {
+		for (const fragment of componentToMarkdown(component)) {
+			const trimmed = fragment.trim()
+			if (trimmed !== '') fragments.push(trimmed)
+		}
+	}
+	return fragments
+}
+
+function componentToMarkdown(component: LayoutComponent): string[] {
+	const props = component.props ?? {}
+	switch (component.type) {
+		case 'Heading': {
+			const text = typeof props.text === 'string' ? props.text.trim() : ''
+			if (text === '') return []
+			const level = props.level === '3' ? 3 : 2
+			return [`${'#'.repeat(level)} ${text}`]
+		}
+		case 'RichText': {
+			const parsed = parsePortableTextEnvelope(props.portableText)
+			if (!parsed) return []
+			return [docToMarkdown(portableTextToDoc(parsed.content))]
+		}
+		case 'Image': {
+			const src = typeof props.src === 'string' ? props.src.trim() : ''
+			if (src === '') return []
+			const alt = typeof props.alt === 'string' ? props.alt : ''
+			return [`![${alt}](${src})`]
+		}
+		case 'CTAButton': {
+			const label = typeof props.label === 'string' ? props.label.trim() : ''
+			const href = typeof props.href === 'string' ? props.href.trim() : ''
+			if (label === '' || href === '') return []
+			return [`[${label}](${href})`]
+		}
+		case 'Section': {
+			// Slot content is stored inline under the slot prop as
+			// { type, props }[] (Puck 0.23 slot fields; ids optional).
+			if (!Array.isArray(props.content)) return []
+			const nested = props.content.filter(
+				(entry): entry is LayoutComponent =>
+					typeof entry === 'object' &&
+					entry !== null &&
+					typeof (entry as LayoutComponent).type === 'string',
+			)
+			return componentsToMarkdown(nested)
+		}
+		default:
+			// Spacer and unknown/future types have no markdown projection.
+			return []
+	}
+}

package/src/routes/content.ts

@@ -52,6 +52,7 @@ import {
 import { applySlugRenameRedirects } from '../engine/slug-redirects.js'
 import { softDeleteContent } from '../engine/soft-delete.js'
 import { TagInputError } from '../engine/taxonomy.js'
+import { parseLayoutEnvelope } from '../schema/layout.js'
 import { parsePortableTextEnvelope } from '../schema/portable-text.js'
 import type { ContentStatus } from '../schema/types.js'
 import { type ContentAction, canPerformContentAction } from './authz-matrix.js'
@@ -258,10 +259,25 @@ const bodyPortableTextField = z
 	.optional()
 	.nullable()
 
+// Puck layout envelopes get the same boundary treatment.
+const layoutJsonField = z
+	.string()
+	.superRefine((value, ctx) => {
+		if (parseLayoutEnvelope(value) === null) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: 'layoutJson must be a valid layout envelope',
+			})
+		}
+	})
+	.optional()
+	.nullable()
+
 const BodyContentCreateSchema = z.object({
 	bodyMarkdown: z.string().min(1),
 	bodyHtml: z.string().optional().nullable(),
 	bodyPortableText: bodyPortableTextField,
+	layoutJson: layoutJsonField,
 	subtitle: z.string().optional().nullable(),
 	wordCount: z.number().int().optional().nullable(),
 	readTimeMinutes: z.number().int().optional().nullable(),
@@ -368,6 +384,7 @@ const ArticleContentUpdateSchema = z.object({
 	bodyMarkdown: z.string().optional(),
 	bodyHtml: z.string().optional().nullable(),
 	bodyPortableText: bodyPortableTextField,
+	layoutJson: layoutJsonField,
 	subtitle: z.string().optional().nullable(),
 	wordCount: z.number().int().optional().nullable(),
 	readTimeMinutes: z.number().int().optional().nullable(),
@@ -570,7 +587,7 @@ async function getContentPayload(ctx: RouteContext, type: string, id: string) {
 	if (type === 'article' || type === 'newsletter' || type === 'page') {
 		return ctx.db
 			.prepare(
-				`SELECT body_markdown, body_html, body_portable_text, word_count, read_time_minutes, subtitle,
+				`SELECT body_markdown, body_html, body_portable_text, layout_json, word_count, read_time_minutes, subtitle,
 					ai_takeaways, ai_takeaways_at, ai_takeaways_model, editor_takeaways,
 					ai_takeaways_correlation_id
 				FROM article_content WHERE content_id = ? LIMIT 1`,

package/src/schema/layout.ts

@@ -0,0 +1,73 @@
+// src/schema/layout.ts
+// The page-layout durable-store contract: envelope shape, version, and the
+// boundary validator. `article_content.layout_json` holds the envelope —
+// `{ version, data }` — where `data` is a Puck Data document (content array
+// of typed components, root props, optional zones). The internal adapter
+// (src/puck/) owns the Puck-specific semantics; this module only guarantees
+// the stored shape is structurally sound so malformed layouts fail loudly at
+// the boundary and renderers fall back to the classic body path.
+
+import { z } from 'zod'
+
+export const LAYOUT_VERSION = 1
+
+export interface LayoutComponent {
+	type: string
+	props?: Record<string, unknown>
+	[key: string]: unknown
+}
+
+export interface LayoutData {
+	content: LayoutComponent[]
+	root?: Record<string, unknown>
+	zones?: Record<string, LayoutComponent[]>
+	[key: string]: unknown
+}
+
+export interface LayoutEnvelope {
+	version: typeof LAYOUT_VERSION
+	data: LayoutData
+}
+
+const layoutComponentSchema = z
+	.object({
+		type: z.string().min(1),
+		props: z.record(z.string(), z.unknown()).optional(),
+	})
+	.passthrough()
+
+const layoutDataSchema = z
+	.object({
+		content: z.array(layoutComponentSchema),
+		root: z.record(z.string(), z.unknown()).optional(),
+		zones: z.record(z.string(), z.array(layoutComponentSchema)).optional(),
+	})
+	.passthrough()
+
+export const layoutEnvelopeSchema = z.object({
+	version: z.literal(LAYOUT_VERSION),
+	data: layoutDataSchema,
+})
+
+/** Wrap a Puck Data document in the versioned storage envelope. */
+export function wrapLayout(data: LayoutData): LayoutEnvelope {
+	return { version: LAYOUT_VERSION, data }
+}
+
+/**
+ * Parse stored layout JSON into a validated envelope. Returns null for
+ * anything malformed — absent value, bad JSON, wrong shape, unknown version —
+ * so callers fall back to the classic body render path.
+ */
+export function parseLayoutEnvelope(raw: unknown): LayoutEnvelope | null {
+	if (typeof raw !== 'string' || raw === '') return null
+	let decoded: unknown
+	try {
+		decoded = JSON.parse(raw)
+	} catch {
+		return null
+	}
+	const parsed = layoutEnvelopeSchema.safeParse(decoded)
+	if (!parsed.success) return null
+	return parsed.data as LayoutEnvelope
+}

package/src/schema/migrations.ts

@@ -834,6 +834,13 @@ ALTER TABLE article_content
   ADD COLUMN body_portable_text TEXT;
 	`,
 	},
+	{
+		id: '0025_page_layout_json',
+		sql: `
+ALTER TABLE article_content
+  ADD COLUMN layout_json TEXT;
+	`,
+	},
 ]
 
 /**

package/src/schema/types.ts

@@ -93,6 +93,8 @@ export interface ArticleContentRow {
 	body_html: string | null
 	/** Portable Text envelope JSON (migration 0024); NULL → render markdown. */
 	body_portable_text: string | null
+	/** Puck layout envelope JSON (migration 0025); NULL → classic page. */
+	layout_json: string | null
 	word_count: number | null
 	read_time_minutes: number | null
 	subtitle: string | null

package/src/ui/editor/serialize.ts

@@ -633,7 +633,13 @@ function parseInline(text: string): JSONContent[] {
 		}
 
 		// ── bold (**text** or __text__) ────────────────────────────────────
-		const boldMatch = /^\*\*([^*]+)\*\*/.exec(remaining) || /^__([^_]+)__/.exec(remaining)
+		const boldStarMatch = /^\*\*([^*]+)\*\*/.exec(remaining)
+		const boldUnderscoreMatch = boldStarMatch ? null : /^__([^_]+)__/.exec(remaining)
+		const boldMatch =
+			boldStarMatch ??
+			(boldUnderscoreMatch && !isIntrawordUnderscore(text, remaining, boldUnderscoreMatch)
+				? boldUnderscoreMatch
+				: null)
 		if (boldMatch) {
 			const inner = parseInlineWithMark(boldMatch[1], { type: 'bold' })
 			nodes.push(...inner)
@@ -656,7 +662,10 @@ function parseInline(text: string): JSONContent[] {
 		// underline mark, which round-tripped underline↔italic inconsistently
 		// and was the visible half of the Word-paste formatting incidents.
 		const underscoreEmphasisMatch = /^_([^_]+)_/.exec(remaining)
-		if (underscoreEmphasisMatch) {
+		if (
+			underscoreEmphasisMatch &&
+			!isIntrawordUnderscore(text, remaining, underscoreEmphasisMatch)
+		) {
 			const inner = parseInlineWithMark(underscoreEmphasisMatch[1], { type: 'italic' })
 			nodes.push(...inner)
 			remaining = remaining.slice(underscoreEmphasisMatch[0].length)
@@ -692,6 +701,19 @@ function parseInline(text: string): JSONContent[] {
 	return mergeTextNodes(nodes)
 }
 
+/**
+ * CommonMark's intraword rule for `_`: an underscore flanked by alphanumerics
+ * (like `?gaa_at=eafs&gaa_n=…` in a bare URL, or `snake_case`) is literal
+ * text, never emphasis. Without this, URLs with query params get italic marks
+ * spliced through them and re-serialize corrupted.
+ */
+function isIntrawordUnderscore(text: string, remaining: string, match: RegExpExecArray): boolean {
+	const consumed = text.length - remaining.length
+	const previousChar = consumed > 0 ? text[consumed - 1] : ''
+	const nextChar = remaining[match[0].length] ?? ''
+	return /[A-Za-z0-9]/.test(previousChar) || /[A-Za-z0-9]/.test(nextChar)
+}
+
 function parseInlineWithMark(text: string, mark: InlineMark): JSONContent[] {
 	const inner = parseInline(text)
 	return inner.map((n) => ({