fix(exam): stop placeholder guide shapes flashing before template loads

seedGuide() ran in onMount via the 'else' branch while template was still null during the async
fetch, creating 5 example shapes (Q1 start/end, part, response, context) that flashed on screen
until the real template + PDF loaded. Only seed the guide for a genuinely-empty template after load.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Dockerfile

@@ -61,6 +61,21 @@ RUN echo 'server { \
     proxy_set_header X-Real-IP $remote_addr; \
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; \
     } \
+    location /__ccapi/ { \
+    proxy_pass http://192.168.0.64:18000/; \
+    proxy_set_header Host $host; \
+    proxy_set_header X-Real-IP $remote_addr; \
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; \
+    } \
+    location /__supabase/ { \
+    proxy_pass http://192.168.0.94:8000/; \
+    proxy_set_header Host $host; \
+    proxy_set_header X-Real-IP $remote_addr; \
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; \
+    proxy_set_header Upgrade $http_upgrade; \
+    proxy_set_header Connection "upgrade"; \
+    proxy_http_version 1.1; \
+    } \
     location /api/ { \
     proxy_pass http://192.168.0.64:18000/api/; \
     proxy_set_header Host $host; \

docker-compose.dev.yml

@@ -16,15 +16,25 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
-        VITE_API_BASE: ${VITE_API_BASE:-}
+        # app-dev is served by nginx on the app host; browser API calls must stay
-        VITE_API_URL: ${VITE_API_URL:-}
+        # same-origin and pass through Dockerfile's /__ccapi proxy. The proxy
+        # strips that prefix before forwarding, preserving mixed backend routes
+        # such as /api/exam, /me/bootstrap, and /database/timetable.
+        # Supabase is likewise routed same-origin via Dockerfile's /__supabase
+        # proxy -> dev Supabase .94 (no CORS, browser-network-agnostic). The
+        # leading-slash URL is resolved against window.location.origin in
+        # supabaseClient.ts. Provide the matching .94 anon key as a build arg
+        # (VITE_SUPABASE_ANON_KEY) so it pairs with the .94 backend.
+        # .env.dev still points at the LAN API/Supabase for local Vite/dev tooling.
+        VITE_API_BASE: /__ccapi
+        VITE_API_URL: /__ccapi
+        VITE_SUPABASE_URL: /__supabase
         VITE_APP_NAME: ${VITE_APP_NAME:-Classroom Copilot}
         VITE_APP_HMR_URL: ${VITE_APP_HMR_URL:-}
         VITE_DEV: ${VITE_DEV:-false}
         VITE_FRONTEND_SITE_URL: ${VITE_FRONTEND_SITE_URL:-}
         VITE_SEARCH_URL: ${VITE_SEARCH_URL:-}
         VITE_SUPABASE_ANON_KEY: ${VITE_SUPABASE_ANON_KEY:-}
-        VITE_SUPABASE_URL: ${VITE_SUPABASE_URL:-}
         VITE_SUPER_ADMIN_EMAIL: ${VITE_SUPER_ADMIN_EMAIL:-}
         VITE_TLSYNC_URL: ${VITE_TLSYNC_URL:-}
         VITE_WHISPERLIVE_URL: ${VITE_WHISPERLIVE_URL:-}

src/pages/auth/PlatformAdminPage.tsx

@@ -102,6 +102,17 @@ const PlatformAdminPage: React.FC = () => {
                 </Grid>
             )}
 
+            <Alert severity="warning" sx={{ mb: 3 }}>
+                <Typography variant="subtitle2" sx={{ fontWeight: 700 }}>Destructive reset scope: exam-corpus</Typography>
+                <Typography variant="body2">
+                    The <strong>exam-corpus</strong> reset is not limited to public papers. It wipes the entire
+                    exam-marker subsystem: public corpus/eb_* data, cc.examboards storage, templates, template
+                    layouts, questions, boundaries, response areas, marking batches, student submissions, and
+                    mark entries. Use it only when you intend to rebuild all exam-marker data; it does not reset
+                    schools, users, or timetable data.
+                </Typography>
+            </Alert>
+
             <Typography variant="subtitle2" sx={{ mb: 1 }}>Schools ({loading ? '…' : schools.length})</Typography>
 
             {loading ? (

src/pages/exam/setup/ExamTemplateSetupPage.tsx

@@ -4,6 +4,7 @@ import { useNavigate, useParams } from 'react-router-dom'
 import { Alert, Box, Button, Chip, CircularProgress, Collapse, Divider, IconButton, Paper, Snackbar, Stack, Tooltip, Typography, useTheme } from '@mui/material'
 import ArrowBackIcon from '@mui/icons-material/ArrowBack'
 import HelpOutlineIcon from '@mui/icons-material/HelpOutline'
+import AutoFixHighIcon from '@mui/icons-material/AutoFixHigh'
 import SaveIcon from '@mui/icons-material/Save'
 import MouseIcon from '@mui/icons-material/Mouse'
 import '@tldraw/tldraw/tldraw.css'
@@ -13,7 +14,7 @@ import axios from 'axios'
 import { ErrorBoundary } from '../../../components/ErrorBoundary'
 import { logger } from '../../../debugConfig'
 import { examRepository } from '../../../services/exam/examRepository'
-import type { ExamTemplateDetail } from '../../../types/exam.types'
+import type { AutoMapJobStatus, ExamTemplateDetail } from '../../../types/exam.types'
 import { CanvasPageGeometry, ExamCanvasShapeModel, PAGE_HEIGHT, PAGE_WIDTH, isUuid, newDomainId, serializeCanvasShapes, shapesFromTemplate } from '../../../utils/exam-canvas/model'
 import { PDF_PAGE_SHAPE_TYPE, canvasShapePalette, examCanvasShapeUtils, examCanvasTools, ExamCanvasTLShape, SHAPE_TYPES, isPdfPageShape, shapeTypeToKind } from './examCanvasShapes'
 import { loadPdfPageImages, PdfPageImage } from './pdfLoader'
@@ -34,6 +35,8 @@ const PAGE_START_X = 0
 const PDF_PAGE_IDS_PREFIX = 'pdf-page-'
 
 function pageGeometryFromImages(pages: PdfPageImage[]): CanvasPageGeometry[] {
+  // S5 coordinate contract: use the actual pdf.js raster dimensions that feed each page src.
+  // Server mapper emits canvas coordinates against the same PAGE_START_X=0 and stacked page heights.
   let y = 0
   return pages.map((page) => {
     const geometry = { pageNumber: page.pageNumber, x: PAGE_START_X, y, w: page.width, h: page.height }
@@ -67,6 +70,18 @@ function apiMessage(err: unknown): { message: string; conflict: boolean } {
   return { conflict: false, message: err instanceof Error ? err.message : String(err) }
 }
 
+
+function reviewSummary(template: ExamTemplateDetail | null) {
+  if (!template) return { ai: 0, unconfirmed: 0, lowConfidence: 0 }
+  const rows = [...(template.questions ?? []), ...(template.response_areas ?? []), ...(template.boundaries ?? []), ...(template.layout ?? [])]
+  return rows.reduce((acc, row) => {
+    if (row.source === 'ai') acc.ai += 1
+    if (row.source === 'ai' && row.confirmed === false) acc.unconfirmed += 1
+    if (typeof row.confidence === 'number' && row.confidence < 0.7) acc.lowConfidence += 1
+    return acc
+  }, { ai: 0, unconfirmed: 0, lowConfidence: 0 })
+}
+
 function stripShapePrefix(id: string) {
   return id.startsWith('shape:') ? id.slice('shape:'.length) : id
 }
@@ -102,6 +117,10 @@ function modelFromTLShape(shape: TLShape): ExamCanvasShapeModel | null {
     responseForm: s.props.responseForm as ExamCanvasShapeModel['responseForm'],
     contextType: s.props.contextType,
     questionId: s.props.questionId ?? null,
+    source: s.props.source ?? 'manual',
+    confirmed: s.props.confirmed ?? s.props.source !== 'ai',
+    confidence: typeof s.props.confidence === 'number' ? s.props.confidence : null,
+    derivation: s.props.derivation ?? null,
   }
 }
 
@@ -111,15 +130,15 @@ function bringDomainShapesToFront(editor: Editor) {
 }
 
 function loadShapes(editor: Editor, models: ExamCanvasShapeModel[]) {
-  if (!models.length) return
   const existing = editor.getCurrentPageShapes().filter((s) => shapeTypeToKind(s.type)).map((s) => s.id)
   if (existing.length) editor.deleteShapes(existing)
+  if (!models.length) return
   editor.createShapes(models.map((m) => ({
     id: createShapeId(m.id),
     type: SHAPE_TYPES[m.kind],
     x: m.x,
     y: m.y,
-    props: { w: m.w, h: m.h, label: m.label ?? m.kind, kind: m.kind, maxMarks: m.maxMarks, responseForm: m.responseForm, contextType: m.contextType, questionId: m.questionId, domainId: m.id },
+    props: { w: m.w, h: m.h, label: m.label ?? m.kind, kind: m.kind, maxMarks: m.maxMarks, responseForm: m.responseForm, contextType: m.contextType, questionId: m.questionId, domainId: m.id, source: m.source ?? 'manual', confirmed: m.confirmed ?? m.source !== 'ai', confidence: m.confidence ?? undefined, derivation: m.derivation ?? undefined, reviewFlags: m.reviewFlags?.join('|') },
   })))
 }
 
@@ -154,6 +173,20 @@ function seedGuide(editor: Editor) {
   ])
 }
 
+
+function isAutoMapAccepted(value: unknown): value is { status: 'accepted'; job_id: string } {
+  return !!value && typeof value === 'object' && (value as { status?: string }).status === 'accepted' && typeof (value as { job_id?: unknown }).job_id === 'string'
+}
+
+function autoMapStatusLabel(status: AutoMapJobStatus | null): string {
+  if (!status) return 'Auto-map running'
+  if (status.status === 'queued') return 'Auto-map queued'
+  if (status.status === 'running') return 'Auto-map running'
+  if (status.status === 'completed') return 'Auto-map complete'
+  if (status.status === 'failed') return 'Auto-map failed'
+  return `Auto-map ${status.status}`
+}
+
 const ExamTemplateSetupInner: React.FC = () => {
   const { templateId } = useParams<{ templateId: string }>()
   const navigate = useNavigate()
@@ -170,6 +203,23 @@ const ExamTemplateSetupInner: React.FC = () => {
   const [pdfStatus, setPdfStatus] = useState<'loading' | 'ready' | 'missing' | 'error'>('loading')
   const [pdfError, setPdfError] = useState<string | null>(null)
   const [guideOpen, setGuideOpen] = useState(false)
+  const [autoMapStatus, setAutoMapStatus] = useState<AutoMapJobStatus | null>(null)
+  const [autoMapBusy, setAutoMapBusy] = useState(false)
+  const autoMapPollRef = useRef<number | null>(null)
+
+  const applyTemplateToCanvas = useCallback((detail: ExamTemplateDetail) => {
+    setTemplate(detail)
+    const editor = editorRef.current
+    if (editor) {
+      const shapes = shapesFromTemplate(detail, pageGeometriesRef.current)
+      loadShapes(editor, shapes)
+      if (!shapes.length) seedGuide(editor)
+      bringDomainShapesToFront(editor)
+    }
+    setDirty(false)
+  }, [])
+
+  const review = useMemo(() => reviewSummary(template), [template])
 
   const load = useCallback(async () => {
     if (!templateId) return
@@ -227,6 +277,62 @@ const ExamTemplateSetupInner: React.FC = () => {
 
   useEffect(() => { void load() }, [load])
 
+  useEffect(() => () => {
+    if (autoMapPollRef.current !== null) window.clearTimeout(autoMapPollRef.current)
+  }, [])
+
+  const pollAutoMapStatus = useCallback(async (jobId: string) => {
+    if (!templateId) return
+    try {
+      const status = await examRepository.getAutoMapStatus(templateId, jobId)
+      setAutoMapStatus(status)
+      if (status.status === 'completed') {
+        if (autoMapPollRef.current !== null) window.clearTimeout(autoMapPollRef.current)
+        autoMapPollRef.current = null
+        setAutoMapBusy(false)
+        const detail = status.template ?? await examRepository.getTemplate(templateId)
+        applyTemplateToCanvas(detail)
+        return
+      }
+      if (status.status === 'failed') {
+        if (autoMapPollRef.current !== null) window.clearTimeout(autoMapPollRef.current)
+        autoMapPollRef.current = null
+        setAutoMapBusy(false)
+        setError(status.error ?? 'Auto-map failed; existing template state was preserved.')
+        return
+      }
+      autoMapPollRef.current = window.setTimeout(() => void pollAutoMapStatus(jobId), 2500)
+    } catch (e) {
+      const msg = apiMessage(e).message
+      setAutoMapBusy(false)
+      setError(msg)
+      logger.warn('cc-exam-marker', 'Auto-map status poll failed', { templateId, jobId, message: msg })
+    }
+  }, [applyTemplateToCanvas, templateId])
+
+  const autoMapFromPdf = useCallback(async () => {
+    if (!templateId || autoMapBusy) return
+    let queued = false
+    setAutoMapBusy(true); setAutoMapStatus(null); setError(null); setConflict(null)
+    try {
+      const result = await examRepository.autoMapTemplate(templateId)
+      if (isAutoMapAccepted(result)) {
+        queued = true
+        setAutoMapStatus({ job_id: result.job_id, status: 'queued', template_id: templateId })
+        await pollAutoMapStatus(result.job_id)
+        return
+      }
+      setAutoMapStatus(null)
+      applyTemplateToCanvas(result)
+    } catch (e) {
+      const msg = apiMessage(e)
+      if (msg.conflict) setConflict(msg.message); else setError(msg.message)
+      logger.warn('cc-exam-marker', 'Auto-map request failed', { templateId, message: msg.message })
+    } finally {
+      if (!queued) setAutoMapBusy(false)
+    }
+  }, [applyTemplateToCanvas, autoMapBusy, pollAutoMapStatus, templateId])
+
   const save = useCallback(async () => {
     const editor = editorRef.current
     if (!editor || !templateId || !template) return
@@ -248,6 +354,11 @@ const ExamTemplateSetupInner: React.FC = () => {
     }
   }, [template, templateId])
 
+  const layoutSummary = useMemo(() => {
+    const rows = (template?.layout ?? []).filter((row) => row.margins_enabled && row.margin_left !== null && row.margin_right !== null)
+    return rows.slice(0, 4).map((row) => `P${row.page_index + 1} ${row.role ?? 'page'} L${Math.round(row.margin_left ?? 0)} R${Math.round(row.margin_right ?? 0)} T${Math.round(row.margin_top ?? 0)} B${Math.round(row.margin_bottom ?? 0)}`)
+  }, [template?.layout])
+
   const toolButtons = useMemo(() => TOOLS.map((tool) => (
     <Tooltip title={tool.tip} key={tool.id} placement="right">
       <Button
@@ -278,7 +389,10 @@ const ExamTemplateSetupInner: React.FC = () => {
         </Tooltip>
         <Divider orientation="vertical" flexItem />
         <Typography variant="subtitle2" noWrap sx={{ flex: 1, minWidth: 0 }}>{template?.title ?? 'Template setup'}</Typography>
+        <Chip size="small" color={review.unconfirmed ? 'warning' : review.ai ? 'info' : 'default'} label={review.ai ? `AI review: ${review.unconfirmed} unconfirmed · ${review.lowConfidence} low conf` : 'Manual template'} />
         <Chip size="small" color={dirty ? 'warning' : 'success'} label={dirty ? 'Unsaved' : 'Saved'} />
+        {(autoMapBusy || autoMapStatus) && <Chip size="small" color={autoMapStatus?.status === 'failed' ? 'error' : autoMapStatus?.status === 'completed' ? 'success' : 'info'} label={autoMapStatusLabel(autoMapStatus)} />}
+        <Button size="small" variant="outlined" startIcon={autoMapBusy ? <CircularProgress size={14} /> : <AutoFixHighIcon fontSize="small" />} onClick={autoMapFromPdf} disabled={autoMapBusy || saving || loading || !template || pdfStatus !== 'ready'}>Auto-map from PDF</Button>
         <Button size="small" variant="contained" startIcon={saving ? <CircularProgress size={14} color="inherit" /> : <SaveIcon fontSize="small" />} onClick={save} disabled={saving || loading || !template}>Save</Button>
       </Paper>
 
@@ -305,7 +419,14 @@ const ExamTemplateSetupInner: React.FC = () => {
                 editor.store.listen(() => setDirty(true), { scope: 'document' })
                 applyDocViewConstraints(editor, [])
                 editor.resetZoom()
-                if (template) loadShapes(editor, shapesFromTemplate(template, pageGeometriesRef.current)); else seedGuide(editor)
+                // Only seed the example guide for a genuinely-empty template AFTER it has loaded.
+                // (Previously `else seedGuide` fired on mount while `template` was still null during
+                // the async fetch, flashing placeholder shapes before the real shapes/PDF rendered.)
+                if (template) {
+                  const s = shapesFromTemplate(template, pageGeometriesRef.current)
+                  loadShapes(editor, s)
+                  if (!s.length) seedGuide(editor)
+                }
                 bringDomainShapesToFront(editor)
               }}
             />
@@ -323,8 +444,11 @@ const ExamTemplateSetupInner: React.FC = () => {
             <Paper elevation={4} sx={{ p: 2, borderRadius: 3, bgcolor: 'background.paper' }}>
               <Typography variant="subtitle2" gutterBottom>Setup guide</Typography>
               <Typography variant="body2" color="text.secondary" sx={{ mb: 1 }}>
-                1) Boundary start/end lines define each main question. 2) Draw amber Part boxes for markable sub-questions. 3) Draw coloured Response, Context, Q Number, Mark Area, Reference, and Furniture regions; Save derives parent links by containment.
+                1) Boundary start/end lines define each main question. 2) Draw amber Part boxes for markable sub-questions. 3) AI suggestions render dashed/translucent with confidence and cheap review flags; manual shapes stay solid.
               </Typography>
+              <Alert severity={review.unconfirmed || review.lowConfidence ? 'warning' : 'info'} variant="outlined" sx={{ my: 1 }}>
+                Review layer: {review.ai} AI suggestions, {review.unconfirmed} unconfirmed, {review.lowConfidence} below 70% confidence. Cheap flags include overlap, missing marks, uncertain labels, low confidence, and unconfirmed AI.
+              </Alert>
               <Stack direction="row" spacing={0.75} useFlexGap flexWrap="wrap" sx={{ my: 1 }}>
                 {(['boundary', 'part', 'response', 'context', 'question_number', 'mark_area', 'reference', 'furniture'] as const).map((kind) => {
                   const p = canvasShapePalette[kind]
@@ -337,6 +461,9 @@ const ExamTemplateSetupInner: React.FC = () => {
               <Typography variant="caption" color={pdfStatus === 'ready' ? 'success.main' : pdfStatus === 'error' ? 'error.main' : 'text.secondary'} sx={{ display: 'block', mt: 1 }}>
                 PDF: {pdfStatus === 'ready' ? 'loaded' : pdfStatus === 'loading' ? 'loading…' : pdfStatus === 'missing' ? 'no source PDF' : pdfError ?? 'failed'}
               </Typography>
+              <Typography variant="caption" color="text.secondary" sx={{ display: 'block', mt: 1 }}>
+                Margins: {layoutSummary.length ? layoutSummary.join(' · ') : 'not detected yet'}
+              </Typography>
             </Paper>
           </Collapse>
 

src/pages/exam/setup/examCanvasShapes.tsx

@@ -4,6 +4,7 @@ import { BaseBoxShapeTool, BaseBoxShapeUtil, Edge2d, HTMLContainer, ShapeUtil, T
 import type { TLHandle } from '@tldraw/tldraw'
 import { PAGE_WIDTH } from '../../../utils/exam-canvas/model'
 import type { ExamCanvasRegionKind, ExamCanvasShapeKind } from '../../../utils/exam-canvas/model'
+import type { ExamTemplateSource } from '../../../types/exam.types'
 
 export const PDF_PAGE_SHAPE_TYPE = 'exam-pdf-page'
 
@@ -35,6 +36,11 @@ export type ExamCanvasTLShape = TLBaseBoxShape & {
     contextType?: string
     questionId?: string | null
     domainId?: string
+    source?: 'manual' | 'ai'
+    confirmed?: boolean
+    confidence?: number | null
+    derivation?: string | null
+    reviewFlags?: string
   }
 }
 
@@ -64,22 +70,50 @@ const shapeCss = `
 .exam-canvas-shape { --exam-stroke: var(--exam-light-stroke); --exam-fill: var(--exam-light-fill); }
 [data-color-mode="dark"] .exam-canvas-shape, .tl-theme__dark .exam-canvas-shape { --exam-stroke: var(--exam-dark-stroke); --exam-fill: var(--exam-dark-fill); }
 .exam-canvas-shape__pill { background: rgba(255,255,255,.90); color: var(--exam-stroke); box-shadow: 0 1px 4px rgba(15,23,42,.14); }
+.exam-canvas-shape__flag { background: rgba(251,191,36,.94); color: #78350f; box-shadow: 0 1px 4px rgba(120,53,15,.18); }
+.exam-canvas-shape__confidence { background: rgba(15,23,42,.82); color: #fff; }
 [data-color-mode="dark"] .exam-canvas-shape__pill, .tl-theme__dark .exam-canvas-shape__pill { background: rgba(15,23,42,.88); color: var(--exam-stroke); box-shadow: 0 1px 5px rgba(0,0,0,.35); }
+[data-color-mode="dark"] .exam-canvas-shape__flag, .tl-theme__dark .exam-canvas-shape__flag { background: rgba(251,191,36,.88); color: #422006; }
 `
 
+
+function confidenceLabel(confidence: number | null | undefined) {
+  return typeof confidence === 'number' ? `${Math.round(confidence * 100)}%` : null
+}
+
+function reviewFlags(shape: ExamCanvasTLShape): string[] {
+  return (shape.props.reviewFlags ?? '').split('|').map((flag) => flag.trim()).filter(Boolean)
+}
+
+function provenanceTitle(shape: ExamCanvasTLShape, base: string) {
+  const bits = [base]
+  if (shape.props.source === 'ai') bits.push(shape.props.confirmed === false ? 'AI suggestion, unconfirmed' : 'AI, confirmed')
+  const confidence = confidenceLabel(shape.props.confidence)
+  if (confidence) bits.push(`confidence ${confidence}`)
+  if (shape.props.derivation) bits.push(`derivation: ${shape.props.derivation}`)
+  const flags = reviewFlags(shape)
+  if (flags.length) bits.push(`review flags: ${flags.join(', ')}`)
+  return bits.join(' • ')
+}
+
 function renderBoundaryLine(shape: ExamCanvasTLShape) {
   const p = canvasShapePalette.boundary
   const lineY = Math.max(1, Math.min(shape.props.h - 1, shape.props.h / 2))
+  const isAi = shape.props.source === 'ai'
+  const confidence = confidenceLabel(shape.props.confidence)
+  const flags = reviewFlags(shape)
   return (
     <HTMLContainer id={shape.id} style={{ width: toDomPrecision(shape.props.w), height: toDomPrecision(shape.props.h), overflow: 'visible', pointerEvents: 'all' }}>
       <style>{shapeCss}</style>
       <svg width={toDomPrecision(shape.props.w)} height={toDomPrecision(shape.props.h)} aria-label={`${p.label}: ${p.role}`} style={{ display: 'block', overflow: 'visible' }}>
-        <line x1={0} x2={toDomPrecision(shape.props.w)} y1={lineY} y2={lineY} stroke="var(--exam-stroke)" strokeWidth={2.5} strokeDasharray={p.dash} strokeLinecap="round" style={{ '--exam-light-stroke': p.stroke, '--exam-dark-stroke': p.darkStroke } as React.CSSProperties} />
+        <line x1={0} x2={toDomPrecision(shape.props.w)} y1={lineY} y2={lineY} stroke="var(--exam-stroke)" strokeWidth={2.5} strokeDasharray={isAi ? '4 6' : p.dash} strokeLinecap="round" opacity={isAi ? 0.62 : 1} style={{ '--exam-light-stroke': p.stroke, '--exam-dark-stroke': p.darkStroke } as React.CSSProperties} />
       </svg>
       <span className="exam-canvas-shape__pill" style={{ position: 'absolute', left: 8, top: -24, fontSize: 11, fontWeight: 900, textTransform: 'uppercase', letterSpacing: 0.6, borderRadius: 999, padding: '2px 7px', display: 'inline-flex', alignItems: 'center', gap: 5, color: p.stroke }}>
-        <span aria-hidden="true">{p.icon}</span>
+        <span aria-hidden="true">{isAi ? 'AI' : p.icon}</span>
         {shape.props.label || p.label}
       </span>
+      {confidence && <span className="exam-canvas-shape__pill exam-canvas-shape__confidence" style={{ position: 'absolute', right: 8, top: -24, fontSize: 11, fontWeight: 900, borderRadius: 999, padding: '2px 7px' }}>{confidence}</span>}
+      {flags.slice(0, 2).map((flag, index) => <span key={flag} className="exam-canvas-shape__pill exam-canvas-shape__flag" style={{ position: 'absolute', left: 8, top: 10 + index * 22, fontSize: 10, fontWeight: 900, borderRadius: 999, padding: '1px 6px' }}>{flag}</span>)}
     </HTMLContainer>
   )
 }
@@ -88,7 +122,12 @@ function renderShape(shape: ExamCanvasTLShape) {
   const kind = shape.props.kind
   const p = canvasShapePalette[kind] ?? canvasShapePalette.response
   const isBoundary = kind === 'boundary'
+  const isAiSuggestion = shape.props.source === 'ai' && shape.props.confirmed === false
   if (isBoundary) return renderBoundaryLine(shape)
+  const isAi = shape.props.source === 'ai'
+  const confidence = confidenceLabel(shape.props.confidence)
+  const flags = reviewFlags(shape)
+  const title = provenanceTitle(shape, `${p.label}: ${p.role}`)
   return (
     <HTMLContainer id={shape.id} style={{ width: toDomPrecision(shape.props.w), height: toDomPrecision(shape.props.h), pointerEvents: 'all' }}>
       <style>{shapeCss}</style>
@@ -100,19 +139,21 @@ function renderShape(shape: ExamCanvasTLShape) {
           '--exam-dark-stroke': p.darkStroke,
           '--exam-dark-fill': p.darkFill,
           width: '100%', height: '100%', boxSizing: 'border-box', border: `${isBoundary ? 2 : 1.5}px solid var(--exam-stroke)`,
-          borderStyle: p.dash ? 'dashed' : 'solid', borderRadius: isBoundary ? 999 : 10,
+          borderStyle: isAi ? 'dashed' : p.dash ? 'dashed' : 'solid', borderRadius: isBoundary ? 999 : 10,
-          background: isBoundary ? 'transparent' : 'var(--exam-fill)', color: 'var(--exam-stroke)', fontFamily: 'Inter, system-ui, sans-serif',
+          background: isBoundary ? 'transparent' : 'var(--exam-fill)', opacity: isAi ? 0.72 : 1, color: 'var(--exam-stroke)', fontFamily: 'Inter, system-ui, sans-serif',
           display: 'flex', alignItems: isBoundary ? 'center' : 'flex-start', justifyContent: isBoundary ? 'center' : 'space-between',
           padding: isBoundary ? '0 8px' : 8, boxShadow: isBoundary ? '0 0 0 3px rgba(239,68,68,0.08)' : '0 10px 22px rgba(15,23,42,0.10)', overflow: 'hidden', gap: 6,
         } as React.CSSProperties}
-        aria-label={`${p.label}: ${p.role}`}
+        aria-label={title}
-        title={`${p.label}: ${p.role}`}
+        title={title}
       >
         <span className="exam-canvas-shape__pill" style={{ fontSize: 12, fontWeight: 900, textTransform: 'uppercase', letterSpacing: 0.6, borderRadius: 999, padding: '2px 7px', display: 'inline-flex', alignItems: 'center', gap: 5 }}>
-          <span aria-hidden="true">{p.icon}</span>
+          <span aria-hidden="true">{isAi ? 'AI' : p.icon}</span>
           {shape.props.label || p.label}
         </span>
-        {!isBoundary && shape.props.questionId && <span className="exam-canvas-shape__pill" style={{ fontSize: 11, fontWeight: 800, borderRadius: 999, padding: '2px 7px' }}>Attached</span>}
+        {confidence && <span className="exam-canvas-shape__pill exam-canvas-shape__confidence" style={{ fontSize: 11, fontWeight: 900, borderRadius: 999, padding: '2px 7px' }}>{confidence}</span>}
+        {!confidence && !isBoundary && shape.props.questionId && <span className="exam-canvas-shape__pill" style={{ fontSize: 11, fontWeight: 800, borderRadius: 999, padding: '2px 7px' }}>Attached</span>}
+        {flags.length > 0 && <span className="exam-canvas-shape__pill exam-canvas-shape__flag" style={{ position: 'absolute', left: 8, bottom: 8, fontSize: 10, fontWeight: 900, borderRadius: 999, padding: '1px 6px', maxWidth: 'calc(100% - 16px)', whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>{flags.slice(0, 2).join(' · ')}</span>}
         {isBoundary && <span className="exam-canvas-shape__pill" style={{ fontSize: 10, fontWeight: 800, borderRadius: 999, padding: '1px 6px' }}>pair across pages</span>}
       </div>
     </HTMLContainer>
@@ -121,10 +162,10 @@ function renderShape(shape: ExamCanvasTLShape) {
 
 function defaultProps(kind: ExamCanvasShapeKind, w: number, h: number) {
   const p = canvasShapePalette[kind]
-  return { w, h, label: p.label, kind, responseForm: kind === 'response' ? 'lines' : undefined, contextType: kind === 'context' ? 'generic' : undefined }
+  return { w, h, label: p.label, kind, responseForm: kind === 'response' ? 'lines' : undefined, contextType: kind === 'context' ? 'generic' : undefined, source: 'manual' as const, confirmed: true }
 }
 
-const sharedProps = { w: T.number, h: T.number, label: T.string, kind: T.string, maxMarks: T.optional(T.number), responseForm: T.optional(T.string), contextType: T.optional(T.string), questionId: T.optional(T.string), domainId: T.optional(T.string) }
+const sharedProps = { w: T.number, h: T.number, label: T.string, kind: T.string, maxMarks: T.optional(T.number), responseForm: T.optional(T.string), contextType: T.optional(T.string), questionId: T.optional(T.string), domainId: T.optional(T.string), source: T.optional(T.string), confirmed: T.optional(T.boolean), confidence: T.optional(T.number), derivation: T.optional(T.string), reviewFlags: T.optional(T.string) }
 const ind = (s: ExamCanvasTLShape | ExamPdfPageTLShape) => <rect width={toDomPrecision(s.props.w)} height={toDomPrecision(s.props.h)} />
 
 class PdfPageUtil extends BaseBoxShapeUtil<ExamPdfPageTLShape> {

src/services/exam/examRepository.ts

@@ -11,6 +11,8 @@ import { API_BASE } from '../../config/apiConfig';
 import { logger } from '../../debugConfig';
 import { supabase } from '../../supabaseClient';
 import type {
+  AutoMapJobStatus,
+  AutoMapResponse,
   BatchQueueResponse,
   BatchResultsResponse,
   CreateBatchPayload,
@@ -20,6 +22,7 @@ import type {
   ExamResponseArea,
   ExamTemplate,
   ExamTemplateDetail,
+  ExamTemplateLayout,
   MarkingBatch,
   MarkUpsertPayload,
   Neo4jSyncResult,
@@ -64,6 +67,10 @@ function questionPayload(q: ExamQuestion, idMap?: Map<string, string>) {
     spec_ref: q.spec_ref,
     bounds: q.bounds ?? null,
     page: q.page ?? null,
+    source: q.source ?? 'manual',
+    confirmed: q.confirmed ?? true,
+    confidence: q.confidence ?? null,
+    derivation: q.derivation ?? null,
   };
 }
 
@@ -79,6 +86,8 @@ function responseAreaPayload(r: ExamResponseArea, idMap?: Map<string, string>, d
     source: r.source,
     confirmed: r.confirmed,
     confidence: r.confidence,
+    mark_subtype: r.mark_subtype ?? null,
+    derivation: r.derivation ?? null,
   };
 }
 
@@ -92,6 +101,26 @@ function boundaryPayload(b: ExamBoundary, idMap?: Map<string, string>, duplicate
     bounds: b.bounds,
     source: b.source,
     confirmed: b.confirmed,
+    confidence: b.confidence ?? null,
+    derivation: b.derivation ?? null,
+  };
+}
+
+function layoutPayload(layout: ExamTemplateLayout, duplicate = false) {
+  return {
+    id: duplicate ? newUuid() : layout.id,
+    page_index: layout.page_index,
+    role: layout.role ?? null,
+    margin_left: layout.margin_left ?? null,
+    margin_right: layout.margin_right ?? null,
+    margin_top: layout.margin_top ?? null,
+    margin_bottom: layout.margin_bottom ?? null,
+    margins_enabled: layout.margins_enabled ?? true,
+    source: layout.source ?? 'manual',
+    confirmed: layout.confirmed ?? true,
+    confidence: layout.confidence ?? null,
+    derivation: layout.derivation ?? null,
+    meta: layout.meta ?? {},
   };
 }
 
@@ -113,6 +142,7 @@ async function replaceTemplate(
       questions: detail.questions.map((q) => questionPayload(q, idMap)),
       response_areas: detail.response_areas.map((r) => responseAreaPayload(r, idMap, duplicateIds)),
       boundaries: detail.boundaries.map((b) => boundaryPayload(b, idMap, duplicateIds)),
+      layout: (detail.layout ?? []).map((layout) => layoutPayload(layout, duplicateIds)),
     },
     { headers },
   );
@@ -135,6 +165,18 @@ export const examRepository = {
     return res.data;
   },
 
+  async autoMapTemplate(templateId: string): Promise<AutoMapResponse> {
+    const headers = await authHeaders();
+    const res = await axios.post<AutoMapResponse>(`${EXAM_BASE}/templates/${templateId}/auto-map`, {}, { headers });
+    return res.data;
+  },
+
+  async getAutoMapStatus(templateId: string, jobId: string): Promise<AutoMapJobStatus> {
+    const headers = await authHeaders();
+    const res = await axios.get<AutoMapJobStatus>(`${EXAM_BASE}/templates/${templateId}/auto-map/${jobId}/status`, { headers });
+    return res.data;
+  },
+
   async getTemplateSourcePdf(templateId: string): Promise<ArrayBuffer> {
     const headers = await authHeaders();
     const res = await axios.get<ArrayBuffer>(`${EXAM_BASE}/templates/${templateId}/source-pdf`, {

src/supabaseClient.ts

@@ -1,9 +1,17 @@
 import { createClient, SupabaseClient } from '@supabase/supabase-js';
 import { logger } from './debugConfig';
 
-const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
+const rawSupabaseUrl = import.meta.env.VITE_SUPABASE_URL;
 const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;
 
+// Same-origin proxy support: a leading-slash value (e.g. "/__supabase") is
+// resolved against the current browser origin so supabase-js receives an
+// absolute URL while every request stays same-origin (no CORS) and routes
+// through the app host's /__supabase nginx proxy to the backend Supabase.
+const supabaseUrl = rawSupabaseUrl?.startsWith('/')
+  ? `${window.location.origin}${rawSupabaseUrl}`
+  : rawSupabaseUrl;
+
 if (!supabaseUrl || !supabaseAnonKey) {
   throw new Error('Missing Supabase configuration');
 }

src/types/exam.types.ts

@@ -75,6 +75,8 @@ export interface UpdateTemplateMetaPayload {
 }
 
 /** Canvas children (used from S4-9 onward; defined here so the seam is complete). */
+export type ExamTemplateSource = 'manual' | 'ai';
+
 export interface ExamQuestion {
   id: string;
   template_id: string;
@@ -89,6 +91,10 @@ export interface ExamQuestion {
   spec_ref: string | null;
   bounds?: Record<string, number> | null;
   page?: number | null;
+  source: ExamTemplateSource;
+  confirmed: boolean;
+  confidence: number | null;
+  derivation: string | null;
 }
 
 export type ExamResponseAreaKind =
@@ -99,6 +105,8 @@ export type ExamResponseAreaKind =
   | 'reference'
   | 'furniture';
 
+export type ExamMarkSubtype = 'part_marks' | 'question_total' | 'grader_box';
+
 export interface ExamResponseArea {
   id: string;
   question_id: string;
@@ -108,9 +116,11 @@ export interface ExamResponseArea {
   kind: ExamResponseAreaKind;
   response_form: string | null;
   context_type?: string | null;
-  source: 'manual' | 'ai';
+  source: ExamTemplateSource;
   confirmed: boolean;
   confidence: number | null;
+  mark_subtype?: ExamMarkSubtype | null;
+  derivation?: string | null;
 }
 
 export interface ExamBoundary {
@@ -121,14 +131,36 @@ export interface ExamBoundary {
   page_index: number;
   y: number;
   bounds: Record<string, number> | null;
-  source: 'manual' | 'ai';
+  source: ExamTemplateSource;
   confirmed: boolean;
+  confidence: number | null;
+  derivation: string | null;
+}
+
+export interface ExamTemplateLayout {
+  id: string;
+  template_id: string;
+  page_index: number;
+  role: string | null;
+  margin_left: number | null;
+  margin_right: number | null;
+  margin_top: number | null;
+  margin_bottom: number | null;
+  margins_enabled: boolean;
+  source: ExamTemplateSource;
+  confirmed: boolean;
+  confidence: number | null;
+  derivation: string | null;
+  meta: Record<string, unknown>;
+  created_at?: string;
+  updated_at?: string;
 }
 
 export interface ExamTemplateDetail extends ExamTemplate {
   questions: ExamQuestion[];
   response_areas: ExamResponseArea[];
   boundaries: ExamBoundary[];
+  layout: ExamTemplateLayout[];
 }
 
 
@@ -152,6 +184,10 @@ export interface TemplateReplacePayload {
     spec_ref?: string | null;
     bounds?: Record<string, number> | null;
     page?: number | null;
+    source?: ExamTemplateSource;
+    confirmed?: boolean;
+    confidence?: number | null;
+    derivation?: string | null;
   }>;
   response_areas: Array<{
     id?: string;
@@ -164,6 +200,8 @@ export interface TemplateReplacePayload {
     source?: 'manual' | 'ai';
     confirmed?: boolean;
     confidence?: number | null;
+    mark_subtype?: ExamMarkSubtype | null;
+    derivation?: string | null;
   }>;
   boundaries: Array<{
     id?: string;
@@ -172,8 +210,25 @@ export interface TemplateReplacePayload {
     page_index: number;
     y: number;
     bounds?: Record<string, number> | null;
-    source?: 'manual' | 'ai';
+    source?: ExamTemplateSource;
     confirmed?: boolean;
+    confidence?: number | null;
+    derivation?: string | null;
+  }>;
+  layout?: Array<{
+    id?: string;
+    page_index: number;
+    role?: string | null;
+    margin_left?: number | null;
+    margin_right?: number | null;
+    margin_top?: number | null;
+    margin_bottom?: number | null;
+    margins_enabled?: boolean;
+    source?: ExamTemplateSource;
+    confirmed?: boolean;
+    confidence?: number | null;
+    derivation?: string | null;
+    meta?: Record<string, unknown>;
   }>;
 }
 
@@ -202,6 +257,23 @@ export interface Neo4jSyncResult {
   projection?: Record<string, unknown>;
 }
 
+export interface AutoMapAcceptedResponse {
+  status: 'accepted';
+  job_id: string;
+}
+
+export interface AutoMapJobStatus {
+  job_id: string;
+  status: 'queued' | 'running' | 'completed' | 'failed' | string;
+  template_id: string;
+  updated_at?: number;
+  counts?: Record<string, number>;
+  error?: string;
+  template?: ExamTemplateDetail;
+}
+
+export type AutoMapResponse = ExamTemplateDetail | AutoMapAcceptedResponse;
+
 export interface MarkingBatch {
   id: string;
   template_id: string;

src/utils/exam-canvas/model.test.ts

@@ -4,7 +4,7 @@ import { isUuid, pageForY, serializeCanvasShapes, shapesFromTemplate } from './m
 
 const template: ExamTemplateDetail = {
   id: 'tpl-1', title: 'Physics', subject: 'Physics', exam_id: null, exam_code: null, source_file_id: null, page_count: 1,
-  institute_id: 'inst', teacher_id: 'teacher', status: 'draft', created_at: 'now', updated_at: 'now', questions: [], response_areas: [], boundaries: [],
+  institute_id: 'inst', teacher_id: 'teacher', status: 'draft', created_at: 'now', updated_at: 'now', questions: [], response_areas: [], boundaries: [], layout: [],
 }
 
 describe('exam setup canvas serialization', () => {
@@ -51,17 +51,45 @@ describe('exam setup canvas serialization', () => {
     const shapes = shapesFromTemplate({
       ...template,
       questions: [
-        { id: 'q1', template_id: 'tpl-1', parent_id: null, label: 'Q1', order: 0, max_marks: 0, answer_type: null, mcq_options: null, mark_scheme: {}, is_container: true, spec_ref: null },
+        { id: 'q1', template_id: 'tpl-1', parent_id: null, label: 'Q1', order: 0, max_marks: 0, answer_type: null, mcq_options: null, mark_scheme: {}, is_container: true, spec_ref: null, source: 'manual', confirmed: true, confidence: null, derivation: null },
-        { id: 'p1', template_id: 'tpl-1', parent_id: 'q1', label: 'Q1(a)', order: 0, max_marks: 2, answer_type: 'written', mcq_options: null, mark_scheme: {}, is_container: false, spec_ref: null, bounds: { x: 1, y: 2, w: 3, h: 4 }, page: 1 },
+        { id: 'p1', template_id: 'tpl-1', parent_id: 'q1', label: 'Q1(a)', order: 0, max_marks: 2, answer_type: 'written', mcq_options: null, mark_scheme: {}, is_container: false, spec_ref: null, bounds: { x: 1, y: 2, w: 3, h: 4 }, page: 1, source: 'manual', confirmed: true, confidence: null, derivation: null },
       ],
       response_areas: [
-        { id: 'r1', question_id: 'p1', template_id: 'tpl-1', page: 1, bounds: { x: 10, y: 20, w: 30, h: 40 }, kind: 'response', response_form: 'lines', source: 'manual', confirmed: true, confidence: null },
+        { id: 'r1', question_id: 'p1', template_id: 'tpl-1', page: 1, bounds: { x: 10, y: 20, w: 30, h: 40 }, kind: 'response', response_form: 'lines', source: 'manual', confirmed: true, confidence: null, derivation: null },
-        { id: 'f1', question_id: 'p1', template_id: 'tpl-1', page: 1, bounds: { x: 11, y: 21, w: 31, h: 41 }, kind: 'furniture', response_form: null, source: 'manual', confirmed: true, confidence: null },
+        { id: 'f1', question_id: 'p1', template_id: 'tpl-1', page: 1, bounds: { x: 11, y: 21, w: 31, h: 41 }, kind: 'furniture', response_form: null, source: 'manual', confirmed: true, confidence: null, derivation: null },
       ],
-      boundaries: [{ id: 'b1', template_id: 'tpl-1', question_id: 'q1', label: 'Q1 start', page_index: 0, y: 100, bounds: { x: 0, y: 100, w: 700, h: 8 }, source: 'manual', confirmed: true }],
+      boundaries: [{ id: 'b1', template_id: 'tpl-1', question_id: 'q1', label: 'Q1 start', page_index: 0, y: 100, bounds: { x: 0, y: 100, w: 700, h: 8 }, source: 'manual', confirmed: true, confidence: null, derivation: null }],
     })
     expect(shapes.map((s) => s.kind).sort()).toEqual(['boundary', 'furniture', 'part', 'response'])
     expect(shapes.find((s) => s.kind === 'boundary')).toMatchObject({ id: 'b1', x: 0, y: 100, w: 780, h: 8 })
     expect(shapes.find((s) => s.kind === 'part')).toMatchObject({ id: 'p1', x: 1, y: 2, w: 3, h: 4 })
   })
+
+  it('carries AI provenance into canvas models, flags cheap review issues, and preserves it on save', () => {
+    const detail: ExamTemplateDetail = {
+      ...template,
+      questions: [
+        { id: '11111111-1111-4111-8111-111111111111', template_id: 'tpl-1', parent_id: null, label: 'Q?', order: 0, max_marks: 0, answer_type: null, mcq_options: null, mark_scheme: {}, is_container: true, spec_ref: null, source: 'ai', confirmed: false, confidence: 0.62, derivation: 'g6' },
+        { id: '22222222-2222-4222-8222-222222222222', template_id: 'tpl-1', parent_id: '11111111-1111-4111-8111-111111111111', label: 'Q?', order: 0, max_marks: 0, answer_type: 'written', mcq_options: null, mark_scheme: {}, is_container: false, spec_ref: null, bounds: { x: 100, y: 120, w: 200, h: 100 }, page: 1, source: 'ai', confirmed: false, confidence: 0.62, derivation: 'g6' },
+        { id: '66666666-6666-4666-8666-666666666666', template_id: 'tpl-1', parent_id: '11111111-1111-4111-8111-111111111111', label: 'Q1(b)', order: 1, max_marks: 1, answer_type: 'written', mcq_options: null, mark_scheme: {}, is_container: false, spec_ref: null, bounds: { x: 150, y: 150, w: 200, h: 100 }, page: 1, source: 'ai', confirmed: false, confidence: 0.8, derivation: 'g6' },
+      ],
+      response_areas: [
+        { id: '33333333-3333-4333-8333-333333333333', question_id: '22222222-2222-4222-8222-222222222222', template_id: 'tpl-1', page: 1, bounds: { x: 120, y: 140, w: 120, h: 40 }, kind: 'response', response_form: 'lines', source: 'ai', confirmed: false, confidence: 0.8, derivation: 'regions' },
+      ],
+      boundaries: [
+        { id: '44444444-4444-4444-8444-444444444444', template_id: 'tpl-1', question_id: '11111111-1111-4111-8111-111111111111', label: 'Q? start', page_index: 0, y: 100, bounds: { x: 0, y: 100, w: 700, h: 8 }, source: 'ai', confirmed: false, confidence: 0.62, derivation: 'g6' },
+        { id: '55555555-5555-4555-8555-555555555555', template_id: 'tpl-1', question_id: '11111111-1111-4111-8111-111111111111', label: 'Q? end', page_index: 0, y: 500, bounds: { x: 0, y: 500, w: 700, h: 8 }, source: 'ai', confirmed: false, confidence: 0.62, derivation: 'g6' },
+      ],
+    }
+    const shapes = shapesFromTemplate(detail)
+    const part = shapes.find((shape) => shape.kind === 'part')
+    expect(part).toMatchObject({ source: 'ai', confirmed: false, confidence: 0.62, derivation: 'g6' })
+    expect(part?.reviewFlags).toEqual(expect.arrayContaining(['unconfirmed AI', 'low confidence', 'uncertain question label', 'missing marks', 'overlapping shapes']))
+
+    const payload = serializeCanvasShapes(template, shapes)
+    expect(payload.questions.find((q) => q.id === '22222222-2222-4222-8222-222222222222')).toMatchObject({ source: 'ai', confirmed: false, confidence: 0.62, derivation: 'g6' })
+    expect(payload.response_areas.find((r) => r.id === '33333333-3333-4333-8333-333333333333')).toMatchObject({ source: 'ai', confirmed: false, confidence: 0.8, derivation: 'regions' })
+    expect(payload.boundaries.find((b) => b.id === '44444444-4444-4444-8444-444444444444')).toMatchObject({ source: 'ai', confirmed: false, confidence: 0.62, derivation: 'g6' })
+  })
+
 })

src/utils/exam-canvas/model.ts

@@ -1,5 +1,5 @@
 
-import type { ExamTemplateDetail, TemplateReplacePayload } from '../../types/exam.types'
+import type { ExamTemplateDetail, ExamTemplateSource, TemplateReplacePayload } from '../../types/exam.types'
 
 export const PAGE_HEIGHT = 1100
 export const PAGE_WIDTH = 780
@@ -10,7 +10,7 @@ export interface CanvasPageGeometry { pageNumber: number; x: number; y: number;
 export type ExamCanvasRegionKind = 'response' | 'context' | 'question_number' | 'mark_area' | 'reference' | 'furniture'
 export type ExamCanvasShapeKind = 'boundary' | 'part' | ExamCanvasRegionKind
 
-export interface CanvasBounds { x: number; y: number; w: number; h: number }
+export interface CanvasBounds extends Record<string, number> { x: number; y: number; w: number; h: number }
 
 export interface ExamCanvasShapeModel {
   /** Stable domain UUID persisted to Supabase. Do not reuse tldraw shape ids for new shapes. */
@@ -26,6 +26,11 @@ export interface ExamCanvasShapeModel {
   responseForm?: 'lines' | 'answer-box' | 'working' | 'diagram' | 'tick-boxes' | 'table' | 'blanks'
   contextType?: string
   questionId?: string | null
+  source?: ExamTemplateSource
+  confirmed?: boolean
+  confidence?: number | null
+  derivation?: string | null
+  reviewFlags?: string[]
 }
 
 export function pageForY(y: number, pages?: CanvasPageGeometry[]): number {
@@ -78,6 +83,22 @@ function boundaryBounds(shape: Pick<ExamCanvasShapeModel, 'y' | 'h'>, pages?: Ca
   return { x: page.x, y: shape.y, w: page.w, h: 8 }
 }
 
+function persistedSource(shape: ExamCanvasShapeModel): ExamTemplateSource {
+  return shape.source ?? 'manual'
+}
+
+function persistedConfirmed(shape: ExamCanvasShapeModel): boolean {
+  return shape.confirmed ?? persistedSource(shape) !== 'ai'
+}
+
+function persistedConfidence(shape: ExamCanvasShapeModel): number | null {
+  return typeof shape.confidence === 'number' ? shape.confidence : null
+}
+
+function persistedDerivation(shape: ExamCanvasShapeModel): string | null {
+  return shape.derivation ?? null
+}
+
 function contains(outer: CanvasBounds, inner: CanvasBounds): boolean {
   const ox2 = outer.x + outer.w
   const oy2 = outer.y + outer.h
@@ -111,10 +132,10 @@ export function serializeCanvasShapes(template: ExamTemplateDetail, shapes: Exam
     const qNum = bands.length + 1
     const questionId = isUuid(top.questionId) ? top.questionId : isUuid(bottom.questionId) ? bottom.questionId : newDomainId()
     const label = top.label?.replace(/\s+(start|end)$/i, '') || bottom.label?.replace(/\s+(start|end)$/i, '') || `Q${qNum}`
-    questions.push({ id: questionId, label, order: qNum - 1, max_marks: 0, is_container: true, mark_scheme: {} })
+    questions.push({ id: questionId, label, order: qNum - 1, max_marks: 0, is_container: true, mark_scheme: {}, source: persistedSource(top), confirmed: persistedConfirmed(top), confidence: persistedConfidence(top), derivation: persistedDerivation(top) })
     bands.push({ questionId, top, bottom })
     for (const b of [top, bottom]) {
-      boundaries.push({ id: isUuid(b.id) ? b.id : newDomainId(), question_id: questionId, label: b === top ? `${label} start` : `${label} end`, page_index: pageForShape(b, pages) - 1, y: b.y, bounds: boundaryBounds(b, pages), source: 'manual', confirmed: true })
+      boundaries.push({ id: isUuid(b.id) ? b.id : newDomainId(), question_id: questionId, label: b === top ? `${label} start` : `${label} end`, page_index: pageForShape(b, pages) - 1, y: b.y, bounds: boundaryBounds(b, pages), source: persistedSource(b), confirmed: persistedConfirmed(b), confidence: persistedConfidence(b), derivation: persistedDerivation(b) })
     }
   }
 
@@ -123,7 +144,7 @@ export function serializeCanvasShapes(template: ExamTemplateDetail, shapes: Exam
     const parentBand = bands.find((band) => bandContains(band.top, band.bottom, part))
     const qid = isUuid(part.questionId) ? part.questionId : isUuid(part.id) ? part.id : newDomainId()
     partQuestionIds.set(part.id, qid)
-    questions.push({ id: qid, parent_id: parentBand?.questionId ?? null, label: part.label || `Part ${index + 1}`, order: index, max_marks: Number(part.maxMarks ?? 0), answer_type: part.answerType ?? 'written', mcq_options: null, mark_scheme: {}, is_container: false, spec_ref: null, bounds: bounds(part), page: pageForShape(part, pages) })
+    questions.push({ id: qid, parent_id: parentBand?.questionId ?? null, label: part.label || `Part ${index + 1}`, order: index, max_marks: Number(part.maxMarks ?? 0), answer_type: part.answerType ?? 'written', mcq_options: null, mark_scheme: {}, is_container: false, spec_ref: null, bounds: bounds(part), page: pageForShape(part, pages), source: persistedSource(part), confirmed: persistedConfirmed(part), confidence: persistedConfidence(part), derivation: persistedDerivation(part) })
   })
 
   const response_areas: TemplateReplacePayload['response_areas'] = []
@@ -133,10 +154,10 @@ export function serializeCanvasShapes(template: ExamTemplateDetail, shapes: Exam
     const questionId = containingPart ? partQuestionIds.get(containingPart.id) : fallbackPart ? partQuestionIds.get(fallbackPart.id) : undefined
     if (!questionId) continue
     const kind = region.kind as ExamCanvasRegionKind
-    response_areas.push({ id: isUuid(region.id) ? region.id : newDomainId(), question_id: questionId, page: pageForShape(region, pages), bounds: bounds(region), kind, response_form: kind === 'response' ? (region.responseForm ?? 'lines') : null, context_type: kind === 'context' ? (region.contextType ?? 'generic') : null, source: 'manual', confirmed: true, confidence: null })
+    response_areas.push({ id: isUuid(region.id) ? region.id : newDomainId(), question_id: questionId, page: pageForShape(region, pages), bounds: bounds(region), kind, response_form: kind === 'response' ? (region.responseForm ?? 'lines') : null, context_type: kind === 'context' ? (region.contextType ?? 'generic') : null, source: persistedSource(region), confirmed: persistedConfirmed(region), confidence: persistedConfidence(region), mark_subtype: null, derivation: persistedDerivation(region) })
   }
 
-  return { meta: { title: template.title, subject: template.subject ?? undefined, page_count: template.page_count ?? undefined, status: template.status }, questions, response_areas, boundaries }
+  return { meta: { title: template.title, subject: template.subject ?? undefined, page_count: template.page_count ?? undefined, status: template.status }, questions, response_areas, boundaries, layout: template.layout ?? [] }
 }
 
 export function shapesFromTemplate(detail: ExamTemplateDetail, pages?: CanvasPageGeometry[]): ExamCanvasShapeModel[] {
@@ -146,16 +167,42 @@ export function shapesFromTemplate(detail: ExamTemplateDetail, pages?: CanvasPag
     const page = pageGeometry((b.page_index ?? 0) + 1, pages)
     // Boundary rows are y-lines. The old bounds rect is vestigial: keep y/domain ids,
     // but render and save a full rendered-page-width horizontal rule.
-    shapes.push({ id: b.id, kind: 'boundary', x: page.x, y: Number(b.y), w: page.w, h: 8, label: b.label ?? undefined, questionId: b.question_id })
+    shapes.push({ id: b.id, kind: 'boundary', x: page.x, y: Number(b.y), w: page.w, h: 8, label: b.label ?? undefined, questionId: b.question_id, source: b.source, confirmed: b.confirmed, confidence: b.confidence, derivation: b.derivation })
   }
   for (const q of detail.questions ?? []) {
     if (q.is_container || !q.bounds) continue
-    shapes.push({ id: q.id, kind: 'part', x: Number(q.bounds.x ?? 80), y: Number(q.bounds.y ?? 120), w: Number(q.bounds.w ?? 420), h: Number(q.bounds.h ?? 180), label: q.label, maxMarks: q.max_marks, answerType: q.answer_type ?? 'written', questionId: q.id })
+    shapes.push({ id: q.id, kind: 'part', x: Number(q.bounds.x ?? 80), y: Number(q.bounds.y ?? 120), w: Number(q.bounds.w ?? 420), h: Number(q.bounds.h ?? 180), label: q.label, maxMarks: q.max_marks, answerType: (q.answer_type as ExamCanvasShapeModel['answerType']) ?? 'written', questionId: q.id, source: q.source, confirmed: q.confirmed, confidence: q.confidence, derivation: q.derivation })
   }
   for (const r of detail.response_areas ?? []) {
     const bb = r.bounds ?? { x: 100, y: pageTop(r.page, pages) + 360, w: 360, h: 120 }
     const q = questions.get(r.question_id)
-    shapes.push({ id: r.id, kind: r.kind, x: Number(bb.x ?? 100), y: Number(bb.y ?? pageTop(r.page, pages) + 360), w: Number(bb.w ?? 360), h: Number(bb.h ?? 120), label: q ? `→ ${q.label}` : r.kind, responseForm: r.response_form ?? undefined, contextType: r.context_type ?? undefined, questionId: r.question_id })
+    shapes.push({ id: r.id, kind: r.kind, x: Number(bb.x ?? 100), y: Number(bb.y ?? pageTop(r.page, pages) + 360), w: Number(bb.w ?? 360), h: Number(bb.h ?? 120), label: q ? `→ ${q.label}` : r.kind, responseForm: (r.response_form as ExamCanvasShapeModel['responseForm']) ?? undefined, contextType: r.context_type ?? undefined, questionId: r.question_id, source: r.source, confirmed: r.confirmed, confidence: r.confidence, derivation: r.derivation })
   }
-  return shapes
+  return addCheapReviewFlags(shapes, pages)
+}
+
+function overlaps(a: ExamCanvasShapeModel, b: ExamCanvasShapeModel): boolean {
+  const ax2 = a.x + a.w
+  const ay2 = a.y + a.h
+  const bx2 = b.x + b.w
+  const by2 = b.y + b.h
+  return a.x < bx2 && ax2 > b.x && a.y < by2 && ay2 > b.y
+}
+
+function looksUncertainLabel(label: string | undefined): boolean {
+  return !label || /\b(unknown|uncertain|maybe|todo|tbd)\b|\?/.test(label.toLowerCase())
+}
+
+function addCheapReviewFlags(shapes: ExamCanvasShapeModel[], pages?: CanvasPageGeometry[]): ExamCanvasShapeModel[] {
+  const markAreasByQuestion = new Set(shapes.filter((shape) => shape.kind === 'mark_area' && shape.questionId).map((shape) => shape.questionId as string))
+  return shapes.map((shape, index) => {
+    const flags: string[] = []
+    if (shape.source === 'ai' && shape.confirmed === false) flags.push('unconfirmed AI')
+    if (typeof shape.confidence === 'number' && shape.confidence < 0.7) flags.push('low confidence')
+    if ((shape.kind === 'part' || shape.kind === 'question_number') && looksUncertainLabel(shape.label)) flags.push('uncertain question label')
+    if (shape.kind === 'part' && (!shape.maxMarks || shape.maxMarks <= 0) && !markAreasByQuestion.has(shape.questionId ?? shape.id)) flags.push('missing marks')
+    const samePageOverlap = shapes.some((other, otherIndex) => otherIndex !== index && shape.kind !== 'boundary' && other.kind !== 'boundary' && pageForShape(shape, pages) === pageForShape(other, pages) && overlaps(shape, other) && (shape.kind === other.kind || (!contains(bounds(shape), bounds(other)) && !contains(bounds(other), bounds(shape)))))
+    if (samePageOverlap) flags.push('overlapping shapes')
+    return flags.length ? { ...shape, reviewFlags: flags } : shape
+  })
 }