fix(widgets): stop rendering missing data as if it were real (#568)

Three widget states presented absent data as a value a teacher could act
on, plus three adjacent defects found while fixing them.

A student with no `profiles.full_name` rendered as a slice of their user
id — `u-008` in the name column, `U-` in the avatar. That is not a name,
identifies nobody, and reads as corrupted data. `student_name: null` is a
normal value (fetchProfileNames drops blanks), so the fallback now goes
through a shared `resources/shared/student-display.ts`: "Unnamed student"
in a muted italic that reads as a placeholder, and a neutral avatar glyph
instead of letters derived from an id. `submission-grader` had the same
`student_id.slice(0, 8)` fallback; `exam-submissions` declared
`student_name` non-nullable while its tool sends null, so a nameless
student rendered as an empty cell.

The roster showed "1 exam" beside an em dash — the same glyph it uses for
"no data" elsewhere — so an ungraded submission read as an exam scored
nothing. It now reads "Ungraded". That state was also unreachable from
real data: `exam_count` was incremented only `if (score != null)`, which
made an ungraded submission vanish entirely and the student read as "0
exams". The aggregation is extracted as `aggregateExamSubmissions()` and
now counts every submission while averaging only the graded ones.

The course dashboard blamed a filter for every empty result, including
the first-run case where no filter exists, the chips have collapsed to a
lone "All", and the teacher is offered no way forward. It now branches:
no courses at all (first-run copy plus a create-course action, chips
hidden), no courses of a server-filtered status, a chip that matched
nothing, and a page past the end of the list. That last case is newly
reachable because `lms_list_courses` was reporting a hardcoded
`total: 0` on an empty page, discarding the real count — which would have
shown a teacher with courses the "create your first course" screen.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VSGmz5frZqzbpQXJxxuqTs

Author: guillermoscript

mcp-server/resources/course-dashboard/widget.tsx

@@ -84,6 +84,19 @@ const STRINGS = {
       archived: "Archived",
     } as Record<string, string>,
     emptyFiltered: "No courses match this filter",
+    // A teacher with no courses at all is not looking at a filtered result —
+    // there is no filter to blame and they need a way forward, not a dead end.
+    headingFirstRun: "Courses",
+    emptyFirstRunTitle: "No courses yet",
+    emptyFirstRunBody:
+      "Your first course is where lessons, exams and enrollments live. Start with a title and an outline — you can publish it later.",
+    emptyFirstRunCta: "Create my first course",
+    // Sent to the model when that button is pressed.
+    emptyFirstRunPrompt:
+      "I'd like to create my first course. Ask me for a title and what it should cover, then create it.",
+    emptyStatus: (label: string) => `No ${label.toLowerCase()} courses yet`,
+    emptyPage: (count: string) => `No courses on this page — ${count} in total`,
+    showAll: (n: number, count: string) => `Show all ${count} course${n === 1 ? "" : "s"}`,
     lessons: (n: number, count: string) => `${count} lesson${n === 1 ? "" : "s"}`,
     enrolled: (count: string) => `${count} enrolled`,
   },
@@ -125,6 +138,17 @@ const STRINGS = {
       archived: "Archivado",
     } as Record<string, string>,
     emptyFiltered: "Ningún curso coincide con este filtro",
+    headingFirstRun: "Cursos",
+    emptyFirstRunTitle: "Todavía no tienes cursos",
+    emptyFirstRunBody:
+      "Tu primer curso es donde viven las lecciones, los exámenes y las inscripciones. Empieza con un título y un esquema — puedes publicarlo más tarde.",
+    emptyFirstRunCta: "Crear mi primer curso",
+    emptyFirstRunPrompt:
+      "Quiero crear mi primer curso. Pregúntame por el título y de qué debería tratar, y luego créalo.",
+    emptyStatus: (label: string) => `Todavía no hay cursos con el estado «${label.toLowerCase()}»`,
+    emptyPage: (count: string) => `No hay cursos en esta página — ${count} en total`,
+    showAll: (n: number, count: string) =>
+      `Ver ${n === 1 ? "el" : "los"} ${count} curso${n === 1 ? "" : "s"}`,
     lessons: (n: number, count: string) =>
       `${count} ${n === 1 ? "lección" : "lecciones"}`,
     enrolled: (count: string) => `${count} inscritos`,
@@ -161,7 +185,7 @@ function statusColor(status: string): string {
 // ── Component ────────────────────────────────────────────────────────────────
 
 export default function CourseDashboard() {
-  const { props, isPending } = useWidget<Props>();
+  const { props, isPending, sendFollowUpMessage } = useWidget<Props>();
   const theme = useWidgetTheme();
   const [activeFilter, setActiveFilter] = useState<string>("all");
 
@@ -189,6 +213,11 @@ export default function CourseDashboard() {
       ? props.courses
       : props.courses.filter((c) => c.status === activeFilter);
 
+  // With nothing to filter, the chip row collapses to a lone "All" that does
+  // nothing — a control the empty-state copy would otherwise be pointing at.
+  const hasFilters = props.courses.length > 0 && allStatuses.length > 1;
+  const firstRun = props.total === 0 && props.status === "all";
+
   return (
     <McpUseProvider autoSize>
       <Brand />
@@ -198,15 +227,17 @@ export default function CourseDashboard() {
           <div className="mb-5 flex flex-wrap items-center justify-between gap-3">
             <div>
               <h2 className="m-0 text-xl font-semibold tracking-tight text-zinc-900 dark:text-zinc-100">
-                {t.heading(activeFilter)}
+                {firstRun ? t.headingFirstRun : t.heading(activeFilter)}
               </h2>
-              <p className="mt-0.5 mb-0 text-[13px] text-zinc-500 dark:text-zinc-400">
-                {t.totalCount(props.total, fmt.number(props.total))}
-              </p>
+              {!firstRun && (
+                <p className="mt-0.5 mb-0 text-[13px] text-zinc-500 dark:text-zinc-400">
+                  {t.totalCount(props.total, fmt.number(props.total))}
+                </p>
+              )}
             </div>
 
             {/* Status filter tabs */}
-            <div className="flex flex-wrap gap-1.5">
+            <div className={`flex flex-wrap gap-1.5 ${hasFilters ? "" : "hidden"}`}>
               {allStatuses.map((s) => {
                 const active = s === activeFilter;
                 return (
@@ -227,12 +258,55 @@ export default function CourseDashboard() {
           </div>
 
           {/* Empty state */}
-          {filtered.length === 0 && (
-            <div className="p-12 text-center text-zinc-400 dark:text-zinc-500">
-              <div className="mb-3 text-4xl">📚</div>
-              <p className="m-0 text-sm">{t.emptyFiltered}</p>
-            </div>
-          )}
+          {/* Empty states — four different situations, four different answers. */}
+          {filtered.length === 0 &&
+            (props.total === 0 ? (
+              firstRun ? (
+                /* No courses exist at all: no filter to blame, and a first-run
+                   teacher needs a way forward rather than a dead end. */
+                <div className="p-12 text-center">
+                  <div className="mb-3 text-4xl">📚</div>
+                  <p className="m-0 text-[15px] font-semibold text-zinc-900 dark:text-zinc-100">
+                    {t.emptyFirstRunTitle}
+                  </p>
+                  <p className="mx-auto mt-1.5 mb-0 max-w-sm text-[13px] text-zinc-500 dark:text-zinc-400">
+                    {t.emptyFirstRunBody}
+                  </p>
+                  <button
+                    onClick={() => sendFollowUpMessage(t.emptyFirstRunPrompt)}
+                    className="mt-4 cursor-pointer rounded-lg border border-[var(--brand-600)] bg-[var(--brand-600)] px-4 py-2 text-[13px] font-semibold text-white dark:border-[var(--brand-400)] dark:bg-[var(--brand-400)] dark:text-zinc-950"
+                  >
+                    {t.emptyFirstRunCta}
+                  </button>
+                </div>
+              ) : (
+                /* The tool itself was called with a status filter. */
+                <div className="p-12 text-center text-zinc-400 dark:text-zinc-500">
+                  <div className="mb-3 text-4xl">📚</div>
+                  <p className="m-0 text-sm">{t.emptyStatus(t.filterLabel(props.status))}</p>
+                </div>
+              )
+            ) : activeFilter !== "all" ? (
+              /* Courses exist; the chip above filtered them all out. */
+              <div className="p-12 text-center text-zinc-400 dark:text-zinc-500">
+                <div className="mb-3 text-4xl">📚</div>
+                <p className="m-0 text-sm">{t.emptyFiltered}</p>
+                <button
+                  onClick={() => setActiveFilter("all")}
+                  className="mt-3 cursor-pointer rounded-lg border border-zinc-200 bg-transparent px-3.5 py-1.5 text-[12.5px] font-medium text-zinc-500 dark:border-zinc-800 dark:text-zinc-400"
+                >
+                  {t.showAll(props.total, fmt.number(props.total))}
+                </button>
+              </div>
+            ) : (
+              /* Courses exist and no chip is active, so this page simply has no
+                 rows — an offset past the end of the list. Blaming a filter here
+                 would point at a control the teacher never touched. */
+              <div className="p-12 text-center text-zinc-400 dark:text-zinc-500">
+                <div className="mb-3 text-4xl">📚</div>
+                <p className="m-0 text-sm">{t.emptyPage(fmt.number(props.total))}</p>
+              </div>
+            ))}
 
           {/*
             Card grid, three shared rows: heading, body (description + tags),

mcp-server/resources/exam-submissions/widget.tsx

@@ -8,14 +8,16 @@ import {
 } from "mcp-use/react";
 import { Brand } from "../shared/branding";
 import { useFormat, useStrings } from "../shared/i18n";
+import { isNamedStudent, studentDisplayName } from "../shared/student-display";
 import { z } from "zod";
 import { Markdown } from "../shared/markdown";
 
 // ── Schema ──────────────────────────────────────────────────────────────────
 
 const submissionSchema = z.object({
   id: z.number(),
-  student_name: z.string(),
+  // `lms_list_exam_submissions` sends `null` when the profile has no full name.
+  student_name: z.string().nullable(),
   score: z.number().nullable(),
   submission_date: z.string(),
   review_status: z.string().nullable(),
@@ -52,6 +54,7 @@ const STRINGS = {
     colDate: "Date",
     colStatus: "Status",
     empty: "No submissions yet",
+    unnamedStudent: "Unnamed student",
     loadingDetails: "Loading details…",
     detailScore: "Score",
     detailReviewStatus: "Review status",
@@ -75,6 +78,7 @@ const STRINGS = {
     colDate: "Fecha",
     colStatus: "Estado",
     empty: "Todavía no hay entregas",
+    unnamedStudent: "Estudiante sin nombre",
     loadingDetails: "Cargando detalles…",
     detailScore: "Nota",
     detailReviewStatus: "Estado de revisión",
@@ -253,8 +257,14 @@ export default function ExamSubmissions() {
                         : "bg-transparent hover:bg-zinc-50 dark:hover:bg-zinc-800"
                     }`}
                   >
-                    <span className="overflow-hidden text-[13px] font-medium text-ellipsis whitespace-nowrap text-zinc-900 dark:text-zinc-100">
-                      {sub.student_name}
+                    <span
+                      className={`overflow-hidden text-[13px] font-medium text-ellipsis whitespace-nowrap ${
+                        isNamedStudent(sub.student_name)
+                          ? "text-zinc-900 dark:text-zinc-100"
+                          : "text-zinc-400 italic dark:text-zinc-500"
+                      }`}
+                    >
+                      {studentDisplayName(sub.student_name, t.unnamedStudent)}
                     </span>
                     <span className="text-[13px] font-semibold text-zinc-900 dark:text-zinc-100">
                       {fmt.percent(sub.score)}

mcp-server/resources/shared/student-display.ts

@@ -0,0 +1,49 @@
+/**
+ * How widgets render a student whose profile has no display name.
+ *
+ * `profiles.full_name` is nullable and `fetchProfileNames()` deliberately drops
+ * blanks, so `student_name: null` is a normal value on every roster — not an
+ * error case. Each widget used to invent its own fallback out of the user id
+ * (`student_id.slice(0, 8)`, initials from the same slice), which put strings
+ * like `u-008` and `U-` in the name column: a teacher reads that as corrupted
+ * data, and it identifies nobody. The id is not a name and must never stand in
+ * for one.
+ *
+ * Resolving the real person would mean their email, which lives in
+ * `auth.users` and is reachable only through `auth.admin.getUserById()` — a
+ * service-role call these tools cannot make on the caller's RLS-scoped client.
+ * So the honest answer is a generic placeholder, rendered visibly as a
+ * placeholder (see `isNamedStudent`) rather than passed off as a name.
+ */
+
+/** English placeholder; callers with a `STRINGS` table pass their own. */
+export const UNNAMED_STUDENT = "Unnamed student";
+
+/** Whether the roster actually knows this student's name. */
+export function isNamedStudent(name: string | null | undefined): boolean {
+  return !!name && name.trim().length > 0;
+}
+
+/**
+ * The name to render — never a user id.
+ *
+ * The placeholder is a widget-owned string, so it is translated like the rest
+ * of them (`resources/shared/i18n.tsx`) and passed in; a real `full_name` is
+ * database content and is always rendered verbatim.
+ */
+export function studentDisplayName(
+  name: string | null | undefined,
+  unnamedLabel: string = UNNAMED_STUDENT
+): string {
+  return isNamedStudent(name) ? name!.trim() : unnamedLabel;
+}
+
+/**
+ * Avatar initials. Degrades to a neutral glyph rather than letters derived from
+ * an id, which would read as someone's initials without being anyone's.
+ */
+export function studentInitials(name: string | null | undefined): string {
+  if (!isNamedStudent(name)) return "·";
+  const parts = name!.trim().split(/\s+/);
+  return ((parts[0]?.[0] ?? "") + (parts[1]?.[0] ?? "")) || "·";
+}

mcp-server/resources/student-progress-roster/widget.tsx

@@ -8,6 +8,7 @@ import {
 import { Brand } from "../shared/branding";
 import { useFormat, useStrings } from "../shared/i18n";
 import { NEUTRAL_TEXT, barClass, textClass } from "../shared/severity";
+import { isNamedStudent, studentDisplayName, studentInitials } from "../shared/student-display";
 import { z } from "zod";
 
 // ── Schema ──────────────────────────────────────────────────────────────────
@@ -71,6 +72,11 @@ const STRINGS = {
     lastActive: "last active",
     noAtRisk: "No at-risk students. 🎉",
     noStudents: "No students enrolled.",
+    // Shown when `profiles.full_name` is empty. Never the user id: that names
+    // nobody and reads as corrupted data.
+    unnamedStudent: "Unnamed student",
+    // An exam that was submitted but not yet scored — distinct from "no exam".
+    ungraded: "Ungraded",
   },
   es: {
     loading: "Cargando lista…",
@@ -87,17 +93,32 @@ const STRINGS = {
     lastActive: "última actividad",
     noAtRisk: "Ningún estudiante en riesgo. 🎉",
     noStudents: "No hay estudiantes inscritos.",
+    unnamedStudent: "Estudiante sin nombre",
+    ungraded: "Sin calificar",
   },
 };
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-function initials(name: string | null, id: string): string {
-  if (name) {
-    const parts = name.trim().split(/\s+/);
-    return (parts[0]?.[0] ?? "") + (parts[1]?.[0] ?? "");
+/**
+ * The exam column reads as three distinct states. `—` (what `fmt.percent`
+ * renders for null) is this widget's glyph for "no data" everywhere else, so it
+ * may only mean "has not sat an exam" — a submission waiting on a grade has to
+ * say so, or it reads as a student who took an exam and scored nothing.
+ */
+function examCell(
+  avg: number | null,
+  count: number,
+  ungradedLabel: string,
+  fmtPercent: (n: number | null) => string
+): { value: string; valueClass: string } {
+  if (count > 0 && avg == null) {
+    return {
+      value: ungradedLabel,
+      valueClass: "text-[12.5px] font-semibold text-amber-600 dark:text-amber-400",
+    };
   }
-  return id.slice(0, 2).toUpperCase();
+  return { value: fmtPercent(avg), valueClass: `text-sm font-bold ${textClass(avg)}` };
 }
 
 // ── Component ────────────────────────────────────────────────────────────────
@@ -195,7 +216,9 @@ export default function StudentProgressRoster() {
           <div className="flex flex-col gap-2">
             {visible.map((s: Student) => {
               const pct = s.progress_pct;
-              const name = s.student_name ?? s.student_id.slice(0, 8);
+              const named = isNamedStudent(s.student_name);
+              const name = studentDisplayName(s.student_name, t.unnamedStudent);
+              const exam = examCell(s.exam_avg, s.exam_count, t.ungraded, fmt.percent);
               return (
                 <div
                   key={s.student_id}
@@ -207,13 +230,19 @@ export default function StudentProgressRoster() {
                 >
                   {/* Avatar */}
                   <div className="flex size-9 shrink-0 items-center justify-center rounded-full bg-[var(--brand-50)] text-[13px] font-bold text-[var(--brand-600)] uppercase dark:bg-[var(--brand-950)] dark:text-[var(--brand-400)]">
-                    {initials(s.student_name, s.student_id)}
+                    {studentInitials(s.student_name)}
                   </div>
 
                   {/* Name + progress bar */}
                   <div className="min-w-40 flex-1">
                     <div className="mb-1.5 flex items-center gap-2">
-                      <span className="truncate text-sm font-semibold text-zinc-900 dark:text-zinc-100">
+                      <span
+                        className={`truncate text-sm ${
+                          named
+                            ? "font-semibold text-zinc-900 dark:text-zinc-100"
+                            : "font-medium text-zinc-400 italic dark:text-zinc-500"
+                        }`}
+                      >
                         {name}
                       </span>
                       {s.at_risk && (
@@ -248,10 +277,8 @@ export default function StudentProgressRoster() {
                     </div>
                   </div>
 
-                  <div className="min-w-16 shrink-0 text-right">
-                    <div className={`text-sm font-bold ${textClass(s.exam_avg)}`}>
-                      {fmt.percent(s.exam_avg)}
-                    </div>
+                  <div className="min-w-20 shrink-0 text-right">
+                    <div className={exam.valueClass}>{exam.value}</div>
                     <div className="text-[11px] text-zinc-400 dark:text-zinc-500">
                       {t.exams(s.exam_count, fmt.number(s.exam_count))}
                     </div>

mcp-server/resources/submission-grader/widget.tsx

@@ -8,6 +8,7 @@ import {
 } from "mcp-use/react";
 import { Brand } from "../shared/branding";
 import { useFormat, useStrings } from "../shared/i18n";
+import { studentDisplayName } from "../shared/student-display";
 import { z } from "zod";
 import { Markdown } from "../shared/markdown";
 
@@ -79,6 +80,7 @@ const STRINGS = {
     saving: "Saving…",
     saved: "Saved ✓",
     saveGrade: "Save grade",
+    unnamedStudent: "Unnamed student",
     saveFailed: "Save failed",
     submitted: "submitted",
     studentAnswer: "Student answer",
@@ -106,6 +108,7 @@ const STRINGS = {
     saving: "Guardando…",
     saved: "Guardado ✓",
     saveGrade: "Guardar nota",
+    unnamedStudent: "Estudiante sin nombre",
     saveFailed: "Error al guardar",
     submitted: "entregado el",
     studentAnswer: "Respuesta del estudiante",
@@ -210,7 +213,7 @@ export default function SubmissionGrader() {
     });
   };
 
-  const studentName = submission.student_name ?? submission.student_id.slice(0, 8);
+  const studentName = studentDisplayName(submission.student_name, t.unnamedStudent);
   const saveDisabled = saving || (!dirty && status === "teacher_reviewed");
 
   return (