@growth-labs/cms 0.5.27 → 0.5.29

package/src/integration/options.ts

@@ -13,6 +13,74 @@ const primaryCategorySchema = z.object({
 	label: z.string().min(1),
 })
 
+const contentMetadataKeySchema = z
+	.string()
+	.regex(/^[a-z][a-z0-9_]{0,63}$/, 'metadata keys must be lowercase snake_case')
+
+const contentMetadataSelectFieldSchema = z
+	.object({
+		key: contentMetadataKeySchema,
+		label: z.string().trim().min(1).max(100),
+		helpText: z.string().trim().min(1).max(500).optional(),
+		contentTypes: z.array(z.enum(['article', 'video', 'podcast', 'newsletter', 'page'])).min(1),
+		options: z
+			.array(
+				z
+					.object({
+						value: z.string().trim().min(1).max(100),
+						label: z.string().trim().min(1).max(100),
+					})
+					.strict(),
+			)
+			.min(1),
+		defaultValue: z.string().trim().min(1).max(100).optional(),
+		inferenceMarkerKey: contentMetadataKeySchema.optional(),
+	})
+	.strict()
+	.superRefine((field, ctx) => {
+		const values = field.options.map(({ value }) => value)
+		if (new Set(values).size !== values.length) {
+			ctx.addIssue({
+				code: 'custom',
+				path: ['options'],
+				message: 'metadata select option values must be unique',
+			})
+		}
+		if (field.defaultValue && !values.includes(field.defaultValue)) {
+			ctx.addIssue({
+				code: 'custom',
+				path: ['defaultValue'],
+				message: 'metadata select defaultValue must match a declared option',
+			})
+		}
+		if (field.inferenceMarkerKey === field.key) {
+			ctx.addIssue({
+				code: 'custom',
+				path: ['inferenceMarkerKey'],
+				message: 'metadata select inference marker must use a separate key',
+			})
+		}
+	})
+
+const contentMetadataSelectsSchema = z
+	.array(contentMetadataSelectFieldSchema)
+	.superRefine((fields, ctx) => {
+		const keys = new Set<string>()
+		for (const [index, field] of fields.entries()) {
+			if (keys.has(field.key)) {
+				ctx.addIssue({
+					code: 'custom',
+					path: [index, 'key'],
+					message: 'metadata select keys must be unique',
+				})
+			}
+			keys.add(field.key)
+		}
+	})
+	.default([])
+
+export type ContentMetadataSelectField = z.output<typeof contentMetadataSelectFieldSchema>
+
 const themeSchema = z
 	.object({
 		mode: z.enum(['light', 'dark']).default('dark'),
@@ -38,6 +106,7 @@ export const cmsIntegrationOptionsSchema = z
 	.object({
 		workspaces: z.array(workspaceSchema).min(1, 'at least one workspace is required'),
 		primaryCategories: z.array(primaryCategorySchema).default([]),
+		contentMetadataSelects: contentMetadataSelectsSchema,
 		activeWorkspaceId: z.string().optional(),
 		adminBasePath: z.string().default('/admin'),
 		searchEnabled: z.boolean().default(true),

package/src/routes/content.ts

@@ -18,6 +18,11 @@ import { z } from 'zod'
 import { logActivity } from '../engine/activity-log.js'
 import { generateContentDek } from '../engine/ai-dek.js'
 import { createDekFailureNotifications } from '../engine/ai-dek-notifications.js'
+import {
+	type ContentMetadata,
+	ContentMetadataError,
+	serializeContentMetadata,
+} from '../engine/content-metadata.js'
 import { listContributors, setContributors } from '../engine/contributors.js'
 import type { D1Database } from '../engine/d1.js'
 import {
@@ -52,6 +57,7 @@ import {
 import { applySlugRenameRedirects } from '../engine/slug-redirects.js'
 import { softDeleteContent } from '../engine/soft-delete.js'
 import { TagInputError } from '../engine/taxonomy.js'
+import type { ValidationError } from '../engine/validator/index.js'
 import { parseLayoutEnvelope } from '../schema/layout.js'
 import { parsePortableTextEnvelope } from '../schema/portable-text.js'
 import type { ContentStatus } from '../schema/types.js'
@@ -284,6 +290,21 @@ const BodyContentCreateSchema = z.object({
 	editorTakeaways: z.array(z.string().min(1)).max(4).optional().nullable(),
 })
 
+const ContentMetadataSchema = z
+	.record(z.string(), z.unknown())
+	.superRefine((metadata, ctx) => {
+		try {
+			serializeContentMetadata(metadata as ContentMetadata)
+		} catch (error) {
+			ctx.addIssue({
+				code: 'custom',
+				message:
+					error instanceof ContentMetadataError ? error.message : 'content metadata is invalid',
+			})
+		}
+	})
+	.transform((metadata) => metadata as ContentMetadata)
+
 function buildSchemas(resolved: ReturnType<typeof resolveConfig>) {
 	const category = slugEnum(resolved.primaryCategorySlugs)
 	const topic = slugEnum(resolved.primaryTopicSlugs)
@@ -306,6 +327,7 @@ function buildSchemas(resolved: ReturnType<typeof resolveConfig>) {
 		socialImageId: z.string().optional().nullable(),
 		canonicalUrl: z.string().url().optional().nullable(),
 		tags: z.array(z.string()).optional(),
+		metadata: ContentMetadataSchema.optional(),
 	})
 
 	const CreateSchema = z.discriminatedUnion('type', [
@@ -370,6 +392,7 @@ function buildSchemas(resolved: ReturnType<typeof resolveConfig>) {
 		socialImageId: z.string().optional().nullable(),
 		canonicalUrl: z.string().url().optional().nullable(),
 		tags: z.array(z.string()).optional(),
+		metadata: ContentMetadataSchema.optional(),
 		content: z.record(z.string(), z.any()).optional(),
 		relations: z.array(RelationSchema).optional(),
 		aiLockedFields: z.array(z.string()).optional(),
@@ -1205,6 +1228,12 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				return json({ error: 'Invalid request', details: parsed.error.flatten() }, 400)
 			}
 
+			// Warn-severity body-lint results. Declared here so the success payload
+			// below can carry them: they do not block the save, but an editor who is
+			// never told is how a malformed Sources section reached a published page
+			// (packages#329).
+			let bodyWarnings: ValidationError[] = []
+
 			if (parsed.data.content !== undefined) {
 				const contentSchema = getContentUpdateSchema(existing.type)
 				if (!contentSchema) return json({ error: 'Invalid content type' }, 400)
@@ -1243,6 +1272,11 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 								422,
 							)
 						}
+						// Warn-severity violations do not block the save, but the editor
+						// has to be told: an unreported warning is why a malformed Sources
+						// section reached a published page (packages#329). Carried into
+						// the 200 payload below rather than only console.warn'd.
+						bodyWarnings = guard.warnings
 					}
 				}
 			}
@@ -1276,6 +1310,9 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				podcastFoundryQueued: Boolean(podcastAttempt.result),
 				podcastFoundryCorrelationId: podcastAttempt.result?.correlationId ?? null,
 				podcastFoundryReason: podcastAttempt.reason,
+				// Present and empty when the body linted clean, so a client can
+				// distinguish "no warnings" from "this build does not report them".
+				bodyWarnings,
 			})
 		},
 

package/src/ui/client/mount.tsx

@@ -39,6 +39,7 @@ export async function mount(elementId = 'masthead-root') {
 	const screens = createCmsScreens({
 		allowInlineAuthorCreation: config.socialSharing.allowInlineAuthorCreation,
 		primaryCategories: config.primaryCategories,
+		contentMetadataSelects: config.contentMetadataSelects,
 		surveyId: config.surveyResults?.surveyId,
 	})
 	createRoot(el).render(<CmsApp initial={initial} screens={screens} boot={boot} />)

package/src/ui/editor/ContentForm.tsx

@@ -18,8 +18,10 @@
 //
 // Compile-gated: all Tiptap/React usage verified by `pnpm run build` (tsc).
 
-import { useCallback, useEffect, useId, useRef, useState } from 'react'
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
+import { type ContentMetadata, parseContentMetadata } from '../../engine/content-metadata.js'
 import { countWords, estimateReadTime } from '../../engine/publisher.js'
+import type { ContentMetadataSelectField } from '../../integration/options.js'
 import type { ContentStatus, ContentType } from '../../schema/types.js'
 import { Icon } from '../icons.js'
 import { uploadMediaAsset } from '../screens/media-upload.js'
@@ -31,8 +33,10 @@ import {
 	type ContentDraftFields,
 	canCreateContentDraft,
 	foundryDispatchSourceForDraft,
+	initialContentMetadata,
 	normalizeMediaDurationSeconds,
 	slugifyTitle,
+	updateContentMetadataSelection,
 } from './content-payload.js'
 import { measureEditorMediaDurationSeconds } from './editor-media-duration.js'
 import { uploadEditorImage } from './editor-media-upload.js'
@@ -63,6 +67,7 @@ export interface ContentFormProps {
 	/** Called when save state changes so editor chrome can show a real save action. */
 	onSaveStateChange?: (state: ContentSaveState) => void
 	primaryCategories?: Array<{ slug: string; label: string }>
+	contentMetadataSelects?: ContentMetadataSelectField[]
 }
 
 export interface ContentSaveState {
@@ -106,6 +111,7 @@ interface ExistingContentItem {
 	published_at?: number | null
 	hero_image_id?: string | null
 	hero_image_url?: string | null
+	metadata_json?: string
 }
 
 interface ExistingContentPayload {
@@ -149,6 +155,7 @@ interface FormState {
 	publishedAt: string | null
 	premium: boolean
 	channel: string | null
+	metadata: ContentMetadata
 	heroImageId: string
 	heroImageUrl: string | null
 	heroUploadStatus: 'idle' | 'uploading' | 'staged'
@@ -180,7 +187,9 @@ interface FormState {
 	aiOpen: boolean
 }
 
-function createEmptyFormState(docId: string | null): FormState {
+const EMPTY_CONTENT_METADATA_SELECTS: ContentMetadataSelectField[] = []
+
+function createEmptyFormState(docId: string | null, metadata: ContentMetadata = {}): FormState {
 	return {
 		status: 'draft',
 		title: '',
@@ -197,6 +206,7 @@ function createEmptyFormState(docId: string | null): FormState {
 		publishedAt: null,
 		premium: false,
 		channel: null,
+		metadata,
 		heroImageId: '',
 		heroImageUrl: null,
 		heroUploadStatus: 'idle',
@@ -238,8 +248,15 @@ export function ContentForm({
 	onStatusChange,
 	onSaveStateChange,
 	primaryCategories = [],
+	contentMetadataSelects = EMPTY_CONTENT_METADATA_SELECTS,
 }: ContentFormProps) {
-	const [form, setForm] = useState<FormState>(() => createEmptyFormState(docId))
+	const metadataFields = useMemo(
+		() => contentMetadataSelects.filter((field) => field.contentTypes.includes(contentType)),
+		[contentMetadataSelects, contentType],
+	)
+	const [form, setForm] = useState<FormState>(() =>
+		createEmptyFormState(docId, initialContentMetadata(metadataFields, contentType)),
+	)
 
 	// Autosave state (mutable refs, not React state — no re-render needed)
 	const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
@@ -260,7 +277,7 @@ export function ContentForm({
 
 	const loadExistingContent = useCallback(async () => {
 		if (!docId) {
-			const next = createEmptyFormState(null)
+			const next = createEmptyFormState(null, initialContentMetadata(metadataFields, contentType))
 			setForm(next)
 			publishDraft(next)
 			return
@@ -288,7 +305,7 @@ export function ContentForm({
 				saveError: err instanceof Error ? err.message : 'Could not load content',
 			}))
 		}
-	}, [contentType, docId, onStatusChange, publishDraft])
+	}, [contentType, docId, metadataFields, onStatusChange, publishDraft])
 
 	// -- Word-count (derived from the body markdown) -------------------------
 	const wordCount = countWords(form.body)
@@ -521,6 +538,16 @@ export function ContentForm({
 		scheduleAutosave(next)
 	}
 
+	function handleMetadataSelectChange(field: ContentMetadataSelectField, value: string) {
+		const next = {
+			...latestForm.current,
+			metadata: updateContentMetadataSelection(latestForm.current.metadata, field, value),
+		}
+		setForm(next)
+		publishDraft(next)
+		scheduleAutosave(next)
+	}
+
 	function handleBodyChange(md: string, portableText: string) {
 		const next = { ...latestForm.current, body: md, bodyPortableText: portableText }
 		setForm(next)
@@ -895,6 +922,39 @@ export function ContentForm({
 				</div>
 			)}
 
+			{metadataFields.map((field) => {
+				const storedValue = form.metadata[field.key]
+				const value = typeof storedValue === 'string' ? storedValue : ''
+				const inferred =
+					field.inferenceMarkerKey !== undefined && form.metadata[field.inferenceMarkerKey] === true
+				return (
+					<div key={field.key} style={fieldGroup}>
+						<label style={{ display: 'grid', gap: 6, fontSize: 12, color: 'var(--ink-muted)' }}>
+							{field.label}
+							<select
+								value={value}
+								onChange={(event) => handleMetadataSelectChange(field, event.currentTarget.value)}
+								aria-label={field.label}
+								style={urlInput}
+							>
+								<option value="">Select…</option>
+								{field.options.map((option) => (
+									<option key={option.value} value={option.value}>
+										{option.label}
+									</option>
+								))}
+							</select>
+						</label>
+						{(field.helpText || inferred) && (
+							<div style={assetHelp}>
+								{inferred ? 'Inferred value — review and choose the best fit. ' : ''}
+								{field.helpText}
+							</div>
+						)}
+					</div>
+				)
+			})}
+
 			{/* Signature masthead hairline between the standfirst and the body */}
 			<hr className="masthead-rule" style={{ margin: '6px 0 20px' }} />
 
@@ -1457,6 +1517,7 @@ function contentResponseToFormState(
 	next.publishedAt = unixSecondsToIso(item.published_at)
 	next.premium = item.visibility === 'premium'
 	next.channel = toNullableString(item.channel)
+	next.metadata = storedContentMetadata(item.metadata_json)
 	next.heroImageId = heroImageId
 	next.heroImageUrl = heroImageUrl || (heroImageId ? mediaUrlFromId(heroImageId) : null)
 
@@ -1491,6 +1552,14 @@ function contentResponseToFormState(
 	return next
 }
 
+function storedContentMetadata(raw: string | null | undefined): ContentMetadata {
+	try {
+		return parseContentMetadata(raw ?? '{}')
+	} catch {
+		return {}
+	}
+}
+
 function formToPreviewDraft(form: FormState, contentType: ContentType): ContentPreviewDraft {
 	return {
 		id: form.savedId ?? 'draft',

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

@@ -1,4 +1,6 @@
+import type { ContentMetadata } from '../../engine/content-metadata.js'
 import { countWords, estimateReadTime } from '../../engine/publisher.js'
+import type { ContentMetadataSelectField } from '../../integration/options.js'
 import type { ContentType } from '../../schema/types.js'
 
 export interface ContentDraftFields {
@@ -17,6 +19,42 @@ export interface ContentDraftFields {
 	audioUrl: string
 	durationSeconds: number | null
 	channel?: string | null
+	metadata?: ContentMetadata
+}
+
+type MetadataSelectFieldContract = Pick<
+	ContentMetadataSelectField,
+	'key' | 'defaultValue' | 'inferenceMarkerKey'
+> & {
+	contentTypes: readonly ContentType[]
+	options: ReadonlyArray<{ value: string }>
+}
+
+export function initialContentMetadata(
+	fields: readonly MetadataSelectFieldContract[],
+	contentType: ContentType,
+): ContentMetadata {
+	const metadata: ContentMetadata = {}
+	for (const field of fields) {
+		if (!field.contentTypes.includes(contentType) || !field.defaultValue) continue
+		metadata[field.key] = field.defaultValue
+	}
+	return metadata
+}
+
+export function updateContentMetadataSelection(
+	metadata: Readonly<ContentMetadata>,
+	field: MetadataSelectFieldContract,
+	value: string,
+): ContentMetadata {
+	if (value && !field.options.some((option) => option.value === value)) {
+		throw new RangeError(`Unknown option for metadata field ${field.key}`)
+	}
+	const next: ContentMetadata = { ...metadata }
+	if (value) next[field.key] = value
+	else delete next[field.key]
+	if (field.inferenceMarkerKey) delete next[field.inferenceMarkerKey]
+	return next
 }
 
 export function normalizeMediaDurationSeconds(value: unknown): number | null {
@@ -97,6 +135,7 @@ export function buildContentUpdatePayload(
 		title: draft.title,
 		excerpt: draft.dek || null,
 	}
+	if (draft.metadata !== undefined) payload.metadata = draft.metadata
 	const channel = draft.channel?.trim()
 	payload.primaryCategory = channel || null
 	const heroImageId = draft.heroImageId?.trim()

package/src/ui/screens/ContentRoute.tsx

@@ -8,6 +8,7 @@
 // This file creates thin stubs so the registry can compile now (Task 10).
 
 import { useReducer } from 'react'
+import type { ContentMetadataSelectField } from '../../integration/options.js'
 import { type ContentType, contentViewReducer, initialContentView } from './content-view.js'
 import { EditorScreen } from './EditorScreen.js'
 import { LibraryScreen } from './LibraryScreen.js'
@@ -15,9 +16,11 @@ import { LibraryScreen } from './LibraryScreen.js'
 export function ContentRoute({
 	allowInlineAuthorCreation = true,
 	primaryCategories = [],
+	contentMetadataSelects = [],
 }: {
 	allowInlineAuthorCreation?: boolean
 	primaryCategories?: Array<{ slug: string; label: string }>
+	contentMetadataSelects?: ContentMetadataSelectField[]
 }) {
 	const [view, dispatch] = useReducer(contentViewReducer, initialContentView)
 
@@ -49,6 +52,7 @@ export function ContentRoute({
 			onClose={handleClose}
 			allowInlineAuthorCreation={allowInlineAuthorCreation}
 			primaryCategories={primaryCategories}
+			contentMetadataSelects={contentMetadataSelects}
 		/>
 	)
 }

package/src/ui/screens/EditorScreen.tsx

@@ -17,6 +17,7 @@
 // is Playwright-smoked only.
 
 import { useCallback, useState } from 'react'
+import type { ContentMetadataSelectField } from '../../integration/options.js'
 import type { ContentStatus, ContentType } from '../../schema/types.js'
 import { buildSharePrefill, ShareModal } from '../components/ShareModal.js'
 import {
@@ -40,6 +41,7 @@ export interface EditorScreenProps {
 	onClose: () => void
 	allowInlineAuthorCreation?: boolean
 	primaryCategories?: Array<{ slug: string; label: string }>
+	contentMetadataSelects?: ContentMetadataSelectField[]
 }
 
 // ---------------------------------------------------------------------------
@@ -81,6 +83,7 @@ export function EditorScreen({
 	onClose,
 	allowInlineAuthorCreation = true,
 	primaryCategories = [],
+	contentMetadataSelects = [],
 }: EditorScreenProps) {
 	const contentType: ContentType = (docRef.contentType as ContentType | undefined) ?? 'article'
 	const siteBase = typeof window !== 'undefined' ? window.location.origin : undefined
@@ -377,6 +380,7 @@ export function EditorScreen({
 								onStatusChange={setStatus}
 								onSaveStateChange={handleSaveStateChange}
 								primaryCategories={primaryCategories}
+								contentMetadataSelects={contentMetadataSelects}
 							/>
 						</div>
 

package/src/ui/screens/registry.tsx

@@ -11,6 +11,7 @@
 // internal router state (which is not exported). The ContentRoute itself owns
 // the full open-doc reducer (which doc is open, new vs existing).
 
+import type { ContentMetadataSelectField } from '../../integration/options.js'
 import type { ScreenRegistry } from '../components/CmsApp.js'
 import { useHashRouter } from '../use-hash-router.js'
 import { AnalyticsScreen } from './AnalyticsScreen.js'
@@ -42,10 +43,12 @@ function CalendarRoute() {
 export function createCmsScreens({
 	allowInlineAuthorCreation = true,
 	primaryCategories = [],
+	contentMetadataSelects = [],
 	surveyId,
 }: {
 	allowInlineAuthorCreation?: boolean
 	primaryCategories?: Array<{ slug: string; label: string }>
+	contentMetadataSelects?: ContentMetadataSelectField[]
 	surveyId?: string
 } = {}): ScreenRegistry {
 	return {
@@ -53,6 +56,7 @@ export function createCmsScreens({
 			<ContentRoute
 				allowInlineAuthorCreation={allowInlineAuthorCreation}
 				primaryCategories={primaryCategories}
+				contentMetadataSelects={contentMetadataSelects}
 			/>
 		),
 		'content-insights': () => <ContentInsightsScreen />,