Merge branch 'main' into feat/DC-153-request-replacement-card-flow

# Conflicts:
#	src/SEBT.Portal.Infrastructure/Repositories/MockHouseholdRepository.cs
#	src/SEBT.Portal.Web/src/features/household/api/schema.test.ts

Author: Nick Campanini

.claude/skills/qa/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: qa
+description: "Generate QA test summary from current branch changes for PR handoff"
+allowed-tools: Read, Grep, Glob, Bash, Write
+---
+
+# /qa - QA Test Summary Generator
+
+Generate a QA handoff document from the current branch's changes. Output should be ready to paste as a **Jira comment** on the ticket.
+
+**Write two versions of the output:**
+1. **`.claude/qa-summary.md`** — Markdown version with proper headings, bold, checkboxes, and code formatting. Useful for GitHub PRs or reference.
+2. **`.claude/qa-summary.txt`** — Plain text version following the Jira formatting rules below. This is the one that gets copied to clipboard.
+
+After writing both files, run `cat .claude/qa-summary.txt | pbcopy` to copy the Jira version to the clipboard. Tell the user: "Copied to clipboard — paste into Jira with Cmd+V. Markdown version also saved to `.claude/qa-summary.md`."
+
+## Instructions
+
+1. **Discover changes**: Diff against the branch's parent, not production. Run `git diff development --stat` and `git log development..HEAD --oneline` to see only what this branch adds. Also run `git diff HEAD --stat` to catch any uncommitted work.
+2. **Read changed files**: Read the key modified files to understand the actual changes, not just the diff stats
+3. **Identify scope**: Determine which features, pages, and components are affected
+4. **Generate test summary in plain text with light formatting.** The output will be pasted into Jira Cloud's rich text editor. Use this format:
+
+```
+QA Summary — [Branch Name]
+
+What Changed
+Brief 2-3 sentence description of the feature/fix.
+
+Affected Areas
+- All pages — page views and browser tab titles
+- Sign in / Sign out flow
+
+Test Cases
+
+Happy Path
+1. Step-by-step test case with expected result
+2. Another test case...
+
+Edge Cases
+1. Edge case scenario with expected behavior
+
+Regression Checks
+1. Verify [related feature] still works as expected
+
+Environment Notes
+- Environment setup needed
+- Which environments to test on
+```
+
+### Formatting rules — CRITICAL
+- Use plain text with simple numbered and bulleted lists
+- NO markdown syntax (no ##, no **, no backticks, no [ ] checkboxes)
+- NO Jira wiki markup (no h2., no *, no {{}}, no #)
+- Section headers should be plain text on their own line, in ALL CAPS or Title Case to stand out
+- Use dashes (-) for bullet lists and numbers (1. 2. 3.) for ordered lists
+- For inline code references like event names, just use quotes: "page_view", "sign_in"
+- For links, write the full URL on its own line
+
+## Key Behaviors
+- Focus on **user-facing behavior**, not implementation details
+- Test cases should be actionable by someone who didn't write the code
+- Use relative paths for navigation (e.g. "Navigate to Tools > Tag Generator"), never reference localhost or full URLs — QA knows their environment
+- Assume QA is already signed in and on the app unless the test specifically involves auth
+- Call out any data dependencies (specific campaigns, creatives, etc.)
+- If changes touch auth, API layer, or shared components, expand regression scope
+- Keep it concise — QA doesn't need to know about refactors or code style changes
+- Use checkboxes so QA can track completion
+
+## Language Rules — CRITICAL
+- **NEVER reference file names, paths, components, stores, functions, or code concepts.** QA does not read code.
+- Write everything in terms of **what the user sees and does in the browser** — pages, buttons, modals, fields, messages.
+- Instead of "interceptors.js tracks CRUD operations", say "Creating, editing, or deleting any item should be tracked"
+- Instead of "TableFilter.vue search is debounced", say "Type in a search bar, wait a second, and the search should be recorded"
+- Instead of "Affected: src/features/analytics/...", say "Affected: Analytics reports page"
+- The "Affected Areas" section should list **page names and UI areas**, not files or components
+- Environment Notes should only include things QA needs to configure or be aware of — no technical implementation details

.gitignore

@@ -444,6 +444,7 @@ FodyWeavers.xsd
 # AI
 CLAUDE.local.md
 .claude/settings.local.json
+.claude/qa-summary.*
 
 # Developer-local workflow artifacts (branch context, PR reviews, screenshots)
 docs/.local/

packages/analytics/src/DataLayerProvider.test.tsx

@@ -0,0 +1,130 @@
+import { act, render } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { DataLayer } from './data-layer'
+import { DataLayerProvider } from './DataLayerProvider'
+import type { RoutePageContextMap } from './DataLayerProvider'
+
+let mockPathname = '/dashboard'
+vi.mock('next/navigation', () => ({
+  usePathname: () => mockPathname
+}))
+
+// jsdom does not implement requestAnimationFrame; stub it to flush synchronously
+vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+  cb(0)
+  return 0
+})
+vi.stubGlobal('cancelAnimationFrame', vi.fn())
+
+const routes: RoutePageContextMap = {
+  '/dashboard': { name: 'Dashboard', flow: 'dashboard', step: 'dashboard' },
+  '/login': { name: 'Login', flow: 'auth', step: 'login' }
+}
+
+describe('PageTracker (via DataLayerProvider)', () => {
+  beforeEach(() => {
+    delete (window as unknown as Record<string, unknown>).digitalData
+    mockPathname = '/dashboard'
+  })
+
+  it('sets correct context for a matched route', () => {
+    new DataLayer('digitalData')
+
+    render(
+      <DataLayerProvider application="test" routes={routes}>
+        <div />
+      </DataLayerProvider>
+    )
+
+    expect(window.digitalData!.get('page.name')).toBe('Dashboard')
+    expect(window.digitalData!.get('page.flow')).toBe('dashboard')
+    expect(window.digitalData!.get('page.step')).toBe('dashboard')
+  })
+
+  it('falls back to document.title for an unmatched route', () => {
+    mockPathname = '/unknown'
+    document.title = 'Fallback Title'
+    new DataLayer('digitalData')
+
+    render(
+      <DataLayerProvider application="test" routes={routes}>
+        <div />
+      </DataLayerProvider>
+    )
+
+    expect(window.digitalData!.get('page.name')).toBe('Fallback Title')
+  })
+
+  it('fires a page_load event on mount', () => {
+    new DataLayer('digitalData')
+
+    render(
+      <DataLayerProvider application="test" routes={routes}>
+        <div />
+      </DataLayerProvider>
+    )
+
+    expect(window.digitalData!.event.length).toBeGreaterThanOrEqual(1)
+    const pageLoadEvent = window.digitalData!.event.find((e) => e.eventName === 'page_load')
+    expect(pageLoadEvent).toBeDefined()
+    expect(pageLoadEvent!.eventData).toEqual(
+      expect.objectContaining({ name: 'Dashboard', flow: 'dashboard' })
+    )
+  })
+
+  it('updates context when pathname changes', () => {
+    new DataLayer('digitalData')
+
+    const { rerender } = render(
+      <DataLayerProvider application="test" routes={routes}>
+        <div />
+      </DataLayerProvider>
+    )
+
+    expect(window.digitalData!.get('page.name')).toBe('Dashboard')
+
+    // Simulate navigation
+    mockPathname = '/login'
+    act(() => {
+      rerender(
+        <DataLayerProvider application="test" routes={routes}>
+          <div />
+        </DataLayerProvider>
+      )
+    })
+
+    expect(window.digitalData!.get('page.name')).toBe('Login')
+    expect(window.digitalData!.get('page.flow')).toBe('auth')
+    expect(window.digitalData!.get('page.step')).toBe('login')
+  })
+
+  it('does not fire extra page_load when routes prop reference changes', () => {
+    new DataLayer('digitalData')
+
+    const { rerender } = render(
+      <DataLayerProvider application="test" routes={{ ...routes }}>
+        <div />
+      </DataLayerProvider>
+    )
+
+    const countAfterMount = window.digitalData!.event.filter(
+      (e) => e.eventName === 'page_load'
+    ).length
+
+    // Re-render with a new routes object reference but same pathname
+    act(() => {
+      rerender(
+        <DataLayerProvider application="test" routes={{ ...routes }}>
+          <div />
+        </DataLayerProvider>
+      )
+    })
+
+    const countAfterRerender = window.digitalData!.event.filter(
+      (e) => e.eventName === 'page_load'
+    ).length
+
+    expect(countAfterRerender).toBe(countAfterMount)
+  })
+})

packages/analytics/src/DataLayerProvider.tsx

@@ -4,13 +4,27 @@ import { usePathname } from 'next/navigation'
 import { useEffect, useRef, type ReactNode } from 'react'
 
 import { DataLayer } from './data-layer'
-import { CTA_CLICK, PAGE_LOAD } from './events'
+import { CTA_CLICK } from './events'
+
+export interface PageContext {
+  /** Logical page title */
+  name: string
+  /** High-level flow this page belongs to (e.g., "auth", "dashboard", "address_update") */
+  flow: string
+  /** Step index or logical step name within the flow */
+  step: string
+}
+
+/** Map of pathname to page context for automatic page load tracking. */
+export type RoutePageContextMap = Record<string, PageContext>
 
 interface DataLayerProviderProps {
   /** Application identifier set on page.application (e.g., "sebt-portal", "sebt-enrollment-checker") */
   application: string
   /** Environment name (e.g., "dev", "staging", "production"). Defaults to NEXT_PUBLIC_ENVIRONMENT or "production". */
   environment?: string
+  /** Map of pathname to page context. When navigation occurs, matching context is set and pageLoad() fires. */
+  routes?: RoutePageContextMap
   children: ReactNode
 }
 
@@ -19,7 +33,12 @@ interface DataLayerProviderProps {
  * Automatically tracks page views on navigation and CTA clicks via delegation.
  * Must be rendered client-side. Initializes once and persists across navigations.
  */
-export function DataLayerProvider({ application, environment, children }: DataLayerProviderProps) {
+export function DataLayerProvider({
+  application,
+  environment,
+  routes,
+  children
+}: DataLayerProviderProps) {
   const initialized = useRef(false)
 
   useEffect(() => {
@@ -32,6 +51,7 @@ export function DataLayerProvider({ application, environment, children }: DataLa
     }
 
     window.digitalData!.page.set('application', application)
+    window.digitalData!.page.set('entry_source', application.replace('sebt-', '').replace(/-/g, '_'))
     window.digitalData!.page.set(
       'environment',
       environment ?? process.env.NEXT_PUBLIC_ENVIRONMENT ?? 'production'
@@ -40,16 +60,18 @@ export function DataLayerProvider({ application, environment, children }: DataLa
 
   return (
     <>
-      <PageTracker />
+      <PageTracker routes={routes} />
       <CtaTracker />
       {children}
     </>
   )
 }
 
-/** Fires a page_load event on every client-side navigation. */
-function PageTracker() {
+/** Fires a page_load event on every client-side navigation via the dedicated pageLoad() API. */
+function PageTracker({ routes }: { routes: RoutePageContextMap | undefined }) {
   const pathname = usePathname()
+  const routesRef = useRef(routes)
+  routesRef.current = routes
 
   useEffect(() => {
     if (typeof window === 'undefined' || !window.digitalData?.initialized) return
@@ -59,11 +81,20 @@ function PageTracker() {
       const dl = window.digitalData!
       const lang = document.documentElement.lang || 'en'
 
-      dl.page.set('name', document.title)
       dl.page.set('language', lang)
       dl.page.set('locale', `${lang}_US`)
 
-      dl.trackEvent(PAGE_LOAD)
+      // Set route-specific context or fall back to document.title
+      const ctx = routesRef.current?.[pathname]
+      if (ctx) {
+        dl.page.set('name', ctx.name)
+        dl.page.set('flow', ctx.flow)
+        dl.page.set('step', ctx.step)
+      } else {
+        dl.page.set('name', document.title)
+      }
+
+      dl.pageLoad()
     })
 
     return () => cancelAnimationFrame(raf)