@duffcloudservices/cms 0.10.0 → 0.12.0

package/src/components/ManagedImage.vue

@@ -8,38 +8,82 @@ defineOptions({ inheritAttrs: false })
 
 const props = withDefaults(defineProps<{
   pageSlug: string
-  imageKey: string
+  imageKey?: string
   fallbackSrc: string
   altKey?: string
   fallbackAlt?: string
   context?: ImageContext
   sizes?: string
   original?: boolean
+  /**
+   * D1-A structured image base (Q-168=A): a single dot-suffix key group, e.g.
+   * `hero.image`, from which `.src` / `.alt` / `.width` / `.height` are read.
+   * When set it supersedes `imageKey`/`altKey`. The legacy two-key form keeps
+   * working forever for backward compatibility. The `.width`/`.height` values
+   * feed the CLS layout-shift hint; when they are absent no hint is emitted
+   * (never fabricated).
+   */
+  imageBase?: string
+  /**
+   * Explicit intrinsic dimensions — a fallback when no `.width`/`.height`
+   * content key exists (e.g. a static hero whose size is known at build time).
+   * Both must be positive to emit a hint.
+   */
+  width?: number
+  height?: number
 }>(), {
+  imageKey: '',
   altKey: '',
   fallbackAlt: '',
   context: 'content',
   sizes: undefined,
   original: false,
+  imageBase: '',
+  width: undefined,
+  height: undefined,
 })
 
+// Resolve the effective content keys. `imageBase` (D1-A) derives the four
+// dot-suffix keys; otherwise fall back to the legacy imageKey/altKey pair.
+const srcKey = computed(() => (props.imageBase ? `${props.imageBase}.src` : props.imageKey))
+const effectiveAltKey = computed(() => (props.imageBase ? `${props.imageBase}.alt` : props.altKey))
+const widthKey = computed(() => (props.imageBase ? `${props.imageBase}.width` : ''))
+const heightKey = computed(() => (props.imageBase ? `${props.imageBase}.height` : ''))
+
 const attrs = useAttrs()
 const { t } = useTextContent({
   pageSlug: props.pageSlug,
   defaults: {
-    [props.imageKey]: props.fallbackSrc,
-    ...(props.altKey ? { [props.altKey]: props.fallbackAlt } : {}),
+    ...(srcKey.value ? { [srcKey.value]: props.fallbackSrc } : {}),
+    ...(effectiveAltKey.value ? { [effectiveAltKey.value]: props.fallbackAlt } : {}),
+    ...(widthKey.value && props.width ? { [widthKey.value]: String(props.width) } : {}),
+    ...(heightKey.value && props.height ? { [heightKey.value]: String(props.height) } : {}),
   },
 })
 
-const imageSrc = computed(() => t(props.imageKey, props.fallbackSrc))
-const imageAlt = computed(() => (props.altKey ? t(props.altKey, props.fallbackAlt) : props.fallbackAlt))
+/** Parse a content value (always a string) into a positive integer, or undefined. */
+function toPositiveInt(value: string | undefined): number | undefined {
+  if (!value) return undefined
+  const n = Number.parseInt(value, 10)
+  return Number.isFinite(n) && n > 0 ? n : undefined
+}
+
+const imageSrc = computed(() => t(srcKey.value, props.fallbackSrc))
+const imageAlt = computed(() => (effectiveAltKey.value ? t(effectiveAltKey.value, props.fallbackAlt) : props.fallbackAlt))
+const imageWidth = computed(() =>
+  toPositiveInt(widthKey.value ? t(widthKey.value, '') : undefined) ?? (props.width && props.width > 0 ? props.width : undefined),
+)
+const imageHeight = computed(() =>
+  toPositiveInt(heightKey.value ? t(heightKey.value, '') : undefined) ?? (props.height && props.height > 0 ? props.height : undefined),
+)
 const image = useResponsiveImage({
   src: imageSrc,
   alt: imageAlt,
   context: () => props.context,
   sizes: () => props.sizes,
   original: () => props.original,
+  width: imageWidth,
+  height: imageHeight,
 })
 
 // Self-heal: a fit-variant (`-md`/`-lg`) may legitimately be absent when the
@@ -61,7 +105,10 @@ const imgAttrs = computed(() => ({
   // When a variant has failed, render the original (also exposed as
   // data-dcs-image-url for the visual editor) instead of the 404'd variant.
   ...(failed.value ? { src: imageSrc.value } : {}),
-  'data-dcs-image-key': props.imageKey,
+  // The VE stages a replacement against the SRC key (the key that holds the
+  // image URL), which is the dot-suffix `<base>.src` when imageBase is used,
+  // or the legacy imageKey otherwise.
+  'data-dcs-image-key': srcKey.value,
   'data-dcs-image-url': imageSrc.value,
   'data-dcs-image-alt': imageAlt.value,
 }))

package/src/composables/useMediaCarousel.ts

@@ -45,7 +45,12 @@ import { isCdnAssetUrl } from '@duffcloudservices/cms-core'
 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 of media: 'image', 'video' (direct file), 'youtube', or 'instagram'.
+   * Render `youtube`/`instagram` items through the click-to-load facade
+   * `LiteMediaEmbed` (`@duffcloudservices/cms/lite-media-embed`) so the heavy
+   * player iframe loads only on user interaction — never eagerly.
+   */
   type: 'image' | 'video' | 'youtube' | 'instagram'
   /** Accessibility alt text */
   alt?: string

package/src/composables/useResponsiveImage.ts

@@ -50,6 +50,10 @@ export interface UseResponsiveImageOptions {
   sizes?: MaybeRefOrGetter<string | undefined>
   /** Skip variant resolution and use the original URL only. */
   original?: MaybeRefOrGetter<boolean | undefined>
+  /** Intrinsic width — emitted as a layout-shift hint when paired with `height`. */
+  width?: MaybeRefOrGetter<number | undefined>
+  /** Intrinsic height — emitted as a layout-shift hint when paired with `width`. */
+  height?: MaybeRefOrGetter<number | undefined>
 }
 
 /**
@@ -67,6 +71,8 @@ export function useResponsiveImage(options: UseResponsiveImageOptions): Responsi
       context: toValue(options.context),
       sizes: toValue(options.sizes),
       original: toValue(options.original) ?? undefined,
+      width: toValue(options.width) ?? undefined,
+      height: toValue(options.height) ?? undefined,
     }),
   )
 

package/src/composables/useReviewContent.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { defineComponent, h } from 'vue'
+import { mount } from '@vue/test-utils'
+import { useReviewContent, type ReviewItem } from './useReviewContent'
+
+/**
+ * Honesty guard: consumer-supplied `defaults` (placeholder / sample reviews)
+ * are a DEV-ONLY affordance. In a production build the composable must render an
+ * honest empty state instead of fabricated social proof — this is the fix for
+ * the flagship SSR bug where a fabricated fallback was baked into the crawler
+ * HTML while the client showed the real reviews.
+ */
+
+const SAMPLE_DEFAULTS: ReviewItem[] = [
+  { id: 'seed-1', platform: 'google', rating: 5, authorName: 'Sample Person', text: 'Placeholder review' },
+]
+
+function mountReviews(config: Parameters<typeof useReviewContent>[0]) {
+  let api!: ReturnType<typeof useReviewContent>
+  const Comp = defineComponent({
+    setup() {
+      api = useReviewContent(config)
+      return () => h('div')
+    },
+  })
+  const wrapper = mount(Comp)
+  return { api, wrapper }
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+  delete (globalThis as Record<string, unknown>).__DCS_CONTENT__
+})
+
+describe('useReviewContent honesty guard', () => {
+  it('production build with no content define renders an empty state, NOT the defaults', () => {
+    vi.stubEnv('DEV', false)
+    // __DCS_CONTENT__ intentionally undefined (simulates a production SSR pass
+    // where the define never reached the composable / no curated reviews).
+    const { api, wrapper } = mountReviews({ sectionKey: 'testimonials', defaults: SAMPLE_DEFAULTS })
+
+    expect(api.reviews.value).toEqual([])
+    expect(api.hasReviews.value).toBe(false)
+    expect(api.count.value).toBe(0)
+    wrapper.unmount()
+  })
+
+  it('production build with no reviews for the section renders empty, NOT the defaults', () => {
+    vi.stubEnv('DEV', false)
+    vi.stubGlobal('__DCS_CONTENT__', { global: {}, pages: {} })
+    const { api, wrapper } = mountReviews({ sectionKey: 'testimonials', defaults: SAMPLE_DEFAULTS })
+
+    expect(api.reviews.value).toEqual([])
+    expect(api.hasReviews.value).toBe(false)
+    wrapper.unmount()
+  })
+
+  it('production build DOES render the real curated reviews from the content define', () => {
+    vi.stubEnv('DEV', false)
+    vi.stubGlobal('__DCS_CONTENT__', {
+      global: {
+        'reviews.testimonials.items': [
+          { id: 'real-1', platform: 'google', rating: 5, authorName: 'Real Reviewer', text: 'Genuine review' },
+        ],
+      },
+      pages: {},
+    })
+    const { api, wrapper } = mountReviews({ sectionKey: 'testimonials', defaults: SAMPLE_DEFAULTS })
+
+    expect(api.reviews.value).toHaveLength(1)
+    expect(api.reviews.value[0].authorName).toBe('Real Reviewer')
+    expect(api.hasReviews.value).toBe(true)
+    wrapper.unmount()
+  })
+
+  it('dev build still surfaces the sample defaults (DX affordance)', () => {
+    vi.stubEnv('DEV', true)
+    const { api, wrapper } = mountReviews({ sectionKey: 'testimonials', defaults: SAMPLE_DEFAULTS })
+
+    expect(api.reviews.value).toHaveLength(1)
+    expect(api.reviews.value[0].id).toBe('seed-1')
+    wrapper.unmount()
+  })
+})

package/src/composables/useReviewContent.ts

@@ -25,6 +25,38 @@ function withoutAuthorPhotos(items: ReviewItem[]): ReviewItem[] {
   }))
 }
 
+/**
+ * True only in a Vite dev build. Vite statically replaces `import.meta.env.DEV`
+ * with a boolean literal (`true` in dev, `false` in production). The
+ * `typeof import.meta` guard + try/catch keep this safe if the package is ever
+ * SSR-externalized (where `import.meta.env` is undefined at the Node runtime and
+ * accessing it would throw) — in that case we deliberately return `false` so the
+ * production-safe branch is taken.
+ */
+function isDevBuild(): boolean {
+  try {
+    if (typeof import.meta !== 'undefined' && import.meta.env) {
+      return import.meta.env.DEV === true
+    }
+  } catch {
+    // import.meta.env unavailable (externalized SSR / non-Vite host) → prod-safe.
+  }
+  return false
+}
+
+/**
+ * Honesty guard: consumer-supplied `defaults` are a DEV-ONLY affordance so a
+ * freshly-scaffolded site shows sample reviews while it is being wired up. In a
+ * production build they must NEVER render — an SSR production pass emitting
+ * placeholder reviews is exactly the fabricated-social-proof / hydration bug
+ * this guards against (the content define can be missing server-side if the cms
+ * package is SSR-externalized). Production therefore falls back to an honest
+ * empty state; real reviews always come from `.dcs/content.yaml`.
+ */
+function fallbackReviews(defaults: ReviewItem[]): ReviewItem[] {
+  return isDevBuild() ? withoutAuthorPhotos(defaults) : []
+}
+
 export interface UseReviewContentConfig {
   /** The section key matching the data-dcs-reviews attribute value */
   sectionKey: string
@@ -130,7 +162,7 @@ export function useReviewContent(config: UseReviewContentConfig): UseReviewConte
     }
 
     if (typeof __DCS_CONTENT__ === 'undefined' || __DCS_CONTENT__ == null) {
-      return withoutAuthorPhotos(defaults)
+      return fallbackReviews(defaults)
     }
 
     let reviewData: unknown = null
@@ -146,7 +178,7 @@ export function useReviewContent(config: UseReviewContentConfig): UseReviewConte
     }
 
     if (!reviewData || !Array.isArray(reviewData)) {
-      return withoutAuthorPhotos(defaults)
+      return fallbackReviews(defaults)
     }
 
     return normalizeReviewList(reviewData)

package/src/composables/useSiteVisitorSession.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { fetchSiteVisitorSession } from './useSiteVisitorSession'
+
+/**
+ * The anonymous session probe is the common case and MUST be silent — no
+ * console.error / console.warn — whether the server answers with the new
+ * `200 { visitor: null }` contract or an old server's `401`. A red console
+ * error on every signed-out page load is the console-noise this fixes.
+ */
+
+function installConsoleSpies() {
+  return {
+    error: vi.spyOn(console, 'error').mockImplementation(() => {}),
+    warn: vi.spyOn(console, 'warn').mockImplementation(() => {}),
+  }
+}
+
+function expectSilent(spies: ReturnType<typeof installConsoleSpies>) {
+  expect(spies.error).not.toHaveBeenCalled()
+  expect(spies.warn).not.toHaveBeenCalled()
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+describe('fetchSiteVisitorSession — anonymous probe is silent', () => {
+  it('new server 200 {visitor:null} → signed out, no console noise', async () => {
+    const spies = installConsoleSpies()
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({ ok: true, status: 200, json: async () => ({ visitor: null }) }),
+    )
+
+    const result = await fetchSiteVisitorSession()
+
+    expect(result.visitor).toBeNull()
+    expect(result.authenticated).toBe(false)
+    expectSilent(spies)
+  })
+
+  it('old server 401 → signed out, no console noise', async () => {
+    const spies = installConsoleSpies()
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 401,
+        json: async () => ({ error: 'Not authenticated' }),
+      }),
+    )
+
+    const result = await fetchSiteVisitorSession()
+
+    expect(result.visitor).toBeNull()
+    expect(result.authenticated).toBe(false)
+    expectSilent(spies)
+  })
+
+  it('network error → signed out, no console noise', async () => {
+    const spies = installConsoleSpies()
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('offline')))
+
+    const result = await fetchSiteVisitorSession()
+
+    expect(result.visitor).toBeNull()
+    expect(result.authenticated).toBe(false)
+    expectSilent(spies)
+  })
+})
+
+describe('fetchSiteVisitorSession — authenticated shapes', () => {
+  it('200 {visitor:{...}} → returns the visitor', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          visitor: { id: 'g-1', email: 'v@example.com', name: 'Visitor', createdAt: '2026-01-01T00:00:00Z' },
+        }),
+      }),
+    )
+
+    const result = await fetchSiteVisitorSession()
+
+    expect(result.authenticated).toBe(true)
+    expect(result.visitor?.email).toBe('v@example.com')
+    expect(result.visitor?.name).toBe('Visitor')
+  })
+
+  it('contracts-spec shape {authenticated,user:{...}} → returns the visitor', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({ authenticated: true, user: { email: 'u@example.com', name: 'User' } }),
+      }),
+    )
+
+    const result = await fetchSiteVisitorSession()
+
+    expect(result.authenticated).toBe(true)
+    expect(result.visitor?.email).toBe('u@example.com')
+  })
+
+  it('probes the slug-free /site-auth/session path with credentials', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200, json: async () => ({ visitor: null }) })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await fetchSiteVisitorSession()
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchMock.mock.calls[0]
+    expect(url).toBe('/api/v1/site-auth/session')
+    expect(init.credentials).toBe('include')
+  })
+})

package/src/composables/useSiteVisitorSession.ts

@@ -0,0 +1,160 @@
+/**
+ * Site-visitor session probe client.
+ *
+ * Customer sites poll "who is signed in?" on load to render the right auth UI.
+ * Signed-out is the EXPECTED state for the vast majority of visits, so this
+ * client treats it as normal and never logs:
+ *
+ *  - New servers answer an anonymous probe with `200 { "visitor": null }`.
+ *  - Old servers (pre-fix) answer an anonymous probe with `401`.
+ *
+ * Sites bump `@duffcloudservices/cms` independently of server deploys, so this
+ * client must accept BOTH shapes and stay silent on the anonymous path — a
+ * `console.error`/`console.warn` on every signed-out page load is exactly the
+ * console-noise this fixes. A genuine signed-in visitor is returned as a
+ * normalized `SiteVisitor`; anything else resolves to `null`.
+ */
+import { ref, computed, onMounted, type Ref, type ComputedRef } from 'vue'
+
+/** A signed-in site visitor. */
+export interface SiteVisitor {
+  id?: string
+  email: string
+  name: string
+  picture?: string
+  createdAt?: string
+}
+
+export interface SiteVisitorSessionResult {
+  /** The signed-in visitor, or `null` when signed out. */
+  visitor: SiteVisitor | null
+  /** Convenience flag — `true` iff a visitor is present. */
+  authenticated: boolean
+}
+
+export interface FetchSiteVisitorSessionOptions {
+  /** API base (default `/api/v1`, same-origin via Front Door). */
+  apiBaseUrl?: string
+  /** Optional AbortSignal to cancel an in-flight probe. */
+  signal?: AbortSignal
+}
+
+const SIGNED_OUT: SiteVisitorSessionResult = { visitor: null, authenticated: false }
+
+const apiBase = (value?: string): string => (value ?? '/api/v1').replace(/\/$/u, '')
+
+/**
+ * Normalize the various session-response shapes into a `SiteVisitor | null`.
+ * Accepts the primary/legacy `{ visitor: {...} | null }` envelope and the
+ * contracts-spec `{ authenticated, user: {...} }` shape defensively.
+ */
+function extractVisitor(data: unknown): SiteVisitor | null {
+  if (!data || typeof data !== 'object') {
+    return null
+  }
+  const obj = data as Record<string, unknown>
+  const raw = obj.visitor ?? obj.user
+  if (!raw || typeof raw !== 'object') {
+    return null
+  }
+  const v = raw as Record<string, unknown>
+  const email = typeof v.email === 'string' ? v.email : ''
+  if (!email) {
+    return null
+  }
+  return {
+    id: typeof v.id === 'string' ? v.id : undefined,
+    email,
+    name: typeof v.name === 'string' ? v.name : email,
+    picture: typeof v.picture === 'string' ? v.picture : undefined,
+    createdAt: typeof v.createdAt === 'string' ? v.createdAt : undefined,
+  }
+}
+
+/**
+ * Fetch the current site-visitor session. Never throws and never logs for the
+ * anonymous case: any network error, non-OK status (incl. a legacy `401`), or
+ * `{ visitor: null }` body resolves to a signed-out result.
+ */
+export async function fetchSiteVisitorSession(
+  options: FetchSiteVisitorSessionOptions = {},
+): Promise<SiteVisitorSessionResult> {
+  const base = apiBase(options.apiBaseUrl)
+
+  let response: Response
+  try {
+    response = await fetch(`${base}/site-auth/session`, {
+      method: 'GET',
+      credentials: 'include',
+      headers: { Accept: 'application/json' },
+      signal: options.signal,
+    })
+  } catch {
+    // Network error / aborted / CORS — signed-out is the safe probe assumption.
+    return SIGNED_OUT
+  }
+
+  // Old servers reply 401 to an anonymous probe; new servers reply 200-null.
+  // Treat any non-OK status as signed-out WITHOUT logging.
+  if (!response.ok) {
+    return SIGNED_OUT
+  }
+
+  let data: unknown
+  try {
+    data = await response.json()
+  } catch {
+    return SIGNED_OUT
+  }
+
+  const visitor = extractVisitor(data)
+  return { visitor, authenticated: visitor !== null }
+}
+
+export interface UseSiteVisitorSessionOptions extends FetchSiteVisitorSessionOptions {
+  /** Probe automatically on mount (browser only). Default `true`. */
+  fetchOnMount?: boolean
+}
+
+export interface UseSiteVisitorSessionReturn {
+  /** The signed-in visitor, or `null` when signed out / not yet loaded. */
+  visitor: Ref<SiteVisitor | null>
+  /** `true` iff a visitor is present. */
+  isAuthenticated: ComputedRef<boolean>
+  /** `true` while a probe is in flight. */
+  isLoading: Ref<boolean>
+  /** Re-run the probe. */
+  refresh: () => Promise<void>
+}
+
+/**
+ * Vue composable wrapper around {@link fetchSiteVisitorSession}. Reactive
+ * `visitor` / `isAuthenticated` / `isLoading`, and probes on mount by default.
+ */
+export function useSiteVisitorSession(
+  options: UseSiteVisitorSessionOptions = {},
+): UseSiteVisitorSessionReturn {
+  const { fetchOnMount = true, ...fetchOptions } = options
+
+  const visitor = ref<SiteVisitor | null>(null)
+  const isLoading = ref(false)
+  const isAuthenticated = computed(() => visitor.value !== null)
+
+  async function refresh(): Promise<void> {
+    isLoading.value = true
+    try {
+      const result = await fetchSiteVisitorSession(fetchOptions)
+      visitor.value = result.visitor
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  if (fetchOnMount && typeof window !== 'undefined') {
+    onMounted(() => {
+      void refresh()
+    })
+  }
+
+  return { visitor, isAuthenticated, isLoading, refresh }
+}

package/dist/chunk-KCWMS7P4.js

@@ -1,3 +0,0 @@
-
-//# sourceMappingURL=chunk-KCWMS7P4.js.map
-//# sourceMappingURL=chunk-KCWMS7P4.js.map