@growth-labs/cms 0.5.21 → 0.5.22

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