@growth-labs/cms 0.1.0

package/src/ui/inspector/SeoTab.tsx

@@ -0,0 +1,573 @@
+// src/ui/inspector/SeoTab.tsx — SEO inspector tab.
+//
+// Sections:
+//   - Score ring: live 0–100 score + 5-check checklist (re-scores on debounce).
+//   - Meta fields: seoTitle / description / seoFocusKeyword — PATCH on blur.
+//   - OG / social preview: renders from title/excerpt/hero; Generate is P4-disabled.
+//
+// The Generate button is rendered disabled with title="AI generation arrives in P4"
+// per the P3 scope guard: NO LlmDispatch call here.
+//
+// Compile-gated (tsc, jsx: react-jsx). No vitest — the pure helpers (scoreRingGeometry,
+// seoSummary) are tested in score-ring.test.ts / seo-checks.test.ts.
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { SeoCheck } from '../../engine/seo.js'
+import { Icon } from '../icons.js'
+import { Field } from './Field.js'
+import { generateOgImage, ogButtonState, patchContent, scoreSeo } from './inspector-data.js'
+import { Section } from './Section.js'
+import { scoreRingGeometry, seoSummary } from './seo-helpers.js'
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+export interface SeoTabProps {
+	docId: string
+	/** Current persisted seoTitle (may be null/empty). */
+	seoTitle: string | null
+	/** Current persisted meta description. */
+	description: string | null
+	/** Current persisted focus keyword. */
+	seoFocusKeyword: string | null
+	/** Title of the content item (used for OG preview and scoring fallback). */
+	title: string
+	/** Excerpt (used for OG preview). */
+	excerpt: string | null
+	/** Hero image URL (used for OG preview, optional). */
+	heroImageUrl: string | null
+	/** Called after a field change so the parent can refresh. */
+	onChanged?: () => void
+}
+
+type OgState = 'idle' | 'loading' | 'generated' | 'locked' | 'error'
+
+// ---------------------------------------------------------------------------
+// SeoTab
+// ---------------------------------------------------------------------------
+
+export function SeoTab({
+	docId,
+	seoTitle: initialSeoTitle,
+	description: initialDescription,
+	seoFocusKeyword: initialFocusKeyword,
+	title,
+	excerpt,
+	heroImageUrl,
+	onChanged,
+}: SeoTabProps): React.ReactElement {
+	// Local field state (controlled).
+	const [seoTitle, setSeoTitle] = useState(initialSeoTitle ?? '')
+	const [description, setDescription] = useState(initialDescription ?? '')
+	const [focusKeyword, setFocusKeyword] = useState(initialFocusKeyword ?? '')
+
+	// OG image generation state.
+	const [ogState, setOgState] = useState<OgState>('idle')
+	const [ogPreviewUrl, setOgPreviewUrl] = useState<string | null>(heroImageUrl)
+
+	// Sync external changes (e.g. after a parent refresh).
+	useEffect(() => setSeoTitle(initialSeoTitle ?? ''), [initialSeoTitle])
+	useEffect(() => setDescription(initialDescription ?? ''), [initialDescription])
+	useEffect(() => setFocusKeyword(initialFocusKeyword ?? ''), [initialFocusKeyword])
+
+	// Live score state.
+	const [score, setScore] = useState<number | null>(null)
+	const [checks, setChecks] = useState<SeoCheck[]>([])
+	const [scoring, setScoring] = useState(false)
+
+	// Debounce timer ref.
+	const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+	// Re-score when any SEO field changes.
+	const triggerScore = useCallback(
+		(overrides: { seoTitle?: string; description?: string; focusKeyword?: string }) => {
+			if (debounceRef.current) clearTimeout(debounceRef.current)
+			debounceRef.current = setTimeout(async () => {
+				setScoring(true)
+				try {
+					const result = (await scoreSeo(docId, {
+						seoTitle: overrides.seoTitle,
+						description: overrides.description,
+						focusKeyword: overrides.focusKeyword,
+					})) as { score?: number; checks?: SeoCheck[] }
+					if (typeof result.score === 'number') setScore(result.score)
+					if (Array.isArray(result.checks)) setChecks(result.checks)
+				} catch {
+					// non-fatal — ring stays on last score
+				} finally {
+					setScoring(false)
+				}
+			}, 400)
+		},
+		[docId],
+	)
+
+	// Initial score on mount (no overrides — read persisted fields).
+	useEffect(() => {
+		if (!docId) return
+		void (async () => {
+			setScoring(true)
+			try {
+				const result = (await scoreSeo(docId)) as { score?: number; checks?: SeoCheck[] }
+				if (typeof result.score === 'number') setScore(result.score)
+				if (Array.isArray(result.checks)) setChecks(result.checks)
+			} catch {
+				// non-fatal
+			} finally {
+				setScoring(false)
+			}
+		})()
+	}, [docId])
+
+	// Field change handlers — update local state + trigger a re-score.
+	const handleSeoTitleChange = useCallback(
+		(e: React.ChangeEvent<HTMLInputElement>) => {
+			const val = e.target.value
+			setSeoTitle(val)
+			triggerScore({ seoTitle: val, description, focusKeyword })
+		},
+		[description, focusKeyword, triggerScore],
+	)
+
+	const handleDescriptionChange = useCallback(
+		(e: React.ChangeEvent<HTMLTextAreaElement>) => {
+			const val = e.target.value
+			setDescription(val)
+			triggerScore({ seoTitle, description: val, focusKeyword })
+		},
+		[seoTitle, focusKeyword, triggerScore],
+	)
+
+	const handleFocusKeywordChange = useCallback(
+		(e: React.ChangeEvent<HTMLInputElement>) => {
+			const val = e.target.value
+			setFocusKeyword(val)
+			triggerScore({ seoTitle, description, focusKeyword: val })
+		},
+		[seoTitle, description, triggerScore],
+	)
+
+	// PATCH on blur — persist to the backend.
+	const handleSeoTitleBlur = useCallback(async () => {
+		try {
+			await patchContent(docId, { seoTitle: seoTitle || null })
+			onChanged?.()
+		} catch {
+			// non-fatal
+		}
+	}, [docId, seoTitle, onChanged])
+
+	const handleDescriptionBlur = useCallback(async () => {
+		try {
+			await patchContent(docId, { description: description || null })
+			onChanged?.()
+		} catch {
+			// non-fatal
+		}
+	}, [docId, description, onChanged])
+
+	const handleFocusKeywordBlur = useCallback(async () => {
+		try {
+			await patchContent(docId, { seoFocusKeyword: focusKeyword || null })
+			onChanged?.()
+		} catch {
+			// non-fatal
+		}
+	}, [docId, focusKeyword, onChanged])
+
+	// Sync OG preview when hero url changes externally.
+	useEffect(() => setOgPreviewUrl(heroImageUrl), [heroImageUrl])
+
+	// OG image generate handler (P4 — live).
+	const handleGenerateOgImage = useCallback(async () => {
+		if (!docId || ogState === 'loading') return
+		setOgState('loading')
+		try {
+			const result = await generateOgImage(docId)
+			const state = ogButtonState(result.written, result.locked)
+			setOgState(state === 'idle' ? 'generated' : state)
+			setOgPreviewUrl(result.url)
+			onChanged?.()
+		} catch {
+			setOgState('error')
+		}
+	}, [docId, ogState, onChanged])
+
+	const summary = seoSummary(checks)
+	const ringGeom = score !== null ? scoreRingGeometry(score, 72) : null
+
+	// -------------------------------------------------------------------------
+	// Render
+	// -------------------------------------------------------------------------
+
+	return (
+		<div>
+			{/* Score section */}
+			<Section title="SEO score" icon="seo">
+				<div style={scoreWrap}>
+					{/* Ring */}
+					<div style={ringWrap}>
+						{ringGeom ? (
+							<svg
+								width={72}
+								height={72}
+								role="img"
+								aria-label={`SEO score: ${score ?? 0}`}
+								style={{ transform: 'rotate(-90deg)' }}
+							>
+								<circle
+									cx={36}
+									cy={36}
+									r={ringGeom.radius}
+									fill="none"
+									stroke="var(--hover)"
+									strokeWidth={8}
+								/>
+								<circle
+									cx={36}
+									cy={36}
+									r={ringGeom.radius}
+									fill="none"
+									stroke={ringColorVar(ringGeom.color)}
+									strokeWidth={8}
+									strokeLinecap="round"
+									strokeDasharray={ringGeom.circumference}
+									strokeDashoffset={ringGeom.dashOffset}
+									style={{ transition: 'stroke-dashoffset .3s ease' }}
+								/>
+							</svg>
+						) : (
+							<svg width={72} height={72} aria-hidden="true">
+								<circle cx={36} cy={36} r={28} fill="none" stroke="var(--hover)" strokeWidth={8} />
+							</svg>
+						)}
+						{/* Score label in the centre — rendered outside the rotated SVG */}
+						<div style={ringLabel}>
+							{scoring ? (
+								<span style={ringLabelText}>…</span>
+							) : score !== null ? (
+								<span style={ringLabelText}>{score}</span>
+							) : null}
+						</div>
+					</div>
+
+					{/* Verdict + passing count */}
+					<div style={scoreInfo}>
+						<div style={verdictLabel}>{summary.verdict}</div>
+						<div style={verdictSub}>
+							{summary.passing}/{summary.total} checks passing
+						</div>
+					</div>
+				</div>
+
+				{/* Checklist */}
+				{checks.length > 0 && (
+					<ul style={checkList}>
+						{checks.map((c) => (
+							<li key={c.id} style={checkItem}>
+								<span style={checkIcon(c.pass)}>
+									{c.pass ? <Icon name="checkCircle" size={13} /> : <Icon name="x" size={13} />}
+								</span>
+								<span style={checkBody}>
+									<span style={checkLabel(c.pass)}>{c.label}</span>
+									{!c.pass && <span style={checkHint}>{c.hint}</span>}
+								</span>
+							</li>
+						))}
+					</ul>
+				)}
+			</Section>
+
+			{/* Meta fields */}
+			<Section title="Meta fields" icon="search">
+				<Field label="Focus keyword" htmlFor="seo-focus-keyword">
+					<input
+						id="seo-focus-keyword"
+						className="input"
+						type="text"
+						value={focusKeyword}
+						placeholder="e.g. content marketing"
+						onChange={handleFocusKeywordChange}
+						onBlur={() => void handleFocusKeywordBlur()}
+					/>
+				</Field>
+
+				<Field
+					label="SEO title"
+					htmlFor="seo-title"
+					help="Overrides the page title in search results. Leave blank to use the content title."
+				>
+					<input
+						id="seo-title"
+						className="input"
+						type="text"
+						value={seoTitle}
+						placeholder={title}
+						maxLength={60}
+						onChange={handleSeoTitleChange}
+						onBlur={() => void handleSeoTitleBlur()}
+					/>
+					<div style={charCount(seoTitle.length, 60)}>{seoTitle.length}/60</div>
+				</Field>
+
+				<Field
+					label="Meta description"
+					htmlFor="seo-description"
+					help="Shown in search results. Aim for 50–160 characters."
+				>
+					<textarea
+						id="seo-description"
+						className="textarea"
+						value={description}
+						placeholder="A concise summary of this content…"
+						maxLength={160}
+						rows={3}
+						onChange={handleDescriptionChange}
+						onBlur={() => void handleDescriptionBlur()}
+					/>
+					<div style={charCount(description.length, 160)}>{description.length}/160</div>
+				</Field>
+			</Section>
+
+			{/* OG / social preview */}
+			<Section title="Social card preview" icon="globe">
+				<p style={ogHelp}>
+					Social image defaults to the hero image. Generate a custom social image only when you need
+					an override for sharing.
+				</p>
+				<div style={ogCard}>
+					{ogPreviewUrl ? (
+						<div style={ogImageWrap}>
+							<img src={ogPreviewUrl} alt="" style={ogImage} />
+						</div>
+					) : (
+						<div style={ogImagePlaceholder}>
+							<Icon name="image" size={22} style={{ color: 'var(--ink-faint)' }} />
+						</div>
+					)}
+					<div style={ogMeta}>
+						<div style={ogSiteName}>yoursite.com</div>
+						<div style={ogTitle}>{seoTitle || title || 'Untitled'}</div>
+						<div style={ogDesc}>{description || excerpt || 'No description yet.'}</div>
+					</div>
+				</div>
+
+				{ogState === 'locked' && <p style={lockedHint}>Field locked — AI cannot overwrite.</p>}
+				{ogState === 'error' && <p style={errorHint}>Generation failed. Try again.</p>}
+
+				{/* Generate button — enabled in P4. */}
+				<button
+					type="button"
+					className="btn sm"
+					style={{
+						width: '100%',
+						opacity: ogState === 'loading' ? 0.6 : 1,
+						cursor: ogState === 'loading' ? 'wait' : 'pointer',
+					}}
+					disabled={ogState === 'loading'}
+					onClick={() => void handleGenerateOgImage()}
+				>
+					<Icon name="sparkle" size={14} />
+					{ogState === 'loading'
+						? 'Generating…'
+						: ogState === 'generated'
+							? 'Regenerate custom social image'
+							: 'Generate custom social image'}
+				</button>
+			</Section>
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function ringColorVar(color: 'green' | 'amber' | 'red'): string {
+	switch (color) {
+		case 'green':
+			return 'var(--green, #22c55e)'
+		case 'amber':
+			return 'var(--amber, #f59e0b)'
+		case 'red':
+			return 'var(--red, #ef4444)'
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const scoreWrap: React.CSSProperties = {
+	display: 'flex',
+	alignItems: 'center',
+	gap: 16,
+	marginBottom: 16,
+}
+
+const ringWrap: React.CSSProperties = {
+	position: 'relative',
+	width: 72,
+	height: 72,
+	flexShrink: 0,
+}
+
+const ringLabel: React.CSSProperties = {
+	position: 'absolute',
+	inset: 0,
+	display: 'flex',
+	alignItems: 'center',
+	justifyContent: 'center',
+	pointerEvents: 'none',
+}
+
+const ringLabelText: React.CSSProperties = {
+	fontSize: 18,
+	fontWeight: 700,
+	color: 'var(--ink)',
+}
+
+const scoreInfo: React.CSSProperties = {
+	flex: 1,
+}
+
+const verdictLabel: React.CSSProperties = {
+	fontSize: 15,
+	fontWeight: 700,
+	color: 'var(--ink)',
+	marginBottom: 2,
+}
+
+const verdictSub: React.CSSProperties = {
+	fontSize: 12,
+	color: 'var(--ink-muted)',
+}
+
+const checkList: React.CSSProperties = {
+	listStyle: 'none',
+	margin: 0,
+	padding: 0,
+	display: 'flex',
+	flexDirection: 'column',
+	gap: 7,
+}
+
+const checkItem: React.CSSProperties = {
+	display: 'flex',
+	alignItems: 'flex-start',
+	gap: 8,
+}
+
+function checkIcon(pass: boolean): React.CSSProperties {
+	return {
+		color: pass ? 'var(--green, #22c55e)' : 'var(--ink-faint)',
+		flexShrink: 0,
+		marginTop: 1,
+	}
+}
+
+const checkBody: React.CSSProperties = {
+	display: 'flex',
+	flexDirection: 'column',
+	gap: 1,
+}
+
+function checkLabel(pass: boolean): React.CSSProperties {
+	return {
+		fontSize: 12.5,
+		fontWeight: 500,
+		color: pass ? 'var(--ink)' : 'var(--ink-muted)',
+	}
+}
+
+const checkHint: React.CSSProperties = {
+	fontSize: 11,
+	color: 'var(--ink-faint)',
+}
+
+function charCount(len: number, max: number): React.CSSProperties {
+	return {
+		fontSize: 10.5,
+		color: len > max * 0.9 ? 'var(--amber, #f59e0b)' : 'var(--ink-faint)',
+		textAlign: 'right' as const,
+		marginTop: 3,
+	}
+}
+
+const ogCard: React.CSSProperties = {
+	border: '1px solid var(--border)',
+	borderRadius: 8,
+	overflow: 'hidden',
+	marginBottom: 10,
+	background: 'var(--panel-2)',
+}
+
+const ogHelp: React.CSSProperties = {
+	margin: '0 0 10px',
+	fontSize: 11.5,
+	lineHeight: 1.45,
+	color: 'var(--ink-muted)',
+}
+
+const ogImageWrap: React.CSSProperties = {
+	height: 100,
+	overflow: 'hidden',
+}
+
+const ogImage: React.CSSProperties = {
+	width: '100%',
+	height: '100%',
+	objectFit: 'cover',
+}
+
+const ogImagePlaceholder: React.CSSProperties = {
+	height: 100,
+	display: 'flex',
+	alignItems: 'center',
+	justifyContent: 'center',
+	background: 'var(--field)',
+}
+
+const ogMeta: React.CSSProperties = {
+	padding: '10px 12px',
+}
+
+const ogSiteName: React.CSSProperties = {
+	fontSize: 10.5,
+	color: 'var(--ink-faint)',
+	marginBottom: 2,
+	textTransform: 'uppercase' as const,
+	letterSpacing: '0.04em',
+}
+
+const ogTitle: React.CSSProperties = {
+	fontSize: 13,
+	fontWeight: 600,
+	color: 'var(--ink)',
+	marginBottom: 3,
+	overflow: 'hidden',
+	textOverflow: 'ellipsis',
+	whiteSpace: 'nowrap' as const,
+}
+
+const ogDesc: React.CSSProperties = {
+	fontSize: 11.5,
+	color: 'var(--ink-muted)',
+	overflow: 'hidden',
+	display: '-webkit-box',
+	WebkitLineClamp: 2,
+	WebkitBoxOrient: 'vertical' as const,
+}
+
+const lockedHint: React.CSSProperties = {
+	fontSize: 11,
+	color: 'var(--amber, #f59e0b)',
+	margin: '0 0 6px',
+}
+
+const errorHint: React.CSSProperties = {
+	fontSize: 11,
+	color: 'var(--red, #ef4444)',
+	margin: '0 0 6px',
+}

package/src/ui/inspector/foundry-stages.ts

@@ -0,0 +1,140 @@
+// src/ui/inspector/foundry-stages.ts — pure pipeline stage helpers for the Foundry tab.
+//
+// processingStages(processingState, type) maps the 7-state machine to an ordered
+// stage list the design renders:
+//   Source uploaded → Transcode / normalize → Transcript → Thumbnail / chapters
+//
+// Each entry is { label, done, active, error? } — driven by the current
+// processing_state value.
+//
+// foundryPillState(state) → 'working' | 'ready' | 'failed'
+//   Collapses the 7 states into a display pill bucket for the tab header.
+//
+// Pure — no DOM, no React, fully vitest-testable.
+
+import type { ProcessingState } from '../../engine/foundry-dispatch.js'
+
+// ---------------------------------------------------------------------------
+// Stage entry
+// ---------------------------------------------------------------------------
+
+export interface StageEntry {
+	/** Human-readable stage label. */
+	label: string
+	/** Approximate duration shown to editors while the pipeline is active. */
+	estimate: string
+	/** True when this stage has completed successfully. */
+	done: boolean
+	/** True when this is the currently-executing stage. */
+	active: boolean
+	/** True when this stage encountered an error (only set for 'failed' state). */
+	error?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Stage definitions
+// ---------------------------------------------------------------------------
+
+// The pipeline executes in order: source fetch → transcript → transcode → thumbnail.
+// (The state machine is: queued → fetching → transcribing → transcoding → ready.)
+// Stage indices map 1:1 to the processing pipeline execution order.
+const STAGE_SOURCE = 0 // queued / fetching
+const STAGE_TRANSCRIPT = 1 // transcribing
+const STAGE_TRANSCODE = 2 // transcoding
+const _STAGE_THUMBNAIL = 3 // finalising / thumbnail / chapters (reached at ready); not referenced in switch
+
+const STAGE_LABELS = [
+	'Source uploaded',
+	'Transcript',
+	'Transcode / normalize',
+	'Thumbnail / chapters',
+]
+
+const STAGE_ESTIMATES = ['1-5 min', '5-20 min', '10-45 min', '2-10 min']
+
+/**
+ * Map a processing_state value to the ordered stage list the Foundry tab renders.
+ *
+ * State → stage progress:
+ *   pending      → all pending (not yet dispatched)
+ *   queued       → source stage active
+ *   fetching     → source stage active
+ *   transcribing → source done, transcript stage active
+ *   transcoding  → source + transcript done, transcode active
+ *   ready        → all done
+ *   failed       → no active stage, error flag on first stage (conservative)
+ */
+export function processingStages(
+	processingState: ProcessingState,
+	_type: 'video' | 'podcast' | string,
+): StageEntry[] {
+	const stages: StageEntry[] = STAGE_LABELS.map((label, index) => ({
+		label,
+		estimate: STAGE_ESTIMATES[index] ?? '',
+		done: false,
+		active: false,
+	}))
+
+	switch (processingState) {
+		case 'pending':
+			// Nothing done yet — all stages pending, none active
+			break
+
+		case 'queued':
+		case 'fetching':
+			// Source is being fetched / item is queued
+			stages[STAGE_SOURCE].active = true
+			break
+
+		case 'transcribing':
+			// Source has been fetched; now generating transcript
+			stages[STAGE_SOURCE].done = true
+			stages[STAGE_TRANSCRIPT].active = true
+			break
+
+		case 'transcoding':
+			// Transcript done; now transcoding media
+			stages[STAGE_SOURCE].done = true
+			stages[STAGE_TRANSCRIPT].done = true
+			stages[STAGE_TRANSCODE].active = true
+			break
+
+		case 'ready':
+			// All stages complete
+			for (const s of stages) {
+				s.done = true
+			}
+			break
+
+		case 'failed': {
+			// No stage is active. Surface the error on the source stage
+			// (conservative — the real error text is in processing_error).
+			stages[STAGE_SOURCE].error = true
+			break
+		}
+
+		default:
+			break
+	}
+
+	return stages
+}
+
+// ---------------------------------------------------------------------------
+// Pill state
+// ---------------------------------------------------------------------------
+
+export type FoundryPillState = 'working' | 'ready' | 'failed'
+
+/**
+ * Collapse the 7-value processing_state into a 3-bucket display pill state.
+ *
+ *   pending / queued / fetching / transcribing / transcoding → 'working'
+ *   ready → 'ready'
+ *   failed → 'failed'
+ */
+export function foundryPillState(state: ProcessingState): FoundryPillState {
+	if (state === 'ready') return 'ready'
+	if (state === 'failed') return 'failed'
+	return 'working'
+}