@growth-labs/cms 0.4.0 → 0.5.1

package/src/ui/editor/ContentForm.tsx

@@ -18,7 +18,7 @@
 //
 // Compile-gated: all Tiptap/React usage verified by `pnpm run build` (tsc).
 
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useId, useRef, useState } from 'react'
 import { countWords, estimateReadTime } from '../../engine/publisher.js'
 import type { ContentStatus, ContentType } from '../../schema/types.js'
 import { Icon } from '../icons.js'
@@ -31,8 +31,10 @@ import {
 	type ContentDraftFields,
 	canCreateContentDraft,
 	foundryDispatchSourceForDraft,
+	normalizeMediaDurationSeconds,
 	slugifyTitle,
 } from './content-payload.js'
+import { measureEditorMediaDurationSeconds } from './editor-media-duration.js'
 import { uploadEditorImage } from './editor-media-upload.js'
 import { Rte } from './Rte.js'
 import { docToMarkdown } from './serialize.js'
@@ -115,6 +117,7 @@ interface ExistingContentPayload {
 	processing_source_kind?: string | null
 	transcript?: string | null
 	audio_r2_key?: string | null
+	duration_seconds?: number | null
 }
 
 interface ExistingContentResponse {
@@ -147,6 +150,7 @@ interface FormState {
 	thumbnailUploadStatus: 'idle' | 'uploading' | 'staged'
 	thumbnailUploadError: string | null
 	audioUrl: string
+	durationSeconds: number | null
 	audioUploadStatus: 'idle' | 'uploading' | 'staged'
 	audioUploadError: string | null
 	videoUploadStatus: 'idle' | 'uploading' | 'staged'
@@ -191,6 +195,7 @@ function createEmptyFormState(docId: string | null): FormState {
 		thumbnailUploadStatus: 'idle',
 		thumbnailUploadError: null,
 		audioUrl: '',
+		durationSeconds: null,
 		audioUploadStatus: 'idle',
 		audioUploadError: null,
 		videoUploadStatus: 'idle',
@@ -284,7 +289,17 @@ export function ContentForm({
 		async (id: string, draft: ContentDraftFields) => {
 			const source = foundryDispatchSourceForDraft(contentType, draft)
 			if (!source) return
-			const queueKey = `${contentType}:${id}:${source}`
+			const durationSeconds = normalizeMediaDurationSeconds(draft.durationSeconds)
+			if (durationSeconds === null) {
+				setForm((prev) => ({
+					...prev,
+					videoPipelineStatus: 'idle',
+					videoPipelineError:
+						'Enter the authoritative media duration in whole seconds before queueing.',
+				}))
+				return
+			}
+			const queueKey = `${contentType}:${id}:${source}:${durationSeconds}`
 			if (queuedVideoSources.current.has(queueKey)) return
 
 			setForm((prev) => ({
@@ -326,9 +341,14 @@ export function ContentForm({
 
 			if (id === null) {
 				if (!canCreateContentDraft(contentType, draft)) {
+					const mediaSource = foundryDispatchSourceForDraft(contentType, draft)
+					const missingMediaDuration =
+						mediaSource && normalizeMediaDurationSeconds(draft.durationSeconds) === null
 					setForm((prev) => ({
 						...prev,
-						saveError: 'Add the required title and content before saving.',
+						saveError: missingMediaDuration
+							? 'Enter the authoritative media duration in whole seconds before saving.'
+							: 'Add the required title and content before saving.',
 					}))
 					return
 				}
@@ -490,6 +510,7 @@ export function ContentForm({
 		const next = {
 			...latestForm.current,
 			videoUrl: value,
+			durationSeconds: null,
 			videoSourceKind: null,
 			videoId: null,
 			videoPipelineStatus: 'idle' as const,
@@ -501,7 +522,28 @@ export function ContentForm({
 	}
 
 	function handleAudioUrlChange(value: string) {
-		const next = { ...latestForm.current, audioUrl: value }
+		const next = {
+			...latestForm.current,
+			audioUrl: value,
+			durationSeconds: null,
+			videoPipelineStatus: 'idle' as const,
+			videoPipelineError: null,
+		}
+		setForm(next)
+		publishDraft(next)
+		scheduleAutosave(next)
+	}
+
+	function handleDurationSecondsChange(value: string) {
+		const parsed = value.trim() === '' ? null : Number(value)
+		const durationSeconds =
+			typeof parsed === 'number' && Number.isInteger(parsed) && parsed > 0 ? parsed : null
+		const next = {
+			...latestForm.current,
+			durationSeconds,
+			videoPipelineStatus: 'idle' as const,
+			videoPipelineError: null,
+		}
 		setForm(next)
 		publishDraft(next)
 		scheduleAutosave(next)
@@ -546,17 +588,24 @@ export function ContentForm({
 				videoPipelineError: null,
 			}))
 			try {
+				const measuredDurationSeconds = await measureEditorMediaDurationSeconds(file, 'video')
 				const uploaded = await uploadMediaAsset({
 					kind: 'video',
 					file,
 					slug: baseSlug || undefined,
+					durationSeconds: measuredDurationSeconds,
 				})
 				if (!uploaded.url) throw new Error('Video upload did not return a source URL')
+				const durationSeconds = normalizeMediaDurationSeconds(uploaded.durationSeconds)
+				if (durationSeconds === null) {
+					throw new Error('Video upload did not return its verified duration')
+				}
 				const next = {
 					...latestForm.current,
 					videoUrl: uploaded.url,
 					videoSourceKind: uploaded.sourceKind ?? 'http_url',
 					videoId: uploaded.videoId ?? baseSlug,
+					durationSeconds,
 					videoUploadStatus: 'staged' as const,
 					videoUploadError: null,
 					videoPipelineStatus: 'idle' as const,
@@ -656,14 +705,21 @@ export function ContentForm({
 				audioUploadError: null,
 			}))
 			try {
+				const measuredDurationSeconds = await measureEditorMediaDurationSeconds(file, 'audio')
 				const uploaded = await uploadMediaAsset({
 					kind: 'podcast',
 					file,
 					slug: baseSlug || undefined,
+					durationSeconds: measuredDurationSeconds,
 				})
+				const durationSeconds = normalizeMediaDurationSeconds(uploaded.durationSeconds)
+				if (durationSeconds === null) {
+					throw new Error('Podcast upload did not return its verified duration')
+				}
 				const next = {
 					...latestForm.current,
 					audioUrl: uploaded.id,
+					durationSeconds,
 					audioUploadStatus: 'staged' as const,
 					audioUploadError: null,
 				}
@@ -774,7 +830,9 @@ export function ContentForm({
 					<div style={mediaBlockStack}>
 						<VideoBlock
 							videoUrl={form.videoUrl}
+							durationSeconds={form.durationSeconds}
 							onVideoUrlChange={handleVideoUrlChange}
+							onDurationSecondsChange={handleDurationSecondsChange}
 							onVideoFileUpload={handleVideoFileUpload}
 							uploadStatus={form.videoUploadStatus}
 							uploadError={form.videoUploadError}
@@ -801,7 +859,9 @@ export function ContentForm({
 					<div style={mediaBlockStack}>
 						<AudioBlock
 							audioUrl={form.audioUrl}
+							durationSeconds={form.durationSeconds}
 							onAudioUrlChange={handleAudioUrlChange}
+							onDurationSecondsChange={handleDurationSecondsChange}
 							onAudioFileUpload={handleAudioFileUpload}
 							uploadStatus={form.audioUploadStatus}
 							uploadError={form.audioUploadError}
@@ -975,7 +1035,9 @@ function ImageAssetBlock({
 
 function VideoBlock({
 	videoUrl,
+	durationSeconds,
 	onVideoUrlChange,
+	onDurationSecondsChange,
 	onVideoFileUpload,
 	uploadStatus,
 	uploadError,
@@ -983,7 +1045,9 @@ function VideoBlock({
 	pipelineError,
 }: {
 	videoUrl: string
+	durationSeconds: number | null
 	onVideoUrlChange: (url: string) => void
+	onDurationSecondsChange: (value: string) => void
 	onVideoFileUpload: (file: File) => void | Promise<void>
 	uploadStatus: 'idle' | 'uploading' | 'staged'
 	uploadError: string | null
@@ -1038,6 +1102,11 @@ function VideoBlock({
 				style={urlInput}
 				aria-label="Video source URL"
 			/>
+			<MediaDurationField
+				durationSeconds={durationSeconds}
+				onChange={onDurationSecondsChange}
+				hasSource={videoUrl.trim().length > 0}
+			/>
 
 			<div style={videoActions}>
 				<label className="btn sm" style={uploadButton}>
@@ -1072,7 +1141,9 @@ function VideoBlock({
 
 function AudioBlock({
 	audioUrl,
+	durationSeconds,
 	onAudioUrlChange,
+	onDurationSecondsChange,
 	onAudioFileUpload,
 	uploadStatus,
 	uploadError,
@@ -1080,7 +1151,9 @@ function AudioBlock({
 	pipelineError,
 }: {
 	audioUrl: string
+	durationSeconds: number | null
 	onAudioUrlChange: (url: string) => void
+	onDurationSecondsChange: (value: string) => void
 	onAudioFileUpload: (file: File) => void | Promise<void>
 	uploadStatus: 'idle' | 'uploading' | 'staged'
 	uploadError: string | null
@@ -1169,6 +1242,11 @@ function AudioBlock({
 				style={urlInput}
 				aria-label="Audio R2 Key"
 			/>
+			<MediaDurationField
+				durationSeconds={durationSeconds}
+				onChange={onDurationSecondsChange}
+				hasSource={audioUrl.trim().length > 0}
+			/>
 
 			<div style={assetHelp}>Only paste a key manually if the audio already exists in R2.</div>
 
@@ -1180,6 +1258,43 @@ function AudioBlock({
 	)
 }
 
+function MediaDurationField({
+	durationSeconds,
+	onChange,
+	hasSource,
+}: {
+	durationSeconds: number | null
+	onChange: (value: string) => void
+	hasSource: boolean
+}) {
+	const inputId = useId()
+
+	return (
+		<>
+			<label htmlFor={inputId} style={assetLabel}>
+				Media duration (seconds)
+			</label>
+			<input
+				id={inputId}
+				type="number"
+				min={1}
+				step={1}
+				value={durationSeconds ?? ''}
+				onChange={(event) => onChange(event.currentTarget.value)}
+				style={urlInput}
+				aria-label="Media duration in seconds"
+			/>
+			<div style={assetHelp}>
+				Uploads are measured automatically and rounded up. For a pasted source URL or R2 key, enter
+				its authoritative whole-second duration.
+			</div>
+			{hasSource && durationSeconds === null && (
+				<div style={videoErrorText}>Duration is required before this source can be queued.</div>
+			)}
+		</>
+	)
+}
+
 const PODCAST_UPLOAD_HELP =
 	'Large audio files can take a few minutes to upload; keep this tab open until the Audio R2 Key appears.'
 
@@ -1225,6 +1340,7 @@ function contentResponseToFormState(
 		next.videoUrl = toStringValue(content.processing_source_url)
 		next.videoSourceKind = toNullableString(content.processing_source_kind)
 		next.videoId = toNullableString(content.video_id)
+		next.durationSeconds = normalizeMediaDurationSeconds(content.duration_seconds)
 		next.thumbnailImageId = thumbnailImageId
 		next.thumbnailImageUrl =
 			thumbnailImageUrl || (thumbnailImageId ? mediaUrlFromId(thumbnailImageId) : null)
@@ -1233,6 +1349,7 @@ function contentResponseToFormState(
 	if (contentType === 'podcast') {
 		next.body = toStringValue(content.transcript)
 		next.audioUrl = toStringValue(content.audio_r2_key)
+		next.durationSeconds = normalizeMediaDurationSeconds(content.duration_seconds)
 	}
 
 	return next

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

@@ -11,6 +11,12 @@ export interface ContentDraftFields {
 	heroImageId?: string | null
 	thumbnailImageId?: string | null
 	audioUrl: string
+	durationSeconds: number | null
+}
+
+export function normalizeMediaDurationSeconds(value: unknown): number | null {
+	if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return null
+	return Math.ceil(value)
 }
 
 export function slugifyTitle(title: string): string {
@@ -31,8 +37,18 @@ export function canCreateContentDraft(
 	if (contentType === 'article' || contentType === 'newsletter' || contentType === 'page') {
 		return draft.body.trim().length > 0
 	}
-	if (contentType === 'video') return draft.videoUrl.trim().length > 0
-	if (contentType === 'podcast') return draft.audioUrl.trim().length > 0
+	if (contentType === 'video') {
+		return (
+			draft.videoUrl.trim().length > 0 &&
+			normalizeMediaDurationSeconds(draft.durationSeconds) !== null
+		)
+	}
+	if (contentType === 'podcast') {
+		return (
+			draft.audioUrl.trim().length > 0 &&
+			normalizeMediaDurationSeconds(draft.durationSeconds) !== null
+		)
+	}
 	return false
 }
 
@@ -95,6 +111,7 @@ export function buildContentUpdatePayload(
 		payload.content = {
 			script: '',
 			videoId,
+			durationSeconds: normalizeMediaDurationSeconds(draft.durationSeconds),
 			...(thumbnailImageId ? { thumbnailImageId } : {}),
 			...(sourceUrl
 				? {
@@ -107,6 +124,7 @@ export function buildContentUpdatePayload(
 		payload.content = {
 			transcript: '',
 			audioR2Key: draft.audioUrl,
+			durationSeconds: normalizeMediaDurationSeconds(draft.durationSeconds),
 		}
 	}
 

package/src/ui/editor/editor-media-duration.ts

@@ -0,0 +1,75 @@
+export type EditorMediaKind = 'video' | 'audio'
+
+export interface MediaMetadataElement {
+	preload: string
+	src: string
+	readonly duration: number
+	addEventListener(type: 'loadedmetadata' | 'error', listener: () => void): void
+	removeEventListener(type: 'loadedmetadata' | 'error', listener: () => void): void
+	load(): void
+	removeAttribute(name: 'src'): void
+}
+
+interface MediaDurationDependencies {
+	createMediaElement?: (kind: EditorMediaKind) => MediaMetadataElement
+	createObjectURL?: (file: File) => string
+	revokeObjectURL?: (url: string) => void
+	timeoutMs?: number
+}
+
+const DEFAULT_METADATA_TIMEOUT_MS = 15_000
+
+/**
+ * Measure a selected local media file before upload. Fractional container
+ * durations are rounded up so the integer dispatch contract never understates
+ * the source runtime. No fallback estimate is permitted.
+ */
+export async function measureEditorMediaDurationSeconds(
+	file: File,
+	kind: EditorMediaKind,
+	dependencies: MediaDurationDependencies = {},
+): Promise<number> {
+	const createMediaElement =
+		dependencies.createMediaElement ??
+		((mediaKind: EditorMediaKind) => document.createElement(mediaKind) as MediaMetadataElement)
+	const createObjectURL =
+		dependencies.createObjectURL ?? ((value: File) => URL.createObjectURL(value))
+	const revokeObjectURL =
+		dependencies.revokeObjectURL ?? ((url: string) => URL.revokeObjectURL(url))
+	const timeoutMs = dependencies.timeoutMs ?? DEFAULT_METADATA_TIMEOUT_MS
+	const media = createMediaElement(kind)
+	const objectUrl = createObjectURL(file)
+	let timeout: ReturnType<typeof setTimeout> | null = null
+	let onLoadedMetadata: (() => void) | null = null
+	let onError: (() => void) | null = null
+
+	try {
+		return await new Promise<number>((resolve, reject) => {
+			onLoadedMetadata = () => {
+				const duration = media.duration
+				if (!Number.isFinite(duration) || duration <= 0) {
+					reject(new Error('Selected media must expose a positive finite duration'))
+					return
+				}
+				resolve(Math.ceil(duration))
+			}
+			onError = () => reject(new Error('Could not read duration metadata from selected media'))
+
+			media.addEventListener('loadedmetadata', onLoadedMetadata)
+			media.addEventListener('error', onError)
+			timeout = setTimeout(() => {
+				reject(new Error('Timed out reading duration metadata from selected media'))
+			}, timeoutMs)
+			media.preload = 'metadata'
+			media.src = objectUrl
+			media.load()
+		})
+	} finally {
+		if (timeout) clearTimeout(timeout)
+		if (onLoadedMetadata) media.removeEventListener('loadedmetadata', onLoadedMetadata)
+		if (onError) media.removeEventListener('error', onError)
+		media.removeAttribute('src')
+		media.load()
+		revokeObjectURL(objectUrl)
+	}
+}

package/src/ui/screens/MediaScreen.tsx

@@ -25,8 +25,9 @@
 // the auto-fill tile grid uses inline `display: grid` exactly as the prototype.
 
 import { useCallback, useEffect, useReducer, useRef, useState } from 'react'
+import { measureEditorMediaDurationSeconds } from '../editor/editor-media-duration.js'
 import { Icon, type IconName } from '../icons.js'
-import { type MediaUploadKind, type MediaUploadResult, uploadMediaAsset } from './media-upload.js'
+import { type MediaUploadResult, uploadMediaAsset } from './media-upload.js'
 
 // ---------------------------------------------------------------------------
 // Kind filter — maps to the listLibrary `type` query param
@@ -146,7 +147,17 @@ export function MediaScreen() {
 		setUploadError(null)
 		setLastUpload(null)
 		try {
-			const result = await uploadMediaAsset({ kind: kind as MediaUploadKind, file })
+			const result =
+				kind === 'image'
+					? await uploadMediaAsset({ kind, file })
+					: await uploadMediaAsset({
+							kind,
+							file,
+							durationSeconds: await measureEditorMediaDurationSeconds(
+								file,
+								kind === 'video' ? 'video' : 'audio',
+							),
+						})
 			setLastUpload(result)
 			await fetchLibrary(kind)
 		} catch (err) {

package/src/ui/screens/media-upload.ts

@@ -3,6 +3,7 @@ export type MediaUploadKind = 'image' | 'video' | 'podcast'
 export interface MediaUploadResult {
 	id: string
 	url: string | null
+	durationSeconds?: number
 	sourceKind?: string | null
 	processingStatus?: string | null
 	videoId?: string | null
@@ -10,13 +11,22 @@ export interface MediaUploadResult {
 
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>
 
-interface UploadMediaAssetInput {
-	kind: MediaUploadKind
+interface BaseUploadMediaAssetInput {
 	file: File
 	slug?: string
 	fetchImpl?: FetchLike
 }
 
+type UploadMediaAssetInput =
+	| (BaseUploadMediaAssetInput & {
+			kind: 'image'
+			durationSeconds?: never
+	  })
+	| (BaseUploadMediaAssetInput & {
+			kind: 'video' | 'podcast'
+			durationSeconds: number
+	  })
+
 interface VideoInitResponse {
 	uploadId?: string
 	key?: string
@@ -36,6 +46,7 @@ interface VideoCompleteResponse {
 	sourceKind?: string
 	processingStatus?: string
 	videoId?: string
+	durationSeconds?: number
 }
 
 interface AudioInitResponse {
@@ -54,6 +65,20 @@ interface AudioPartResponse {
 interface AudioCompleteResponse {
 	key?: string
 	publicUrl?: string
+	durationSeconds?: number
+}
+
+function requirePositiveIntegerDuration(input: { durationSeconds?: unknown }): number {
+	const durationSeconds = input.durationSeconds
+	if (
+		typeof durationSeconds !== 'number' ||
+		!Number.isFinite(durationSeconds) ||
+		!Number.isInteger(durationSeconds) ||
+		durationSeconds <= 0
+	) {
+		throw new Error('Media upload requires a positive integer duration')
+	}
+	return durationSeconds
 }
 
 export function buildMediaUploadSlug(fileName: string): string {
@@ -118,6 +143,7 @@ export async function uploadMediaAsset(input: UploadMediaAssetInput): Promise<Me
 	}
 
 	if (input.kind === 'podcast') {
+		const durationSeconds = requirePositiveIntegerDuration(input)
 		if (input.file.size <= 0) {
 			throw new Error('Podcast audio file is empty')
 		}
@@ -133,6 +159,7 @@ export async function uploadMediaAsset(input: UploadMediaAssetInput): Promise<Me
 					fileName: input.file.name,
 					contentType: input.file.type || null,
 					sizeBytes: input.file.size,
+					durationSeconds,
 				}),
 			})
 			const init = await assertOk<AudioInitResponse>(
@@ -177,6 +204,7 @@ export async function uploadMediaAsset(input: UploadMediaAssetInput): Promise<Me
 					fileName: input.file.name,
 					contentType: input.file.type || null,
 					sizeBytes: input.file.size,
+					durationSeconds,
 					parts,
 				}),
 			})
@@ -184,9 +212,13 @@ export async function uploadMediaAsset(input: UploadMediaAssetInput): Promise<Me
 				completeResponse,
 				'Could not complete podcast audio upload',
 			)
+			if (complete.durationSeconds !== durationSeconds) {
+				throw new Error('Podcast upload did not preserve the measured duration')
+			}
 			return {
 				id: complete.key || key,
 				url: complete.publicUrl || null,
+				durationSeconds,
 			}
 		} catch (error) {
 			if (uploadId && key) {
@@ -200,6 +232,7 @@ export async function uploadMediaAsset(input: UploadMediaAssetInput): Promise<Me
 		}
 	}
 
+	const durationSeconds = requirePositiveIntegerDuration(input)
 	if (input.file.size <= 0) {
 		throw new Error('Video file is empty')
 	}
@@ -215,6 +248,7 @@ export async function uploadMediaAsset(input: UploadMediaAssetInput): Promise<Me
 				fileName: input.file.name,
 				contentType: input.file.type || null,
 				sizeBytes: input.file.size,
+				durationSeconds,
 			}),
 		})
 		const init = await assertOk<VideoInitResponse>(initResponse, 'Could not start video upload')
@@ -256,6 +290,7 @@ export async function uploadMediaAsset(input: UploadMediaAssetInput): Promise<Me
 				fileName: input.file.name,
 				contentType: input.file.type || null,
 				sizeBytes: input.file.size,
+				durationSeconds,
 				parts,
 			}),
 		})
@@ -263,12 +298,16 @@ export async function uploadMediaAsset(input: UploadMediaAssetInput): Promise<Me
 			completeResponse,
 			'Could not complete video upload',
 		)
+		if (complete.durationSeconds !== durationSeconds) {
+			throw new Error('Video upload did not preserve the measured duration')
+		}
 		return {
 			id: complete.key || key,
 			url: complete.sourceUrl || null,
 			sourceKind: complete.sourceKind || 'http_url',
 			processingStatus: complete.processingStatus || 'processing',
 			videoId: complete.videoId || slug,
+			durationSeconds,
 		}
 	} catch (error) {
 		if (uploadId && key) {