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

@@ -70,7 +70,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");
 
@@ -99,6 +99,11 @@ export default function CourseDashboard() {
   const labelForFilter =
     activeFilter === "all" ? "All" : activeFilter.charAt(0).toUpperCase() + activeFilter.slice(1);
 
+  // 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 />
@@ -108,15 +113,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">
-                {labelForFilter} Courses
+                {firstRun ? "Courses" : `${labelForFilter} Courses`}
               </h2>
-              <p className="mt-0.5 mb-0 text-[13px] text-zinc-500 dark:text-zinc-400">
-                {props.total} course{props.total !== 1 ? "s" : ""} total
-              </p>
+              {!firstRun && (
+                <p className="mt-0.5 mb-0 text-[13px] text-zinc-500 dark:text-zinc-400">
+                  {props.total} course{props.total !== 1 ? "s" : ""} 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 (
@@ -136,13 +143,65 @@ export default function CourseDashboard() {
             </div>
           </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">No courses match this filter</p>
-            </div>
-          )}
+          {/* Empty states — three different situations, three different answers. */}
+          {filtered.length === 0 &&
+            (props.total === 0 ? (
+              props.status === "all" ? (
+                /* First run: no courses exist at all, so there is no filter to
+                   blame and the teacher needs a way forward, not 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">
+                    No courses yet
+                  </p>
+                  <p className="mx-auto mt-1.5 mb-0 max-w-sm text-[13px] text-zinc-500 dark:text-zinc-400">
+                    Your first course is where lessons, exams and enrollments
+                    live. Start with a title and an outline — you can publish it
+                    later.
+                  </p>
+                  <button
+                    onClick={() =>
+                      sendFollowUpMessage(
+                        "I'd like to create my first course. Ask me for a title and what it should cover, then create it."
+                      )
+                    }
+                    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"
+                  >
+                    Create my first course
+                  </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">
+                    No {props.status} courses yet
+                  </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">No courses match this filter</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"
+                >
+                  Show all {props.total} course{props.total !== 1 ? "s" : ""}
+                </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">
+                  No courses on this page — {props.total} in total
+                </p>
+              </div>
+            ))}
 
           {/* Card grid */}
           <div className="grid grid-cols-[repeat(auto-fill,minmax(260px,1fr))] gap-4">

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

@@ -7,14 +7,16 @@ import {
   type WidgetMetadata,
 } from "mcp-use/react";
 import { Brand } from "../shared/branding";
+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(),
@@ -206,8 +208,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)}
                     </span>
                     <span className="text-[13px] font-semibold text-zinc-900 dark:text-zinc-100">
                       {sub.score != null ? `${sub.score}%` : "—"}

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

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+
+/** Placeholder shown in place of a name we do not have. */
+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. */
+export function studentDisplayName(name: string | null | undefined): string {
+  return isNamedStudent(name) ? name!.trim() : UNNAMED_STUDENT;
+}
+
+/**
+ * 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

@@ -6,6 +6,11 @@ import {
   type WidgetMetadata,
 } from "mcp-use/react";
 import { Brand } from "../shared/branding";
+import {
+  isNamedStudent,
+  studentDisplayName,
+  studentInitials,
+} from "../shared/student-display";
 import { z } from "zod";
 
 // ── Schema ──────────────────────────────────────────────────────────────────
@@ -74,12 +79,24 @@ function progressColor(pct: number | null): string {
   return "bg-red-600 dark:bg-red-400";
 }
 
-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. `—` is this widget's glyph
+ * for "no data" everywhere else, so it may only mean "has not sat an exam" —
+ * a submission that is 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) {
+  if (count > 0 && avg == null) {
+    return {
+      value: "Ungraded",
+      valueClass:
+        "text-[12.5px] font-semibold text-amber-600 dark:text-amber-400",
+    };
   }
-  return id.slice(0, 2).toUpperCase();
+  return {
+    value: avg == null ? "—" : `${avg}%`,
+    valueClass: "text-sm font-bold text-zinc-900 dark:text-zinc-100",
+  };
 }
 
 // ── Component ────────────────────────────────────────────────────────────────
@@ -171,7 +188,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);
+              const exam = examCell(s.exam_avg, s.exam_count);
               return (
                 <div
                   key={s.student_id}
@@ -183,13 +202,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 && (
@@ -221,10 +246,8 @@ export default function StudentProgressRoster() {
                     </div>
                   </div>
 
-                  <div className="min-w-16 shrink-0 text-right">
-                    <div className="text-sm font-bold text-zinc-900 dark:text-zinc-100">
-                      {s.exam_avg == null ? "—" : `${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">
                       {s.exam_count} exam{s.exam_count === 1 ? "" : "s"}
                     </div>

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

@@ -7,6 +7,7 @@ import {
   type WidgetMetadata,
 } from "mcp-use/react";
 import { Brand } from "../shared/branding";
+import { studentDisplayName } from "../shared/student-display";
 import { z } from "zod";
 import { Markdown } from "../shared/markdown";
 
@@ -163,7 +164,7 @@ export default function SubmissionGrader() {
     });
   };
 
-  const studentName = submission.student_name ?? submission.student_id.slice(0, 8);
+  const studentName = studentDisplayName(submission.student_name);
   const saveDisabled = saving || (!dirty && status === "teacher_reviewed");
 
   return (