@anantagnanam/lms 0.1.0 → 0.3.0

package/astro/components/MediaPlayer.astro

@@ -4,8 +4,9 @@ interface Props {
   kind: "video" | "audio" | "live";
   title: string;
   startsAt?: string | null;
+  captions?: { src: string; language: string; label: string }[];
 }
-const { url, kind, title, startsAt } = Astro.props;
+const { url, kind, title, startsAt, captions = [] } = Astro.props;
 let embed: string | null = null;
 try {
   const parsed = new URL(url, Astro.url.origin);
@@ -24,7 +25,7 @@ try {
 } catch {}
 ---
 
-<div class="lms-media">
+<div class="lms-media" data-lms-media>
   {kind === "live" ? (
     <div class="lms-live-card">
       <p class="lms-eyebrow">LIVE LEARNING SESSION</p>
@@ -40,7 +41,23 @@ try {
       </a>
     </div>
   ) : kind === "audio" ? (
-    <audio src={url} controls preload="metadata" aria-label={title}></audio>
+    <audio
+      src={url}
+      controls
+      preload="metadata"
+      aria-label={title}
+      crossorigin={captions.length ? "anonymous" : undefined}
+    >
+      {captions.map((track, index) => (
+        <track
+          kind="captions"
+          src={track.src}
+          srclang={track.language}
+          label={track.label}
+          default={index === 0}
+        />
+      ))}
+    </audio>
   ) : embed ? (
     <iframe
       src={embed}
@@ -50,7 +67,41 @@ try {
       referrerpolicy="strict-origin-when-cross-origin"
     ></iframe>
   ) : (
-    <video src={url} controls preload="metadata" aria-label={title}></video>
+    <video
+      src={url}
+      controls
+      preload="metadata"
+      aria-label={title}
+      crossorigin={captions.length ? "anonymous" : undefined}
+    >
+      {captions.map((track, index) => (
+        <track
+          kind="captions"
+          src={track.src}
+          srclang={track.language}
+          label={track.label}
+          default={index === 0}
+        />
+      ))}
+    </video>
+  )}
+  {kind !== "live" && !embed && (
+    <div class="lms-actions">
+      <label>
+        Playback speed{" "}
+        <select data-lms-speed aria-label="Playback speed">
+          {[0.5, 0.75, 1, 1.25, 1.5, 1.75, 2].map((rate) => (
+            <option value={rate} selected={rate === 1}>
+              {rate}×
+            </option>
+          ))}
+        </select>
+      </label>
+      <button type="button" class="lms-btn lms-btn-outline" data-lms-playback-save hidden>
+        Save position
+      </button>
+      <span data-lms-feedback aria-live="polite"></span>
+    </div>
   )}
   {kind !== "live" && (
     <a class="lms-media-link" href={url} target="_blank" rel="noopener noreferrer">

package/astro/draft-queue.ts

@@ -0,0 +1,95 @@
+export type DraftState = "saved" | "pending" | "saving" | "failed" | "conflict";
+export interface DraftWrite<T> {
+  value: T;
+  expectedDraftRevision: number;
+}
+const fingerprint = (value: object) =>
+  JSON.stringify(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
+
+/** Serialize writes and preserve the exact unacknowledged request for retries. */
+export class DraftQueue<T extends object> {
+  revision: number;
+  state: DraftState = "saved";
+  private latest: T;
+  private acknowledged: string;
+  private retry?: DraftWrite<T>;
+  private running?: Promise<void>;
+  private disposed = false;
+  constructor(
+    value: T,
+    revision: number,
+    private send: (write: DraftWrite<T>) => Promise<{ draftRevision: number }>,
+    private changed: (state: DraftState) => void,
+  ) {
+    this.latest = structuredClone(value);
+    this.acknowledged = fingerprint(value);
+    this.revision = revision;
+  }
+  get dirty() {
+    return !!this.retry || fingerprint(this.latest) !== this.acknowledged;
+  }
+  private emit(state: DraftState) {
+    this.state = state;
+    if (!this.disposed) this.changed(state);
+  }
+  update(value: T) {
+    this.latest = structuredClone(value);
+    if (!["failed", "conflict", "saving"].includes(this.state))
+      this.emit(this.dirty ? "pending" : "saved");
+  }
+  flush(): Promise<void> {
+    if (this.disposed) return Promise.reject(new Error("This form has closed."));
+    if (this.state === "conflict")
+      return Promise.reject(new Error("Review the saved draft before continuing."));
+    if (this.running) return this.running;
+    this.running = this.drain().finally(() => {
+      this.running = undefined;
+    });
+    return this.running;
+  }
+  private async drain() {
+    while (this.dirty && !this.disposed) {
+      const write = this.retry ?? {
+        value: structuredClone(this.latest),
+        expectedDraftRevision: this.revision,
+      };
+      this.retry = write;
+      this.emit("saving");
+      try {
+        const result = await this.send(structuredClone(write));
+        this.revision = result.draftRevision;
+        this.acknowledged = fingerprint(write.value);
+        this.retry = undefined;
+      } catch (error) {
+        const failure = error as { code?: string; status?: number };
+        // A definite rejection did not persist the write. Allow corrected values on retry.
+        if (
+          failure.status &&
+          failure.status < 500 &&
+          failure.status !== 408 &&
+          failure.status !== 429 &&
+          failure.code !== "DRAFT_CONFLICT"
+        )
+          this.retry = undefined;
+        this.emit((error as { code?: string })?.code === "DRAFT_CONFLICT" ? "conflict" : "failed");
+        throw error;
+      }
+    }
+    this.emit(this.dirty ? "pending" : "saved");
+  }
+  conflict() {
+    this.emit("conflict");
+  }
+  /** Only after the learner has reviewed the current saved draft. */
+  reconcile(value: T, revision: number, keepLocal: boolean) {
+    if (this.running) throw new Error("Wait for the current save to finish.");
+    this.revision = revision;
+    this.acknowledged = fingerprint(value);
+    this.retry = undefined;
+    if (!keepLocal) this.latest = structuredClone(value);
+    this.emit(this.dirty ? "pending" : "saved");
+  }
+  dispose() {
+    this.disposed = true;
+  }
+}

package/astro/media-player.ts

@@ -0,0 +1,124 @@
+import type { Playback } from "@anantagnanam/lms/types";
+
+type Call = <T>(route: string, input: Record<string, unknown>, method?: string) => Promise<T>;
+
+/** Provider iframes own their controls. Only native media participates in resume. */
+export function initializeMedia(call: Call) {
+  for (const root of document.querySelectorAll<HTMLElement>(
+    "[data-lms-media]:not([data-lms-bound])",
+  )) {
+    root.dataset.lmsBound = "true";
+    const media = root.querySelector<HTMLMediaElement>("video, audio");
+    if (!media) continue;
+    const lesson = root.closest<HTMLElement>("[data-lms-lesson]");
+    const speed = root.querySelector<HTMLSelectElement>("[data-lms-speed]")!;
+    const button = root.querySelector<HTMLButtonElement>("[data-lms-playback-save]")!;
+    const status = root.querySelector<HTMLElement>("[data-lms-feedback]")!;
+    const saved: Playback | undefined = lesson?.dataset.playback
+      ? JSON.parse(lesson.dataset.playback)
+      : undefined;
+    let revision = saved?.revision ?? 0;
+    let ready = false;
+    let busy = false;
+    let pending = false;
+    let failed = false;
+    let disposed = false;
+    let lastSave = Date.now();
+    const enabled = Boolean(lesson && lesson.dataset.preview !== "true");
+    const seekBookmark = () => {
+      const raw = new URLSearchParams(window.location.hash.slice(1)).get("t");
+      if (!ready || disposed || raw === null || !/^\d+(?:\.\d+)?$/.test(raw)) return;
+      const position = Number(raw);
+      if (!Number.isFinite(position) || position > 86_400) return;
+      try {
+        media.currentTime = Number.isFinite(media.duration)
+          ? Math.min(position, Math.max(0, media.duration - 0.1))
+          : position;
+        status.textContent = `Bookmark at ${Math.floor(media.currentTime / 60)}:${String(Math.floor(media.currentTime % 60)).padStart(2, "0")}. Press play when ready.`;
+      } catch {
+        status.textContent = "This media is not seekable yet.";
+      }
+    };
+    button.hidden = !enabled;
+    const restore = () => {
+      if (ready) return;
+      ready = true;
+      if (saved) {
+        const position = Number.isFinite(media.duration)
+          ? Math.min(saved.positionSeconds, Math.max(0, media.duration - 0.1))
+          : saved.positionSeconds;
+        try {
+          media.currentTime = position;
+          media.playbackRate = saved.playbackRate;
+        } catch {
+          /* The browser may not have a seekable range yet. */
+        }
+        speed.value = String(media.playbackRate);
+        status.textContent = `Resumed at ${Math.floor(position / 60)}:${String(Math.floor(position % 60)).padStart(2, "0")}.`;
+      }
+      seekBookmark();
+    };
+    const save = async () => {
+      if (disposed || !enabled || !ready || failed || !Number.isFinite(media.currentTime)) return;
+      if (busy) {
+        pending = true;
+        return;
+      }
+      busy = true;
+      button.disabled = true;
+      pending = false;
+      status.textContent = "Saving playback position…";
+      try {
+        const result = await call<Playback>("learner/playback", {
+          courseId: lesson!.dataset.courseId,
+          lessonId: lesson!.dataset.lessonId,
+          positionSeconds: Math.min(media.currentTime, 86_400),
+          playbackRate: media.playbackRate,
+          expectedRevision: revision,
+        });
+        revision = result.revision;
+        lastSave = Date.now();
+        status.textContent = "Playback position saved.";
+      } catch (error) {
+        // A lost response can follow a successful write. Stop instead of overwriting another tab.
+        failed = true;
+        status.textContent = `${error instanceof Error ? error.message : "Could not save playback."} Reload this lesson before saving again.`;
+        status.setAttribute("role", "alert");
+      } finally {
+        busy = false;
+        button.disabled = failed;
+        if (pending && !failed) void save();
+      }
+    };
+    media.addEventListener("loadedmetadata", restore);
+    if (media.readyState >= 1) restore();
+    speed.addEventListener("change", () => {
+      media.playbackRate = Number(speed.value);
+    });
+    media.addEventListener("ratechange", () => {
+      speed.value = String(media.playbackRate);
+      void save();
+    });
+    media.addEventListener("timeupdate", () => {
+      if (!busy && Date.now() - lastSave >= 15_000) void save();
+    });
+    media.addEventListener("pause", () => {
+      void save();
+    });
+    media.addEventListener("ended", () => {
+      void save();
+    });
+    button.addEventListener("click", () => {
+      void save();
+    });
+    window.addEventListener("hashchange", seekBookmark);
+    document.addEventListener(
+      "astro:before-swap",
+      () => {
+        disposed = true;
+        window.removeEventListener("hashchange", seekBookmark);
+      },
+      { once: true },
+    );
+  }
+}

package/astro/pages/author-preview.astro

@@ -0,0 +1,73 @@
+---
+import Layout from "virtual:anantagnanam-lms/layout";
+import LearningShell from "../components/LearningShell.astro";
+import LessonContent from "../components/LessonContent.astro";
+import AssignmentRubric from "../components/AssignmentRubric.astro";
+import { lmsAuthorLessonPreview, loginUrl, LmsError } from "@anantagnanam/lms/server";
+import { loginPath } from "virtual:anantagnanam-lms/config";
+export const prerender = false;
+Astro.response.headers.set("Cache-Control", "private, no-store");
+Astro.response.headers.set("X-Robots-Tag", "noindex, nofollow");
+let result: Awaited<ReturnType<typeof lmsAuthorLessonPreview>> | undefined;
+let error = "";
+try {
+  result = await lmsAuthorLessonPreview(
+    Astro.locals,
+    { courseId: Astro.params.courseId!, lessonId: Astro.params.lessonId! },
+    Astro.url.origin,
+  );
+} catch (cause) {
+  Astro.response.status = cause instanceof LmsError ? cause.status : 503;
+  error = cause instanceof Error ? cause.message : "Preview is unavailable.";
+}
+---
+
+<Layout
+  title={result ? `Preview: ${result.lesson.title}` : "Lesson preview"}
+  robots="noindex, nofollow"
+>
+  <LearningShell>
+    {result ? (
+      <article class="lms-lesson">
+        <p class="lms-notice">
+          Saved author preview · {result.course.title}. Save changes in the course editor, then
+          refresh this page. Linked content uses its published version.
+        </p>
+        <h1>{result.lesson.title}</h1>
+        {result.lesson.summary && <p class="lms-lead">{result.lesson.summary}</p>}
+        <LessonContent lesson={result.lesson} />
+        {result.lesson.quiz && (
+          <section class="lms-assessment">
+            <h2>Lesson quiz</h2>
+            <p>
+              {result.lesson.quiz.questionCount} questions · Pass with{" "}
+              {result.lesson.quiz.passingPercent}% · {result.lesson.quiz.maxAttempts} attempts
+            </p>
+            <p>Assessment summary only. This preview does not create an attempt.</p>
+          </section>
+        )}
+        {result.lesson.assignment && (
+          <section class="lms-assessment">
+            <h2>Your assignment</h2>
+            <p class="lms-text">{result.lesson.assignment.instructions}</p>
+            <AssignmentRubric rubric={result.lesson.assignment.rubric} />
+            <p>
+              {result.lesson.assignment.passingPoints}/{result.lesson.assignment.maxPoints} points
+              to pass
+            </p>
+          </section>
+        )}
+      </article>
+    ) : (
+      <section class="lms-gate">
+        <h1>Lesson preview</h1>
+        <p>{error}</p>
+        {!Astro.locals.user && (
+          <a class="lms-btn" href={loginUrl(loginPath, Astro.url.pathname)}>
+            Sign in →
+          </a>
+        )}
+      </section>
+    )}
+  </LearningShell>
+</Layout>

package/astro/pages/course.astro

@@ -60,6 +60,16 @@ try {
   robots={course ? undefined : "noindex, follow"}
 >
   <LearningShell>
+    {course && Astro.locals.user && (
+      <form class="lms-actions" data-lms-route="learner/saved/save">
+        <input type="hidden" name="courseId" value={course.id} />
+        <input type="hidden" name="saved" value="true" />
+        <button class="lms-btn lms-btn-outline" type="submit">
+          Save course to my library
+        </button>
+        <p data-lms-feedback aria-live="polite"></p>
+      </form>
+    )}
     {course ? (
       <CourseOverview
         course={course}

package/astro/pages/lesson.astro

@@ -2,6 +2,7 @@
 import Layout from "virtual:anantagnanam-lms/layout";
 import LearningShell from "../components/LearningShell.astro";
 import LessonPlayer from "../components/LessonPlayer.astro";
+import LessonAvailabilityNote from "../components/LessonAvailabilityNote.astro";
 import { lmsPublic, lmsLearner, courseUrl, loginUrl, LmsError } from "@anantagnanam/lms/server";
 import { basePath, loginPath } from "virtual:anantagnanam-lms/config";
 import type {
@@ -27,6 +28,7 @@ try {
     }>(Astro.locals, "learner/course-by-slug", { slug: Astro.params.slug }, Astro.url.origin);
     course = result.course;
     enrollment = result.enrollment;
+    progress = result.progress;
   } else
     course = await lmsPublic<CourseDetail>(
       Astro.locals,
@@ -84,6 +86,7 @@ try {
         <p class="lms-eyebrow">ONE STEP AT A TIME</p>
         <h1>Continue your learning</h1>
         <p>{error}</p>
+        <LessonAvailabilityNote availability={progress?.availability[Astro.params.lessonId!]} />
         {!Astro.locals.user && (
           <a class="lms-btn" href={loginUrl(loginPath, Astro.url.pathname)}>
             Sign in →

package/astro/pages/library.astro

@@ -0,0 +1,173 @@
+---
+import Layout from "virtual:anantagnanam-lms/layout";
+import LearningShell from "../components/LearningShell.astro";
+import { lmsLearner, loginUrl, courseUrl, LmsError } from "@anantagnanam/lms/server";
+import { basePath, loginPath } from "virtual:anantagnanam-lms/config";
+import type { Page, CourseCard, LearnerPath, LearnerPreferences } from "@anantagnanam/lms/types";
+export const prerender = false;
+Astro.response.headers.set("Cache-Control", "private, no-store");
+if (!Astro.locals.user)
+  return Astro.redirect(loginUrl(loginPath, Astro.url.pathname + Astro.url.search));
+let saved: Page<{ courseId: string; course: CourseCard | null }> = { items: [], hasMore: false };
+let paths: Page<LearnerPath> = { items: [], hasMore: false };
+let preferences: { value: LearnerPreferences; revision: string | null } | undefined;
+let error = "";
+try {
+  [saved, paths, preferences] = await Promise.all([
+    lmsLearner<typeof saved>(
+      Astro.locals,
+      "learner/saved",
+      { cursor: Astro.url.searchParams.get("saved") ?? undefined },
+      Astro.url.origin,
+    ),
+    lmsLearner<typeof paths>(
+      Astro.locals,
+      "learner/paths",
+      { cursor: Astro.url.searchParams.get("paths") ?? undefined },
+      Astro.url.origin,
+    ),
+    lmsLearner<NonNullable<typeof preferences>>(
+      Astro.locals,
+      "learner/preferences",
+      {},
+      Astro.url.origin,
+    ),
+  ]);
+} catch (cause) {
+  Astro.response.status = cause instanceof LmsError ? cause.status : 503;
+  error = cause instanceof Error ? cause.message : "Your library is unavailable.";
+}
+const more = (key: string, cursor: string) => {
+  const url = new URL(Astro.url);
+  url.searchParams.set(key, cursor);
+  return url.href;
+};
+---
+
+<Layout title="My library and preferences" robots="noindex, follow">
+  <LearningShell>
+    <h1>My library &amp; preferences</h1>
+    {error && <p role="alert">{error}</p>}
+    <section>
+      <h2>Saved courses</h2>
+      {!error && !saved.items.length && (
+        <p>Save a course from its overview to find it here later.</p>
+      )}
+      {saved.items.map(({ courseId, course }) => (
+        <article class="lms-learning-card">
+          <h3>
+            {course ? (
+              <a href={courseUrl(basePath, course.slug)}>{course.title}</a>
+            ) : (
+              "Course currently unavailable"
+            )}
+          </h3>
+          <form data-lms-route="learner/saved/save" data-lms-reload>
+            <input type="hidden" name="courseId" value={courseId} />
+            <input type="hidden" name="saved" value="false" />
+            <button class="lms-text-button" type="submit">
+              Remove from saved courses
+            </button>
+            <p data-lms-feedback aria-live="polite"></p>
+          </form>
+        </article>
+      ))}
+      {saved.hasMore && saved.cursor && (
+        <a href={more("saved", saved.cursor)}>More saved courses →</a>
+      )}
+    </section>
+    <section>
+      <h2>My learning paths</h2>
+      <p>
+        Your joined paths keep their original course lists when administrators edit the program.
+      </p>
+      {!error && !paths.items.length && <a href={`${basePath}/paths`}>Explore learning paths</a>}
+      {paths.items.map((path) => (
+        <article class="lms-learning-card">
+          <h3>{path.title}</h3>
+          <p>
+            {path.completed} of {path.total} courses completed
+          </p>
+          <progress value={path.completed} max={path.total} aria-label={`${path.title} progress`}>
+            {path.completed}/{path.total}
+          </progress>
+          <ol>
+            {path.courses.map(({ course, completed }) => (
+              <li>
+                {course ? (
+                  <a href={courseUrl(basePath, course.slug)}>{course.title}</a>
+                ) : (
+                  "Course currently unavailable"
+                )}
+                {completed && " · Completed"}
+              </li>
+            ))}
+          </ol>
+        </article>
+      ))}
+      {paths.hasMore && paths.cursor && (
+        <a href={more("paths", paths.cursor)}>More joined paths →</a>
+      )}
+    </section>
+    {preferences && (
+      <section class="lms-learning-card">
+        <h2>Learning preferences</h2>
+        <form class="lms-form" data-lms-route="learner/preferences/save" data-lms-reload>
+          <input type="hidden" name="expectedRevision" value={preferences.revision ?? ""} />
+          <label>
+            <span>Email updates</span>
+            <select name="emailNotifications">
+              <option value="true" selected={preferences.value.emailNotifications}>
+                Enabled when the academy sends email
+              </option>
+              <option value="false" selected={!preferences.value.emailNotifications}>
+                Off
+              </option>
+            </select>
+          </label>
+          <label>
+            <span>Weekly lesson goal</span>
+            <input
+              type="number"
+              name="weeklyGoalLessons"
+              min="0"
+              max="100"
+              value={preferences.value.weeklyGoalLessons}
+            />
+          </label>
+          <p>
+            Set 0 for no goal. Your goal is a personal target; it does not change deadlines or
+            completion requirements.
+          </p>
+          <button class="lms-btn" type="submit">
+            Save preferences
+          </button>
+          <p data-lms-feedback aria-live="polite"></p>
+        </form>
+      </section>
+    )}
+    <section class="lms-learning-card" data-lms-export>
+      <h2>Download my learning data</h2>
+      <p>
+        Download each section as JSON, five records per page. Continue until all pages are
+        downloaded. Exports include only your records and omit quiz answer keys.
+      </p>
+      <label>
+        Data section{" "}
+        <select data-lms-export-section>
+          <option value="enrollments">Learning history, notes and assessments</option>
+          <option value="discussions">Discussion contributions</option>
+          <option value="reviews">Course reviews</option>
+          <option value="notifications">Notifications</option>
+          <option value="saved_courses">Saved courses</option>
+          <option value="path_enrollments">Joined paths</option>
+          <option value="cohort_enrollments">Cohort membership</option>
+        </select>
+      </label>
+      <button type="button" class="lms-btn" data-lms-export-download>
+        Download first page
+      </button>
+      <p data-lms-feedback aria-live="polite"></p>
+    </section>
+  </LearningShell>
+</Layout>

package/astro/pages/paths.astro

@@ -0,0 +1,73 @@
+---
+import Layout from "virtual:anantagnanam-lms/layout";
+import LearningShell from "../components/LearningShell.astro";
+import { lmsPublic, courseUrl, loginUrl, LmsError } from "@anantagnanam/lms/server";
+import { basePath, loginPath } from "virtual:anantagnanam-lms/config";
+import type { Page, PublicPath } from "@anantagnanam/lms/types";
+export const prerender = false;
+Astro.response.headers.set("Cache-Control", "private, no-store");
+let page: Page<PublicPath> = { items: [], hasMore: false };
+let error = "";
+try {
+  page = await lmsPublic<typeof page>(
+    Astro.locals,
+    "paths",
+    { cursor: Astro.url.searchParams.get("cursor") ?? undefined },
+    Astro.url.origin,
+  );
+} catch (cause) {
+  Astro.response.status = cause instanceof LmsError ? cause.status : 503;
+  error = cause instanceof Error ? cause.message : "Learning paths unavailable.";
+}
+const next = new URL(Astro.url);
+next.searchParams.set("cursor", page.cursor ?? "");
+---
+
+<Layout title="Learning paths">
+  <LearningShell>
+    <h1>Learning paths</h1>
+    <p class="lms-lead">
+      Follow an ordered program of courses and track your progress in your library.
+    </p>
+    <p>
+      Join a path to save its course list. Enroll in each course separately; approval and
+      prerequisites still apply.
+    </p>
+    {error && <p role="alert">{error}</p>}
+    {!error && !page.items.length && <p>No learning paths have been published yet.</p>}
+    {page.items.map((path) => (
+      <article class="lms-learning-card">
+        <h2>{path.title}</h2>
+        <p class="lms-text">{path.description}</p>
+        <ol>
+          {path.courses.map((course) => (
+            <li>
+              {course ? (
+                <a href={courseUrl(basePath, course.slug)}>{course.title}</a>
+              ) : (
+                "Course currently unavailable"
+              )}
+            </li>
+          ))}
+        </ol>
+        {Astro.locals.user ? (
+          <form data-lms-route="learner/path/join">
+            <input type="hidden" name="pathId" value={path.id} />
+            <button class="lms-btn" type="submit">
+              Join path
+            </button>
+            <a class="lms-btn lms-btn-outline" href={`${basePath}/my-learning/library`}>
+              View my paths
+            </a>
+            <p data-lms-feedback aria-live="polite"></p>
+          </form>
+        ) : (
+          <a class="lms-btn" href={loginUrl(loginPath, Astro.url.pathname)}>
+            Sign in to join
+          </a>
+        )}
+      </article>
+    ))}
+    {page.hasMore && page.cursor && <a href={next.href}>More learning paths →</a>}
+  </LearningShell>
+</Layout>