@duffcloudservices/cms 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duffcloudservices/cms",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Vue 3 composables and Vite plugins for DCS CMS integration",
   "type": "module",
   "exports": {
@@ -27,7 +27,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src/components"
+    "src/components",
+    "src/composables"
   ],
   "scripts": {
     "build": "tsup",

package/src/composables/index.ts

@@ -0,0 +1,4 @@
+export { useTextContent } from './useTextContent'
+export { useSEO, createSiteSEO } from './useSEO'
+export { useReleaseNotes } from './useReleaseNotes'
+export { useSiteVersion } from './useSiteVersion'

package/src/composables/useMediaCarousel.ts

@@ -0,0 +1,158 @@
+/**
+ * useMediaCarousel Composable
+ *
+ * Extracts media carousel items from text content keys following the pattern:
+ * `{prefix}.{N}.url`, `{prefix}.{N}.type`, `{prefix}.{N}.alt`
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useTextContent, useMediaCarousel } from '@duffcloudservices/cms'
+ *
+ * const { t } = useTextContent({
+ *   pageSlug: 'bio-mackenzie',
+ *   defaults: {
+ *     'hero.media-carousel.0.url': '/images/staff/mackenzie.webp',
+ *     'hero.media-carousel.0.type': 'image',
+ *     'hero.media-carousel.0.alt': 'Mackenzie Kowalick',
+ *     'hero.media-carousel.1.url': '/videos/intro.mp4',
+ *     'hero.media-carousel.1.type': 'video',
+ *     'hero.media-carousel.1.alt': 'Introduction video',
+ *   }
+ * })
+ *
+ * const { items } = useMediaCarousel({
+ *   prefix: 'hero.media-carousel',
+ *   t,
+ *   defaults: [
+ *     { url: '/images/staff/mackenzie.webp', type: 'image', alt: 'Mackenzie Kowalick' }
+ *   ]
+ * })
+ * </script>
+ *
+ * <template>
+ *   <MediaCarousel :items="items" />
+ * </template>
+ * ```
+ */
+
+import { computed, type ComputedRef } from 'vue'
+import { isCdnAssetUrl } from '@duffcloudservices/cms-core'
+
+/**
+ * Media carousel item representing an image, video, or embed
+ */
+export interface MediaCarouselItem {
+  /** URL to the image, video file, or embed URL */
+  url: string
+  /** Type of media: 'image', 'video' (direct file), 'youtube', or 'instagram' */
+  type: 'image' | 'video' | 'youtube' | 'instagram'
+  /** Accessibility alt text */
+  alt?: string
+  /**
+   * Whether this image has responsive CDN variants available.
+   * Automatically set to `true` when the URL matches the DCS CDN asset pattern.
+   * Components rendering the carousel should use `<ResponsiveImage>` when this is `true`.
+   */
+  responsive?: boolean
+}
+
+/**
+ * Configuration for useMediaCarousel composable
+ */
+export interface UseMediaCarouselConfig {
+  /** Key prefix for carousel items (e.g., 'hero.media-carousel') */
+  prefix: string
+  /** The t() function from useTextContent */
+  t: (key: string, fallback?: string) => string
+  /** Default items to use if no content keys are found */
+  defaults?: MediaCarouselItem[]
+  /** Maximum number of items to look for (default: 10) */
+  maxItems?: number
+}
+
+/**
+ * Return type for useMediaCarousel composable
+ */
+export interface UseMediaCarouselReturn {
+  /** Computed array of media carousel items */
+  items: ComputedRef<MediaCarouselItem[]>
+  /** Whether any items were found from content keys */
+  hasItems: ComputedRef<boolean>
+  /** Number of items in the carousel */
+  count: ComputedRef<number>
+}
+
+/**
+ * Extract media carousel items from text content keys.
+ *
+ * Looks for keys in the format:
+ * - `{prefix}.{N}.url` - Required URL for the media
+ * - `{prefix}.{N}.type` - Type: 'image' or 'video' (defaults to 'image')
+ * - `{prefix}.{N}.alt` - Alt text for accessibility
+ *
+ * Items are sorted by index (0, 1, etc.) and only included if they have a valid URL.
+ *
+ * @param config - Configuration object
+ * @returns Media carousel helpers and state
+ */
+export function useMediaCarousel(config: UseMediaCarouselConfig): UseMediaCarouselReturn {
+  const {
+    prefix,
+    t,
+    defaults = [],
+    maxItems = 10,
+  } = config
+
+  const items = computed<MediaCarouselItem[]>(() => {
+    const result: MediaCarouselItem[] = []
+
+    // Look for items from 0 to maxItems
+    for (let i = 0; i < maxItems; i++) {
+      const urlKey = `${prefix}.${i}.url`
+      const typeKey = `${prefix}.${i}.type`
+      const altKey = `${prefix}.${i}.alt`
+
+      // Use a sentinel value to detect if the key exists
+      const url = t(urlKey, '')
+      
+      // Skip if no URL (key doesn't exist or is empty)
+      if (!url || url === urlKey) {
+        continue
+      }
+
+      const typeValue = t(typeKey, 'image')
+      // Parse type value - support image, video, youtube, instagram
+      let type: 'image' | 'video' | 'youtube' | 'instagram' = 'image'
+      if (typeValue === 'video') type = 'video'
+      else if (typeValue === 'youtube') type = 'youtube'
+      else if (typeValue === 'instagram') type = 'instagram'
+      const alt = t(altKey, '')
+
+      result.push({
+        url,
+        type,
+        alt: alt && alt !== altKey ? alt : undefined,
+        // Flag CDN-hosted images as responsive so carousel components
+        // can render them with <ResponsiveImage> automatically
+        responsive: type === 'image' && isCdnAssetUrl(url),
+      })
+    }
+
+    // If no items found from content keys, use defaults
+    if (result.length === 0) {
+      return defaults
+    }
+
+    return result
+  })
+
+  const hasItems = computed(() => items.value.length > 0)
+  const count = computed(() => items.value.length)
+
+  return {
+    items,
+    hasItems,
+    count,
+  }
+}

package/src/composables/useReleaseNotes.ts

@@ -0,0 +1,153 @@
+/**
+ * useReleaseNotes Composable
+ *
+ * Fetches and displays versioned release notes from the DCS Portal API.
+ * Supports fetching specific versions or the latest release.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useReleaseNotes } from '@duffcloudservices/cms'
+ * import { useRoute } from 'vue-router'
+ *
+ * const route = useRoute()
+ * const version = route.params.version as string || 'latest'
+ *
+ * const { releaseNote, isLoading, error } = useReleaseNotes(version)
+ * </script>
+ *
+ * <template>
+ *   <div v-if="isLoading">Loading...</div>
+ *   <div v-else-if="error">{{ error }}</div>
+ *   <article v-else-if="releaseNote">
+ *     <h1>{{ releaseNote.title }}</h1>
+ *     <p>{{ releaseNote.summary }}</p>
+ *     <div v-html="renderedMarkdown" />
+ *   </article>
+ * </template>
+ * ```
+ */
+
+import { ref, onMounted } from 'vue'
+import type { ReleaseNote, ReleaseNotesReturn } from '../types/release-notes'
+
+/**
+ * Get environment variable value.
+ */
+function getEnvVar(key: string, defaultValue = ''): string {
+  try {
+    if (typeof import.meta !== 'undefined' && import.meta.env) {
+      const value = (import.meta.env as Record<string, string | undefined>)[key]
+      if (value !== undefined) return value
+    }
+  } catch {
+    // import.meta not available
+  }
+  return defaultValue
+}
+
+// Simple cache for release notes
+const releaseNotesCache = new Map<string, { data: ReleaseNote; expiresAt: number }>()
+const CACHE_TTL = 5 * 60 * 1000 // 5 minutes
+
+/**
+ * useReleaseNotes composable for fetching release notes from the DCS API.
+ *
+ * @param version - Semantic version (e.g., "1.2.0") or "latest"
+ * @param options - Optional configuration
+ * @returns Release notes data and state
+ */
+export function useReleaseNotes(
+  version: string,
+  options: { fetchOnMount?: boolean } = {}
+): ReleaseNotesReturn {
+  const { fetchOnMount = true } = options
+
+  const apiBaseUrl = getEnvVar('VITE_API_BASE_URL', 'https://portal.duffcloudservices.com')
+  const siteSlug = getEnvVar('VITE_SITE_SLUG', '')
+
+  const releaseNote = ref<ReleaseNote | null>(null)
+  const isLoading = ref(false)
+  const error = ref<string | null>(null)
+
+  async function fetchReleaseNotes(): Promise<void> {
+    if (!siteSlug) {
+      error.value = 'VITE_SITE_SLUG environment variable not set'
+      return
+    }
+
+    // Check cache
+    const cacheKey = `${siteSlug}:${version}`
+    const cached = releaseNotesCache.get(cacheKey)
+    if (cached && cached.expiresAt > Date.now()) {
+      releaseNote.value = cached.data
+      return
+    }
+
+    isLoading.value = true
+    error.value = null
+
+    try {
+      const url = `${apiBaseUrl}/api/v1/sites/${siteSlug}/release-notes/${version}`
+      const response = await fetch(url, {
+        headers: {
+          Accept: 'application/json',
+        },
+      })
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          error.value = `Release notes for version ${version} not found`
+          return
+        }
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+      }
+
+      const data = await response.json()
+
+      // Normalize the response
+      const note: ReleaseNote = {
+        version: data.version,
+        title: data.title,
+        summary: data.summary || '',
+        notesMarkdown: data.notesMarkdown || data.notes || '',
+        changeCount: data.changeCount || 0,
+        releaseDate: data.releaseDate || data.releasedAt || '',
+      }
+
+      // Cache the result
+      releaseNotesCache.set(cacheKey, {
+        data: note,
+        expiresAt: Date.now() + CACHE_TTL,
+      })
+
+      releaseNote.value = note
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to load release notes'
+      console.error('[@duffcloudservices/cms] Failed to fetch release notes:', e)
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  async function refresh(): Promise<void> {
+    // Clear cache
+    const cacheKey = `${siteSlug}:${version}`
+    releaseNotesCache.delete(cacheKey)
+    await fetchReleaseNotes()
+  }
+
+  // Fetch on mount if enabled
+  if (fetchOnMount && typeof window !== 'undefined') {
+    onMounted(() => {
+      fetchReleaseNotes()
+    })
+  }
+
+  return {
+    releaseNote,
+    isLoading,
+    error,
+    refresh,
+  }
+}

package/src/composables/useResponsiveImage.ts

@@ -0,0 +1,85 @@
+/**
+ * Vue 3 composable that resolves responsive image variants for DCS CDN-hosted assets.
+ *
+ * Wraps the framework-agnostic `resolveResponsiveImage` from `@duffcloudservices/cms-core`
+ * with reactive Vue refs so it can be used directly in `<script setup>` blocks.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useResponsiveImage } from '@duffcloudservices/cms'
+ *
+ * const hero = useResponsiveImage({
+ *   src: 'https://files.duffcloudservices.com/kept/assets/hero/abc-123.jpg',
+ *   alt: 'Hero image',
+ *   context: 'hero',
+ * })
+ * </script>
+ *
+ * <template>
+ *   <picture v-if="hero.hasVariants">
+ *     <source
+ *       v-for="source in hero.sources"
+ *       :key="source.type"
+ *       :srcset="source.srcset"
+ *       :type="source.type"
+ *       :sizes="source.sizes"
+ *     />
+ *     <img v-bind="hero.imgProps" class="w-full h-full object-cover" />
+ *   </picture>
+ *   <img v-else v-bind="hero.imgProps" class="w-full h-full object-cover" />
+ * </template>
+ * ```
+ */
+
+import { computed, type MaybeRefOrGetter, toValue } from 'vue'
+import {
+  resolveResponsiveImage,
+  type ImageContext,
+  type ResponsiveImageResult,
+} from '@duffcloudservices/cms-core'
+
+export interface UseResponsiveImageOptions {
+  /** Source URL — can be a reactive ref, getter, or plain string. */
+  src: MaybeRefOrGetter<string>
+  /** Alt text — can be a reactive ref, getter, or plain string. */
+  alt: MaybeRefOrGetter<string>
+  /** Sizing context — determines which variants to include. */
+  context?: MaybeRefOrGetter<ImageContext | undefined>
+  /** Optional `sizes` attribute override. */
+  sizes?: MaybeRefOrGetter<string | undefined>
+  /** Skip variant resolution and use the original URL only. */
+  original?: MaybeRefOrGetter<boolean | undefined>
+}
+
+/**
+ * Reactively resolves responsive image metadata for a DCS CDN URL.
+ *
+ * The returned object is a computed ref that recomputes whenever any
+ * of the input refs change. Spread `imgProps` onto an `<img>` or
+ * combine with `sources` inside a `<picture>` element.
+ */
+export function useResponsiveImage(options: UseResponsiveImageOptions): ResponsiveImageResult {
+  const result = computed(() =>
+    resolveResponsiveImage({
+      src: toValue(options.src),
+      alt: toValue(options.alt),
+      context: toValue(options.context),
+      sizes: toValue(options.sizes),
+      original: toValue(options.original) ?? undefined,
+    }),
+  )
+
+  // Return a reactive proxy that delegates to the computed
+  return {
+    get imgProps() {
+      return result.value.imgProps
+    },
+    get sources() {
+      return result.value.sources
+    },
+    get hasVariants() {
+      return result.value.hasVariants
+    },
+  }
+}

package/src/composables/useSEO.ts

@@ -0,0 +1,387 @@
+/**
+ * useSEO Composable
+ *
+ * Provides SEO configuration with build-time injection support from .dcs/seo.yaml.
+ * Generates meta tags, Open Graph, Twitter Cards, and JSON-LD structured data.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useSEO } from '@duffcloudservices/cms'
+ *
+ * const { applyHead, getSchema, config } = useSEO('home')
+ *
+ * // Apply all meta tags
+ * applyHead()
+ *
+ * // Or customize before applying
+ * applyHead({
+ *   title: 'Custom Override Title',
+ *   schemas: [...getSchema(), customSchema]
+ * })
+ * </script>
+ * ```
+ */
+
+import { computed, type ComputedRef } from 'vue'
+import { useHead } from '@unhead/vue'
+import type {
+  SeoConfiguration,
+  GlobalSeoConfig,
+  SeoOpenGraphConfig,
+  SeoTwitterConfig,
+  SeoSchemaConfig,
+  ResolvedPageSeo,
+  UseSeoReturn,
+  HeadOverrides,
+} from '../types/seo'
+
+// Declare the global injected by dcsSeoPlugin
+declare const __DCS_SEO__: SeoConfiguration | undefined
+
+/**
+ * Safely get build-time SEO configuration.
+ * Returns undefined if not available (no seo.yaml or plugin not configured).
+ */
+function getBuildTimeSeo(): SeoConfiguration | undefined {
+  try {
+    if (typeof __DCS_SEO__ !== 'undefined' && __DCS_SEO__ !== null) {
+      return __DCS_SEO__
+    }
+  } catch {
+    // __DCS_SEO__ not defined - that's fine, use defaults
+  }
+  return undefined
+}
+
+// =============================================================================
+// Meta Tag Generation Utilities
+// =============================================================================
+
+interface HeadInput {
+  title?: string
+  titleTemplate?: string | ((title: string) => string)
+  meta?: Array<{ name?: string; property?: string; content: string }>
+  link?: Array<{ rel: string; href: string; hreflang?: string }>
+  script?: Array<{ type: string; children: string }>
+}
+
+/**
+ * Generate Open Graph meta tags from config
+ */
+function generateOpenGraphMeta(
+  og: SeoOpenGraphConfig,
+  global: GlobalSeoConfig,
+  pageTitle: string,
+  pageDescription: string,
+  canonical: string
+): Array<{ property: string; content: string }> {
+  const tags: Array<{ property: string; content: string }> = []
+
+  tags.push({ property: 'og:title', content: og.title || pageTitle })
+  tags.push({ property: 'og:description', content: og.description || pageDescription })
+  tags.push({ property: 'og:url', content: og.url || canonical })
+  tags.push({ property: 'og:type', content: og.type || 'website' })
+
+  const image = og.image || global.images?.ogDefault
+  if (image) {
+    tags.push({ property: 'og:image', content: image })
+    if (og.imageAlt || pageTitle) {
+      tags.push({ property: 'og:image:alt', content: og.imageAlt || pageTitle })
+    }
+    if (og.imageWidth) {
+      tags.push({ property: 'og:image:width', content: String(og.imageWidth) })
+    }
+    if (og.imageHeight) {
+      tags.push({ property: 'og:image:height', content: String(og.imageHeight) })
+    }
+  }
+
+  if (global.siteName) {
+    tags.push({ property: 'og:site_name', content: global.siteName })
+  }
+
+  if (global.locale) {
+    tags.push({ property: 'og:locale', content: global.locale })
+  }
+
+  // Article-specific tags
+  if (og.type === 'article') {
+    if (og.publishedTime) {
+      tags.push({ property: 'article:published_time', content: og.publishedTime })
+    }
+    if (og.modifiedTime) {
+      tags.push({ property: 'article:modified_time', content: og.modifiedTime })
+    }
+    if (og.author) {
+      tags.push({ property: 'article:author', content: og.author })
+    }
+    if (og.section) {
+      tags.push({ property: 'article:section', content: og.section })
+    }
+    if (og.tags) {
+      og.tags.forEach((tag) => {
+        tags.push({ property: 'article:tag', content: tag })
+      })
+    }
+  }
+
+  return tags
+}
+
+/**
+ * Generate Twitter Card meta tags from config
+ */
+function generateTwitterMeta(
+  twitter: SeoTwitterConfig,
+  global: GlobalSeoConfig,
+  pageTitle: string,
+  pageDescription: string
+): Array<{ name: string; content: string }> {
+  const tags: Array<{ name: string; content: string }> = []
+
+  tags.push({ name: 'twitter:card', content: twitter.card || 'summary_large_image' })
+  tags.push({ name: 'twitter:title', content: twitter.title || pageTitle })
+  tags.push({ name: 'twitter:description', content: twitter.description || pageDescription })
+
+  const image = twitter.image || global.images?.twitterDefault
+  if (image) {
+    tags.push({ name: 'twitter:image', content: image })
+    if (twitter.imageAlt || pageTitle) {
+      tags.push({ name: 'twitter:image:alt', content: twitter.imageAlt || pageTitle })
+    }
+  }
+
+  const site = twitter.site || global.social?.twitter
+  if (site) {
+    tags.push({ name: 'twitter:site', content: site.startsWith('@') ? site : `@${site}` })
+  }
+
+  if (twitter.creator) {
+    tags.push({
+      name: 'twitter:creator',
+      content: twitter.creator.startsWith('@') ? twitter.creator : `@${twitter.creator}`,
+    })
+  }
+
+  return tags
+}
+
+/**
+ * Generate JSON-LD script content from schemas
+ */
+function generateJsonLd(schemas: SeoSchemaConfig[], global: GlobalSeoConfig): object[] {
+  return schemas.map((schema) => {
+    const base: Record<string, unknown> = {
+      '@context': 'https://schema.org',
+      '@type': schema.type,
+    }
+
+    // Merge properties
+    if (schema.properties) {
+      Object.assign(base, schema.properties)
+    }
+
+    // Auto-populate common properties from global config
+    if (schema.type === 'WebSite' && global.siteUrl && !base.url) {
+      base.url = global.siteUrl
+    }
+    if (schema.type === 'WebSite' && global.siteName && !base.name) {
+      base.name = global.siteName
+    }
+
+    return base
+  })
+}
+
+/**
+ * Resolve page SEO by merging global defaults with page-specific config
+ */
+function resolvePageSeo(
+  pageSlug: string,
+  pagePath: string | undefined,
+  seoConfig: SeoConfiguration | undefined
+): ResolvedPageSeo {
+  const global = seoConfig?.global ?? {}
+  const page = seoConfig?.pages?.[pageSlug] ?? {}
+
+  // Build canonical URL
+  let canonical = page.canonical || ''
+  if (!canonical && global.siteUrl) {
+    const path = pagePath ?? (pageSlug === 'home' ? '/' : `/${pageSlug}`)
+    canonical = `${global.siteUrl.replace(/\/$/, '')}${path}`
+  }
+
+  // Build title
+  let title = page.title || global.defaultTitle || pageSlug
+  if (!page.noTitleTemplate && global.titleTemplate) {
+    title = global.titleTemplate.replace('%s', title)
+  }
+
+  // Merge Open Graph
+  const openGraph: ResolvedPageSeo['openGraph'] = {
+    type: page.openGraph?.type || 'website',
+    title: page.openGraph?.title || page.title || global.defaultTitle || '',
+    description: page.openGraph?.description || page.description || global.defaultDescription || '',
+    ...page.openGraph,
+  }
+
+  // Merge Twitter
+  const twitter: ResolvedPageSeo['twitter'] = {
+    card: page.twitter?.card || 'summary_large_image',
+    ...page.twitter,
+  }
+
+  // Combine schemas (global + page)
+  const schemas = [...(global.schemas ?? []), ...(page.schemas ?? [])]
+
+  return {
+    title,
+    description: page.description || global.defaultDescription || '',
+    canonical,
+    robots: page.robots || global.robots || 'index, follow',
+    openGraph,
+    twitter,
+    schemas,
+    alternates: page.alternates ?? [],
+  }
+}
+
+/**
+ * useSEO composable for DCS-managed SEO configuration.
+ *
+ * @param pageSlug - Page slug matching entry in seo.yaml
+ * @param pagePath - Optional page path for canonical URL generation
+ * @returns SEO helpers and state
+ */
+export function useSEO(pageSlug: string, pagePath?: string): UseSeoReturn {
+  const seoConfig = getBuildTimeSeo()
+  const hasBuildTimeSeo = seoConfig !== undefined
+
+  // Computed resolved config
+  const config: ComputedRef<ResolvedPageSeo> = computed(() =>
+    resolvePageSeo(pageSlug, pagePath, seoConfig)
+  )
+
+  /**
+   * Get JSON-LD schema objects for the page
+   */
+  function getSchema(): object[] {
+    return generateJsonLd(config.value.schemas, seoConfig?.global ?? {})
+  }
+
+  /**
+   * Get canonical URL for the page
+   */
+  function getCanonical(): string {
+    return config.value.canonical
+  }
+
+  /**
+   * Apply all meta tags via useHead
+   */
+  function applyHead(overrides?: HeadOverrides): void {
+    const resolved = config.value
+    const global = seoConfig?.global ?? {}
+
+    const title = overrides?.title ?? resolved.title
+    const description = overrides?.description ?? resolved.description
+
+    // Build meta tags
+    const meta: HeadInput['meta'] = []
+
+    // Basic meta
+    meta.push({ name: 'description', content: description })
+    if (resolved.robots) {
+      meta.push({ name: 'robots', content: resolved.robots })
+    }
+
+    // Verification codes
+    if (global.verification?.google) {
+      meta.push({ name: 'google-site-verification', content: global.verification.google })
+    }
+    if (global.verification?.bing) {
+      meta.push({ name: 'msvalidate.01', content: global.verification.bing })
+    }
+
+    // Open Graph
+    const ogMeta = generateOpenGraphMeta(
+      resolved.openGraph,
+      global,
+      title,
+      description,
+      resolved.canonical
+    )
+    meta.push(...ogMeta.map((t) => ({ property: t.property, content: t.content })))
+
+    // Twitter
+    const twitterMeta = generateTwitterMeta(resolved.twitter, global, title, description)
+    meta.push(...twitterMeta.map((t) => ({ name: t.name, content: t.content })))
+
+    // Additional overrides
+    if (overrides?.meta) {
+      meta.push(...overrides.meta)
+    }
+
+    // Build links
+    const link: HeadInput['link'] = []
+
+    // Canonical
+    if (resolved.canonical) {
+      link.push({ rel: 'canonical', href: resolved.canonical })
+    }
+
+    // Alternate languages
+    resolved.alternates.forEach((alt) => {
+      link.push({ rel: 'alternate', href: alt.href, hreflang: alt.hreflang })
+    })
+
+    // Build scripts (JSON-LD)
+    const schemas = overrides?.schemas ?? getSchema()
+    const script: HeadInput['script'] = schemas.map((schema) => ({
+      type: 'application/ld+json',
+      children: JSON.stringify(schema),
+    }))
+
+    // Apply via useHead
+    useHead({
+      title,
+      meta,
+      link,
+      script,
+    })
+  }
+
+  return {
+    config,
+    applyHead,
+    getSchema,
+    getCanonical,
+    hasBuildTimeSeo,
+  }
+}
+
+/**
+ * Create a typed useSEO function with site-specific defaults.
+ * Useful for creating a site-wide wrapper.
+ *
+ * @example
+ * ```ts
+ * // composables/useSiteSeo.ts
+ * import { createSiteSEO } from '@duffcloudservices/cms'
+ *
+ * export const useSiteSeo = createSiteSEO({
+ *   siteName: 'My Site',
+ *   siteUrl: 'https://example.com'
+ * })
+ * ```
+ */
+export function createSiteSEO(
+  _siteDefaults: Partial<GlobalSeoConfig>
+): (pageSlug: string, pagePath?: string) => UseSeoReturn {
+  return function siteUseSEO(pageSlug: string, pagePath?: string): UseSeoReturn {
+    // Note: siteDefaults would be used if we needed to override at runtime
+    // but build-time injection handles this via dcsSeoPlugin
+    return useSEO(pageSlug, pagePath)
+  }
+}

package/src/composables/useSiteVersion.ts

@@ -0,0 +1,123 @@
+/**
+ * useSiteVersion Composable
+ *
+ * Gets the current site version for footer badges and version displays.
+ * Fetches the latest release version from the DCS Portal API.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useSiteVersion } from '@duffcloudservices/cms'
+ *
+ * const { version, releaseNotesUrl } = useSiteVersion()
+ * </script>
+ *
+ * <template>
+ *   <footer>
+ *     <a v-if="version" :href="releaseNotesUrl" class="version-badge">
+ *       v{{ version }}
+ *     </a>
+ *   </footer>
+ * </template>
+ * ```
+ */
+
+import { ref, computed, onMounted } from 'vue'
+import type { SiteVersionReturn } from '../types/release-notes'
+
+/**
+ * Get environment variable value.
+ */
+function getEnvVar(key: string, defaultValue = ''): string {
+  try {
+    if (typeof import.meta !== 'undefined' && import.meta.env) {
+      const value = (import.meta.env as Record<string, string | undefined>)[key]
+      if (value !== undefined) return value
+    }
+  } catch {
+    // import.meta not available
+  }
+  return defaultValue
+}
+
+// Cache for site version
+let versionCache: { version: string; expiresAt: number } | null = null
+const CACHE_TTL = 10 * 60 * 1000 // 10 minutes
+
+/**
+ * useSiteVersion composable for displaying the current site version.
+ *
+ * @param options - Optional configuration
+ * @returns Site version data and computed URL
+ */
+export function useSiteVersion(options: { fetchOnMount?: boolean } = {}): SiteVersionReturn {
+  const { fetchOnMount = true } = options
+
+  const apiBaseUrl = getEnvVar('VITE_API_BASE_URL', 'https://portal.duffcloudservices.com')
+  const siteSlug = getEnvVar('VITE_SITE_SLUG', '')
+
+  const version = ref<string | null>(null)
+  const isLoading = ref(false)
+
+  const releaseNotesUrl = computed(() => {
+    if (!version.value) return '/releaseNotes/latest'
+    return `/releaseNotes/${version.value}`
+  })
+
+  async function fetchVersion(): Promise<void> {
+    if (!siteSlug) {
+      return
+    }
+
+    // Check cache
+    if (versionCache && versionCache.expiresAt > Date.now()) {
+      version.value = versionCache.version
+      return
+    }
+
+    isLoading.value = true
+
+    try {
+      // Fetch the latest release notes to get the version
+      const url = `${apiBaseUrl}/api/v1/sites/${siteSlug}/release-notes/latest`
+      const response = await fetch(url, {
+        headers: {
+          Accept: 'application/json',
+        },
+      })
+
+      if (!response.ok) {
+        // No release notes yet - that's fine
+        return
+      }
+
+      const data = await response.json()
+      const latestVersion = data.version
+
+      // Cache the result
+      versionCache = {
+        version: latestVersion,
+        expiresAt: Date.now() + CACHE_TTL,
+      }
+
+      version.value = latestVersion
+    } catch (e) {
+      console.error('[@duffcloudservices/cms] Failed to fetch site version:', e)
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  // Fetch on mount if enabled
+  if (fetchOnMount && typeof window !== 'undefined') {
+    onMounted(() => {
+      fetchVersion()
+    })
+  }
+
+  return {
+    version,
+    isLoading,
+    releaseNotesUrl,
+  }
+}

package/src/composables/useTextContent.ts

@@ -0,0 +1,297 @@
+/**
+ * useTextContent Composable
+ *
+ * Provides text content management with build-time injection support and optional
+ * runtime API overrides for DCS-managed customer sites.
+ *
+ * Content resolution order:
+ * 1. Runtime API overrides (premium tier only, if mode is 'runtime')
+ * 2. Build-time content from .dcs/content.yaml (injected via dcsContentPlugin)
+ * 3. Hardcoded defaults passed to the composable
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useTextContent } from '@duffcloudservices/cms'
+ *
+ * const { t, isLoading, error } = useTextContent({
+ *   pageSlug: 'home',
+ *   defaults: {
+ *     'hero.title': 'Welcome to Our Site',
+ *     'hero.subtitle': 'Build something amazing',
+ *     'cta.primary': 'Get Started'
+ *   }
+ * })
+ * </script>
+ *
+ * <template>
+ *   <h1>{{ t('hero.title') }}</h1>
+ *   <p>{{ t('hero.subtitle') }}</p>
+ *   <button>{{ t('cta.primary') }}</button>
+ * </template>
+ * ```
+ */
+
+import { ref, computed, readonly, onMounted, type Ref } from 'vue'
+import type { DcsContentFile, TextContentConfig, TextContentReturn } from '../types/content'
+
+// Declare the global injected by dcsContentPlugin
+declare const __DCS_CONTENT__: DcsContentFile | undefined
+
+// Simple in-memory cache for runtime fetches
+const fetchCache = new Map<string, { data: Record<string, string>; expiresAt: number }>()
+
+/**
+ * Safely get build-time content configuration.
+ * Returns undefined if not available (no content.yaml or plugin not configured).
+ */
+function getBuildTimeContent(): DcsContentFile | undefined {
+  try {
+    if (typeof __DCS_CONTENT__ !== 'undefined' && __DCS_CONTENT__ !== null) {
+      return __DCS_CONTENT__
+    }
+  } catch {
+    // __DCS_CONTENT__ not defined - that's fine, use defaults
+  }
+  return undefined
+}
+
+/**
+ * Get build-time content for a specific page, merging global and page-specific content.
+ */
+function getBuildTimePageContent(pageSlug: string): Record<string, string> {
+  const content = getBuildTimeContent()
+  if (!content) return {}
+
+  const global = content.global ?? {}
+  const page = content.pages?.[pageSlug] ?? {}
+
+  return { ...global, ...page }
+}
+
+/**
+ * Get environment variable value, handling both Vite and process.env patterns.
+ */
+function getEnvVar(key: string, defaultValue = ''): string {
+  try {
+    // Vite pattern
+    if (typeof import.meta !== 'undefined' && import.meta.env) {
+      const value = (import.meta.env as Record<string, string | undefined>)[key]
+      if (value !== undefined) return value
+    }
+  } catch {
+    // import.meta not available
+  }
+
+  try {
+    // Node.js pattern
+    if (typeof process !== 'undefined' && process.env) {
+      const value = process.env[key]
+      if (value !== undefined) return value
+    }
+  } catch {
+    // process not available
+  }
+
+  return defaultValue
+}
+
+/**
+ * useTextContent composable for DCS-managed text content.
+ *
+ * @param config - Configuration object
+ * @returns Text content helpers and state
+ */
+export function useTextContent(config: TextContentConfig): TextContentReturn {
+  const {
+    pageSlug,
+    defaults,
+    fetchOnMount = true,
+    cacheKey,
+    cacheTtl = 60000,
+  } = config
+
+  // Get configuration from environment
+  const apiBaseUrl = getEnvVar('VITE_API_BASE_URL', '')
+  const siteSlug = getEnvVar('VITE_SITE_SLUG', '')
+  const textOverrideMode = getEnvVar('VITE_TEXT_OVERRIDE_MODE', 'commit')
+  const mode: 'commit' | 'runtime' = textOverrideMode === 'runtime' ? 'runtime' : 'commit'
+
+  // Get build-time content immediately (synchronous)
+  const buildTimeContent = getBuildTimePageContent(pageSlug)
+  const hasBuildTimeContent = Object.keys(buildTimeContent).length > 0
+
+  // State - initialize with build-time content
+  const overrides = ref<Record<string, string>>({ ...buildTimeContent })
+  const isLoading = ref(false)
+  const error = ref<string | null>(null)
+
+  // Computed merged texts (defaults + overrides)
+  const texts = computed(() => ({ ...defaults, ...overrides.value }))
+
+  /**
+   * Get text by key with optional fallback.
+   * Resolution order: overrides → defaults → fallback → key
+   */
+  function t(key: string, fallback?: string): string {
+    return overrides.value[key] ?? defaults[key] ?? fallback ?? key
+  }
+
+  /**
+   * Check if a key has an override (from build-time or runtime).
+   */
+  function hasOverride(key: string): boolean {
+    return key in overrides.value
+  }
+
+  /**
+   * Get an array of objects from indexed content keys.
+   * Useful for lists where keys follow the pattern: arrayKey.index.property
+   * Example: features.1.title, features.1.description, features.2.title, etc.
+   *
+   * @param arrayKey - The base key prefix (e.g., 'features', 'items')
+   * @returns Array of objects with properties extracted from matching keys, sorted by index
+   *
+   * @example
+   * ```ts
+   * // Given content keys:
+   * // positions.1.title = "Software Engineer"
+   * // positions.1.description = "Build cool stuff"
+   * // positions.2.title = "Designer"
+   * // positions.2.description = "Design cool stuff"
+   *
+   * const positions = getArray('positions')
+   * // Returns:
+   * // [
+   * //   { _index: 1, title: "Software Engineer", description: "Build cool stuff" },
+   * //   { _index: 2, title: "Designer", description: "Design cool stuff" }
+   * // ]
+   * ```
+   */
+  function getArray(arrayKey: string): Array<Record<string, unknown> & { _index: number }> {
+    const items: Record<number, Record<string, unknown> & { _index: number }> = {}
+    const source = { ...defaults, ...overrides.value }
+
+    Object.keys(source).forEach((key) => {
+      if (key.startsWith(`${arrayKey}.`)) {
+        const parts = key.split('.')
+        // Format: arrayKey.index.property (or arrayKey.index.nested.property)
+        // Example: features.1.title -> index=1, prop=title
+        if (parts.length >= 3) {
+          const index = Number.parseInt(parts[1], 10)
+          const prop = parts.slice(2).join('.')
+
+          if (!Number.isNaN(index)) {
+            if (!items[index]) items[index] = { _index: index }
+            items[index][prop] = source[key]
+          }
+        }
+      }
+    })
+
+    return Object.values(items).sort((a, b) => a._index - b._index)
+  }
+
+  /**
+   * Fetch runtime overrides from the API.
+   * Only runs if mode is 'runtime' and API is configured.
+   */
+  async function fetchOverrides(): Promise<void> {
+    // Skip API fetch in commit mode - use build-time content only
+    if (mode !== 'runtime') {
+      return
+    }
+
+    // Skip if API not configured
+    if (!apiBaseUrl || !siteSlug) {
+      console.warn(
+        '[@duffcloudservices/cms] Runtime mode enabled but VITE_API_BASE_URL or VITE_SITE_SLUG not set'
+      )
+      return
+    }
+
+    // Check cache first
+    const effectiveCacheKey = cacheKey ?? `${siteSlug}:${pageSlug}`
+    const cached = fetchCache.get(effectiveCacheKey)
+    if (cached && cached.expiresAt > Date.now()) {
+      overrides.value = { ...buildTimeContent, ...cached.data }
+      return
+    }
+
+    isLoading.value = true
+    error.value = null
+
+    try {
+      const url = `${apiBaseUrl}/api/v1/sites/${siteSlug}/pages/${pageSlug}/text`
+      const response = await fetch(url, {
+        headers: {
+          Accept: 'application/json',
+        },
+      })
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          // No overrides for this page - that's fine
+          return
+        }
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+      }
+
+      const data = await response.json()
+      const apiOverrides = data.overrides ?? data.texts ?? {}
+
+      // Cache the result
+      fetchCache.set(effectiveCacheKey, {
+        data: apiOverrides,
+        expiresAt: Date.now() + cacheTtl,
+      })
+
+      // Merge: build-time content is baseline, API overrides on top
+      overrides.value = { ...buildTimeContent, ...apiOverrides }
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to load text overrides'
+      console.error('[@duffcloudservices/cms] Failed to fetch text overrides:', e)
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  /**
+   * Manually refresh overrides.
+   * In commit mode, resets to build-time content.
+   * In runtime mode, fetches fresh data from API.
+   */
+  async function refresh(): Promise<void> {
+    if (mode !== 'runtime') {
+      // In commit mode, just reset to build-time content
+      overrides.value = { ...buildTimeContent }
+      return
+    }
+
+    // Clear cache for this key
+    const effectiveCacheKey = cacheKey ?? `${siteSlug}:${pageSlug}`
+    fetchCache.delete(effectiveCacheKey)
+
+    await fetchOverrides()
+  }
+
+  // Fetch on mount if enabled and in runtime mode (browser only)
+  if (fetchOnMount && mode === 'runtime' && globalThis.window !== undefined) {
+    onMounted(() => {
+      fetchOverrides()
+    })
+  }
+
+  return {
+    t,
+    getArray,
+    texts,
+    overrides,
+    isLoading: readonly(isLoading) as Ref<boolean>,
+    error: readonly(error) as Ref<string | null>,
+    refresh,
+    hasOverride,
+    hasBuildTimeContent,
+    mode,
+  }
+}