@growth-labs/cms 0.5.21 → 0.5.23

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/ContentForm.tsx

@@ -36,6 +36,8 @@ import {
 } from './content-payload.js'
 import { measureEditorMediaDurationSeconds } from './editor-media-duration.js'
 import { uploadEditorImage } from './editor-media-upload.js'
+import { LayoutBuilder } from './LayoutBuilder.js'
+import { layoutDraftFromData } from './layout-mode.js'
 import { Rte } from './Rte.js'
 import { docToMarkdown } from './serialize.js'
 
@@ -110,6 +112,7 @@ interface ExistingContentPayload {
 	body_markdown?: string | null
 	body_html?: string | null
 	body_portable_text?: string | null
+	layout_json?: string | null
 	subtitle?: string | null
 	script?: string | null
 	video_id?: string | null
@@ -134,6 +137,10 @@ interface FormState {
 	body: string
 	/** Serialized Portable Text envelope paired with `body`; null until the editor emits one. */
 	bodyPortableText: string | null
+	/** Serialized Puck layout envelope (pages only); null = classic page. */
+	layoutJson: string | null
+	/** Whether the Builder canvas (vs the classic Rte) is showing (pages only). */
+	builderOpen: boolean
 	slug: string
 	byline: string | null
 	authorId: string | null
@@ -180,6 +187,8 @@ function createEmptyFormState(docId: string | null): FormState {
 		dek: '',
 		body: '',
 		bodyPortableText: null,
+		layoutJson: null,
+		builderOpen: false,
 		slug: '',
 		byline: null,
 		authorId: null,
@@ -519,6 +528,35 @@ export function ContentForm({
 		scheduleAutosave(next)
 	}
 
+	function handleLayoutDataChange(data: Parameters<typeof layoutDraftFromData>[0]) {
+		const current = latestForm.current
+		const next = {
+			...current,
+			...layoutDraftFromData(data, current.body, current.title),
+		}
+		setForm(next)
+		publishDraft(next)
+		scheduleAutosave(next)
+	}
+
+	function handleBuilderToggle(open: boolean) {
+		setForm((prev) => ({ ...prev, builderOpen: open }))
+	}
+
+	function handleRemoveLayout() {
+		if (
+			!window.confirm(
+				'Remove the page layout? The page renders its classic body again; the layout cannot be recovered after the next save.',
+			)
+		) {
+			return
+		}
+		const next = { ...latestForm.current, layoutJson: null, builderOpen: false }
+		setForm(next)
+		publishDraft(next)
+		scheduleAutosave(next)
+	}
+
 	function handleVideoUrlChange(value: string) {
 		const next = {
 			...latestForm.current,
@@ -942,12 +980,66 @@ export function ContentForm({
 								/>
 							</div>
 						)}
-						<Rte
-							value={form.body}
-							portableText={form.bodyPortableText}
-							onChange={handleBodyChange}
-							onImageUpload={handleEditorImageUpload}
-						/>
+						{contentType === 'page' && (
+							<div
+								style={{
+									display: 'flex',
+									alignItems: 'center',
+									gap: 10,
+									marginBottom: 10,
+									fontSize: 13,
+								}}
+							>
+								<button
+									type="button"
+									onClick={() => handleBuilderToggle(false)}
+									style={modeTabStyle(!form.builderOpen)}
+								>
+									Classic body
+								</button>
+								<button
+									type="button"
+									onClick={() => handleBuilderToggle(true)}
+									style={modeTabStyle(form.builderOpen)}
+								>
+									Builder
+								</button>
+								{form.layoutJson !== null && (
+									<>
+										{!form.builderOpen && (
+											<span style={{ color: 'var(--ink-faint)' }}>
+												This page has a layout — the layout wins on the live page.
+											</span>
+										)}
+										<button
+											type="button"
+											onClick={handleRemoveLayout}
+											style={{
+												...modeTabStyle(false),
+												marginLeft: 'auto',
+												color: 'var(--danger, #b91c1c)',
+											}}
+										>
+											Remove layout
+										</button>
+									</>
+								)}
+							</div>
+						)}
+						{contentType === 'page' && form.builderOpen ? (
+							<LayoutBuilder
+								layoutJson={form.layoutJson}
+								onDataChange={handleLayoutDataChange}
+								onImageUpload={handleEditorImageUpload}
+							/>
+						) : (
+							<Rte
+								value={form.body}
+								portableText={form.bodyPortableText}
+								onChange={handleBodyChange}
+								onImageUpload={handleEditorImageUpload}
+							/>
+						)}
 					</>
 				)}
 			</div>
@@ -1373,6 +1465,12 @@ function contentResponseToFormState(
 		next.bodyPortableText = toNullableString(content.body_portable_text)
 	}
 
+	if (contentType === 'page') {
+		next.layoutJson = toNullableString(content.layout_json)
+		// A stored layout means this is a builder page — open the canvas.
+		next.builderOpen = next.layoutJson !== null
+	}
+
 	if (contentType === 'video') {
 		next.body = toStringValue(content.script)
 		next.videoUrl = toStringValue(content.processing_source_url)
@@ -1452,6 +1550,19 @@ function timeSince(ts: number): string {
 // Styles
 // ---------------------------------------------------------------------------
 
+function modeTabStyle(active: boolean): React.CSSProperties {
+	return {
+		border: '1px solid var(--line)',
+		borderRadius: 6,
+		background: active ? 'var(--ink)' : 'transparent',
+		color: active ? 'var(--paper, #fff)' : 'var(--ink)',
+		cursor: 'pointer',
+		fontSize: 12,
+		fontWeight: 600,
+		padding: '4px 10px',
+	}
+}
+
 const formWrap: React.CSSProperties = {
 	display: 'flex',
 	flexDirection: 'column',

package/src/ui/editor/LayoutBuilder.tsx

@@ -0,0 +1,100 @@
+// src/ui/editor/LayoutBuilder.tsx
+// Builder mode for page documents: mounts the Puck editor over the shared
+// component config (src/puck/config.tsx). Browser-only by nature — this
+// module imports the full @puckeditor/core editor and TipTap HTML generation,
+// and it ships in the admin client bundle only.
+//
+// <Puck data> is initial-only: the parent renders this component conditionally
+// (or keyed per doc), so every mount re-reads the stored envelope. Canvas
+// changes flow up through onDataChange as plain LayoutData; the parent owns
+// wrapping, projection, and autosave (layout-mode.ts).
+
+import { Puck } from '@puckeditor/core'
+import '@puckeditor/core/no-external.css'
+import { generateHTML } from '@tiptap/core'
+import { useMemo, useState } from 'react'
+import { createPuckConfig, type LayoutData } from '../../puck/index.js'
+import { parsePortableTextEnvelope } from '../../schema/portable-text.js'
+import { createRteExtensions } from './extensions.js'
+import { initialLayoutData, richTextMarkdownFromEnvelope } from './layout-mode.js'
+import { portableTextToDoc } from './portable-text.js'
+import { Rte, type RteProps } from './Rte.js'
+
+function escapeHtml(value: string): string {
+	return value
+		.replaceAll('&', '&amp;')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;')
+		.replaceAll('"', '&quot;')
+		.replaceAll("'", '&#39;')
+}
+
+// Canvas preview for RichText blocks: the same TipTap schema the Rte uses,
+// so the preview matches what the field editor shows. Falls back to escaped
+// text if HTML generation fails; empty envelopes show a placeholder hint.
+function canvasRichTextHtml(envelopeJson: string): string {
+	const parsed = parsePortableTextEnvelope(envelopeJson)
+	if (!parsed) {
+		return '<p class="gl-builder-richtext-empty">Empty rich text — select the block to write.</p>'
+	}
+	try {
+		return generateHTML(portableTextToDoc(parsed.content), createRteExtensions())
+	} catch {
+		return `<p>${escapeHtml(richTextMarkdownFromEnvelope(envelopeJson))}</p>`
+	}
+}
+
+function makeRichTextField(onImageUpload: RteProps['onImageUpload']) {
+	return {
+		type: 'custom' as const,
+		label: 'Rich text',
+		render: ({ value, onChange }: { value: unknown; onChange: (value: string) => void }) => {
+			const stored = typeof value === 'string' ? value : ''
+			return (
+				<div className="gl-builder-richtext-field">
+					<Rte
+						value={richTextMarkdownFromEnvelope(stored)}
+						portableText={stored || null}
+						onChange={(_md, portableText) => onChange(portableText)}
+						onImageUpload={onImageUpload}
+					/>
+				</div>
+			)
+		},
+	}
+}
+
+const EMPTY_DATA: LayoutData = { root: { props: {} }, content: [] }
+
+export interface LayoutBuilderProps {
+	/** Stored layout envelope JSON at mount time; null starts a blank canvas. */
+	layoutJson: string | null
+	/** Fires on every canvas edit with the raw Puck data. */
+	onDataChange: (data: LayoutData) => void
+	onImageUpload?: RteProps['onImageUpload']
+}
+
+export function LayoutBuilder({ layoutJson, onDataChange, onImageUpload }: LayoutBuilderProps) {
+	const config = useMemo(
+		() =>
+			createPuckConfig({
+				renderRichTextHtml: canvasRichTextHtml,
+				richTextField: makeRichTextField(onImageUpload),
+			}),
+		[onImageUpload],
+	)
+	// Initial-only by contract — a lazy state initializer reads the prop once
+	// at mount (Puck ignores later data props; a remount re-reads the envelope).
+	const [initialData] = useState(() => initialLayoutData(layoutJson) ?? EMPTY_DATA)
+	return (
+		<div className="gl-layout-builder" style={{ border: '1px solid var(--line)', borderRadius: 8 }}>
+			<Puck
+				config={config}
+				data={initialData as never}
+				onChange={(data) => onDataChange(data as unknown as LayoutData)}
+				iframe={{ enabled: false }}
+				height="72vh"
+			/>
+		</div>
+	)
+}

package/src/ui/editor/content-payload.ts

@@ -7,6 +7,8 @@ export interface ContentDraftFields {
 	body: string
 	/** Serialized Portable Text envelope for the body; null until the editor emits one. */
 	bodyPortableText?: string | null
+	/** Serialized Puck layout envelope (pages only); null clears, undefined never sent. */
+	layoutJson?: string | null
 	videoUrl: string
 	videoSourceKind?: string | null
 	videoId?: string | null
@@ -109,6 +111,9 @@ export function buildContentUpdatePayload(
 			bodyPortableText: draft.bodyPortableText || null,
 			wordCount,
 			readTimeMinutes: estimateReadTime(wordCount),
+			// Pages always state their layout explicitly: a value writes it,
+			// null clears it (the engine preserves only when the key is absent).
+			...(contentType === 'page' ? { layoutJson: draft.layoutJson ?? null } : {}),
 		}
 	} else if (contentType === 'video') {
 		const sourceUrl = draft.videoUrl.trim()

package/src/ui/editor/layout-mode.ts

@@ -0,0 +1,58 @@
+// src/ui/editor/layout-mode.ts
+// Pure Builder-mode logic: canvas data → persisted draft triple, stored
+// envelope → canvas data, and the Portable Text ↔ markdown bridge for the
+// RichText custom field. No DOM, no Puck imports — the LayoutBuilder
+// component owns the browser-only pieces.
+
+import {
+	type LayoutData,
+	layoutToMarkdown,
+	parseLayoutEnvelope,
+	wrapLayout,
+} from '../../puck/index.js'
+import { parsePortableTextEnvelope } from '../../schema/portable-text.js'
+import { portableTextToDoc } from './portable-text.js'
+import { docToMarkdown } from './serialize.js'
+
+export interface LayoutDraft {
+	layoutJson: string
+	body: string
+	bodyPortableText: null
+}
+
+/**
+ * Turn a Puck canvas change into the fields a builder save persists. The
+ * classic body stays populated with the derived-markdown projection (search,
+ * SEO, non-layout surfaces); an unprojectable layout keeps the previous body,
+ * then the title, so create/publish body requirements still hold.
+ */
+export function layoutDraftFromData(
+	data: LayoutData,
+	previousBody: string,
+	title: string,
+): LayoutDraft {
+	const envelope = wrapLayout(data)
+	const projected = layoutToMarkdown(envelope).trim()
+	return {
+		layoutJson: JSON.stringify(envelope),
+		body: projected || previousBody.trim() || title.trim(),
+		// The derived body is markdown-only — stale Portable Text must not
+		// survive a builder save (same staleness rule the engine enforces).
+		bodyPortableText: null,
+	}
+}
+
+/** Stored layout JSON → Puck canvas data; null for absent/malformed. */
+export function initialLayoutData(layoutJson: string | null): LayoutData | null {
+	return parseLayoutEnvelope(layoutJson)?.data ?? null
+}
+
+/**
+ * Portable Text envelope JSON (a RichText block's stored prop) → markdown,
+ * for seeding the embedded Rte. Empty string when the envelope is malformed.
+ */
+export function richTextMarkdownFromEnvelope(envelopeJson: string): string {
+	const parsed = parsePortableTextEnvelope(envelopeJson)
+	if (!parsed) return ''
+	return docToMarkdown(portableTextToDoc(parsed.content)).trim()
+}