@panaversity/ksor 0.0.29 → 0.0.31

package/templates/scaffold/system/site/components/deck-viewer.tsx

@@ -0,0 +1,195 @@
+"use client";
+
+import { ChevronLeft, ChevronRight, Maximize2 } from "lucide-react";
+import { useCallback, useRef, useState, type ReactElement } from "react";
+
+import { Button } from "@/components/ui/button";
+import type { DeckSlide } from "@/lib/attachments";
+
+/**
+ * A presentation the RECORD owns, rendered in the page.
+ *
+ * This is the mode that makes the workflow complete. An agent writes the
+ * slides from the document — no browser, no third party, no human step in the
+ * middle — and this draws them. Which means the deck is governed like every
+ * other attachment: reviewed in a PR, versioned with its document, withdrawn
+ * with it. An embedded deck is none of those things, and can rot into a dead
+ * link with nothing going red.
+ *
+ * Every slide is in the SERVER-RENDERED HTML, not fetched and not built on
+ * mount: a crawler, a reader with JavaScript off, and an agent parsing the page
+ * all get the whole deck. Only the *navigation* is client-side, so what the
+ * bytes carry never depends on a script running.
+ *
+ * The stage is dark in both themes (`.ksor-stage`, app/global.css). A slide is
+ * a PROJECTION and the page around it is a document; looking like the first
+ * thing while sitting inside the second is most of what makes a deck legible
+ * at a glance. The first version painted it `--muted` and it read as an empty
+ * placeholder — pale grey on a pale page, saying nothing.
+ */
+export function DeckViewer({
+  slides,
+  title,
+}: {
+  readonly slides: readonly DeckSlide[];
+  readonly title: string;
+}): ReactElement {
+  const [index, setIndex] = useState(0);
+  const frameRef = useRef<HTMLDivElement>(null);
+  const total = slides.length;
+
+  const go = useCallback(
+    (delta: number) => setIndex((i) => Math.min(total - 1, Math.max(0, i + delta))),
+    [total],
+  );
+
+  // Arrow keys, but ONLY while the deck has focus — a page-wide listener would
+  // hijack arrows from the reader scrolling the document.
+  const onKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (event.key === "ArrowRight" || event.key === "PageDown") {
+        event.preventDefault();
+        go(1);
+      } else if (event.key === "ArrowLeft" || event.key === "PageUp") {
+        event.preventDefault();
+        go(-1);
+      }
+    },
+    [go],
+  );
+
+  const present = useCallback(() => {
+    void frameRef.current?.requestFullscreen?.().catch(() => {
+      // Fullscreen is a nicety and is refused in plenty of ordinary contexts —
+      // an iframe without the permission, a browser that requires a gesture it
+      // did not see. The deck stays usable inline, so this is not an error.
+    });
+  }, []);
+
+  const current = slides[index];
+  if (current === undefined) return <></>;
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div
+        ref={frameRef}
+        tabIndex={0}
+        role="group"
+        aria-roledescription="presentation"
+        aria-label={`${title}, slide ${index + 1} of ${total}`}
+        onKeyDown={onKeyDown}
+        className="ksor-stage relative aspect-video w-full overflow-hidden rounded-xl border border-[var(--ksor-stage-rule)] shadow-[0_1px_2px_rgba(0,0,0,0.08),0_12px_28px_-12px_rgba(0,0,0,0.35)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
+      >
+        {/* The deck's own rule across the top: a slide theme in one line, and
+            the thing that stops the stage reading as a plain dark rectangle. */}
+        <div aria-hidden className="absolute inset-x-0 top-0 h-[3px] bg-fd-primary" />
+
+        {slides.map((slide, i) => (
+          <article
+            key={slide.heading + String(i)}
+            // Every slide is rendered; the inactive ones are hidden rather
+            // than absent, so the whole deck is in the shipped HTML.
+            hidden={i !== index}
+            aria-hidden={i !== index}
+            className="absolute inset-0 flex flex-col justify-center gap-6 px-[8%] pt-[8%] pb-[13%]"
+          >
+            <h3 className="font-(family-name:--font-display) text-[clamp(1.35rem,3.1vw,2.1rem)] leading-[1.15] font-semibold tracking-tight text-balance">
+              {slide.heading}
+            </h3>
+            {slide.lead === undefined ? null : (
+              <p className="ksor-stage-dim max-w-[42ch] text-[clamp(0.9rem,1.5vw,1.1rem)] leading-relaxed">
+                {slide.lead}
+              </p>
+            )}
+            {slide.bullets === undefined || slide.bullets.length === 0 ? null : (
+              <ul className="flex max-w-[48ch] flex-col gap-3">
+                {slide.bullets.map((bullet, k) => (
+                  <li
+                    key={`${bullet}-${k}`}
+                    className="flex gap-3 text-[clamp(0.85rem,1.4vw,1rem)] leading-snug"
+                  >
+                    {/* A square tick in the accent rather than a disc: it reads
+                        at projection distance, where a bullet dot disappears. */}
+                    <span
+                      aria-hidden
+                      className="mt-[0.45em] size-[0.42em] shrink-0 rounded-[1px] bg-fd-primary"
+                    />
+                    <span>{bullet}</span>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </article>
+        ))}
+
+        {/* The stage's own footer: the deck's name and the position, in mono,
+            the way a real deck carries its identity on every slide. */}
+        <div className="absolute inset-x-0 bottom-0 flex items-center justify-between gap-4 px-[8%] pb-[4%]">
+          <p className="ksor-stage-dim truncate font-mono text-[0.68rem] tracking-wide uppercase">
+            {title}
+          </p>
+          <p className="ksor-stage-dim shrink-0 font-mono text-[0.68rem] tabular-nums">
+            {index + 1} / {total}
+          </p>
+        </div>
+
+        {/* How far through the deck, drawn on the stage itself so it survives
+            fullscreen — where the controls below are not on screen at all. */}
+        <div aria-hidden className="ksor-stage-rule absolute inset-x-0 bottom-0 h-[2px]">
+          <div
+            className="h-full bg-fd-primary transition-[width] duration-200 motion-reduce:transition-none"
+            style={{ width: `${((index + 1) / total) * 100}%` }}
+          />
+        </div>
+      </div>
+
+      <div className="flex items-center justify-between gap-3">
+        <div className="flex items-center gap-1">
+          <Button variant="ghost" size="sm" onClick={() => go(-1)} disabled={index === 0}>
+            <ChevronLeft aria-hidden className="size-4" />
+            <span className="sr-only sm:not-sr-only">Back</span>
+          </Button>
+          <Button variant="ghost" size="sm" onClick={() => go(1)} disabled={index === total - 1}>
+            <span className="sr-only sm:not-sr-only">Next</span>
+            <ChevronRight aria-hidden className="size-4" />
+          </Button>
+        </div>
+
+        {/* Jump to any slide. Dots rather than a list, because a deck this
+            size is scanned rather than read, and they double as the shape of
+            how much is left. */}
+        <div className="flex flex-wrap items-center justify-center gap-1.5">
+          {slides.map((slide, i) => (
+            <button
+              key={`dot-${slide.heading}-${i}`}
+              type="button"
+              onClick={() => setIndex(i)}
+              aria-label={`Slide ${i + 1}: ${slide.heading}`}
+              aria-current={i === index ? "true" : undefined}
+              className={`h-1.5 rounded-full transition-all motion-reduce:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring ${
+                i === index
+                  ? "w-5 bg-fd-primary"
+                  : "w-1.5 bg-fd-border hover:bg-fd-muted-foreground"
+              }`}
+            />
+          ))}
+        </div>
+
+        <Button variant="ghost" size="sm" onClick={present}>
+          <Maximize2 aria-hidden className="size-3.5" />
+          <span className="font-mono text-xs tracking-wide uppercase">Present</span>
+        </Button>
+      </div>
+
+      {current.note === undefined ? null : (
+        // The presenter's note: what to SAY, never what the slide shows. Kept
+        // outside the stage so it is not projected when the deck is
+        // fullscreened, which is the whole point of a note.
+        <p className="border-s-2 border-fd-border ps-3 text-sm text-fd-muted-foreground">
+          <span className="font-mono text-xs tracking-wide uppercase">Say: </span>
+          {current.note}
+        </p>
+      )}
+    </div>
+  );
+}

package/templates/scaffold/system/site/components/quiz.tsx

@@ -0,0 +1,321 @@
+"use client";
+
+import { Check, RotateCcw, X } from "lucide-react";
+import { useCallback, useEffect, useMemo, useState, type ReactElement } from "react";
+
+import { StudyAidHeader } from "@/components/study-aids";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { Progress } from "@/components/ui/progress";
+import type { QuizEntry, QuizQuestion } from "@/lib/attachments";
+import { hasMoreRounds, roundOf } from "@/lib/quiz-round";
+
+/**
+ * Taking a quiz on the document you just read.
+ *
+ * The interaction model is the predecessor's and is the good part of it:
+ * answer, see IMMEDIATELY whether you were right, and read the explanation
+ * before moving on. Its own usage guide is explicit that this teaches through
+ * the mistake, which has more effect than a score revealed at the end — so the
+ * explanation is the point of the component and the score is a footnote.
+ *
+ * What is deliberately absent is everything the predecessor's `GatedQuiz`
+ * wrapper added: a sign-in gate, an XP modal, and a POST of the score to a
+ * progress API. The site is a static export with no backend, and decision 7
+ * fixes it as preview and review rather than an editor. A score here is the
+ * reader's, stays in their browser, and is sent nowhere.
+ */
+
+const STORAGE_VERSION = 1;
+
+interface Persisted {
+  readonly version: number;
+  /** questionHash -> the option index this reader chose. */
+  readonly answers: Record<string, number>;
+}
+
+function storageKey(quizPath: string): string {
+  return `ksor:quiz:${quizPath}`;
+}
+
+function readPersisted(quizPath: string): Record<string, number> {
+  try {
+    const raw = window.localStorage.getItem(storageKey(quizPath));
+    if (raw === null) return {};
+    const record = JSON.parse(raw) as Persisted;
+    // A version bump discards rather than migrates: the only thing lost is
+    // which options a reader clicked, and guessing at an old shape is how a
+    // reader ends up with someone else's answers against their questions.
+    if (record.version !== STORAGE_VERSION) return {};
+    return record.answers ?? {};
+  } catch {
+    // A private window, cleared site data, or storage disabled entirely. An
+    // unanswered quiz is a correct starting state, so this is not an error.
+    return {};
+  }
+}
+
+function writePersisted(quizPath: string, answers: Record<string, number>): void {
+  try {
+    window.localStorage.setItem(
+      storageKey(quizPath),
+      JSON.stringify({ version: STORAGE_VERSION, answers } satisfies Persisted),
+    );
+  } catch {
+    // Storage is a convenience here, never the record. Losing it costs the
+    // reader their place and nothing else.
+  }
+}
+
+/** The letter an author and a reader both use for an option index. */
+function letterOf(index: number): string {
+  return String.fromCharCode(65 + index);
+}
+
+export function Quiz({ quiz }: { quiz: QuizEntry }): ReactElement {
+  const size = quiz.questionsPerRound;
+  const banked = quiz.questions.length;
+  const canRedraw = hasMoreRounds(banked, size);
+
+  // Round zero is the authored order, chosen on the server AND the client so
+  // the first paint matches: `roundOf` returns the bank untouched when it fits
+  // in one round, and for a larger bank the shuffle happens only after mount
+  // (see the effect below). Sampling during render would differ between the
+  // server HTML and the first client render and would hydrate mismatched.
+  const [round, setRound] = useState<readonly QuizQuestion[]>(() =>
+    roundOf(quiz.questions, size, () => 0),
+  );
+  const [answers, setAnswers] = useState<Record<string, number>>({});
+  const [hydrated, setHydrated] = useState(false);
+  const [index, setIndex] = useState(0);
+  const [done, setDone] = useState(false);
+
+  useEffect(() => {
+    setAnswers(readPersisted(quiz.path));
+    if (canRedraw) setRound(roundOf(quiz.questions, size, Math.random));
+    setHydrated(true);
+  }, [quiz.path, quiz.questions, size, canRedraw]);
+
+  const current = round[index];
+  const chosen = current === undefined ? undefined : answers[current.hash];
+  const answered = chosen !== undefined;
+
+  const answeredCount = useMemo(
+    () => round.filter((q) => answers[q.hash] !== undefined).length,
+    [round, answers],
+  );
+  const correctCount = useMemo(
+    () => round.filter((q) => answers[q.hash] === q.answer).length,
+    [round, answers],
+  );
+
+  const choose = useCallback(
+    (option: number) => {
+      if (current === undefined || answers[current.hash] !== undefined) return;
+      const next = { ...answers, [current.hash]: option };
+      setAnswers(next);
+      writePersisted(quiz.path, next);
+    },
+    [answers, current, quiz.path],
+  );
+
+  const newRound = useCallback(() => {
+    setRound(roundOf(quiz.questions, size, Math.random));
+    setAnswers({});
+    writePersisted(quiz.path, {});
+    setIndex(0);
+    setDone(false);
+  }, [quiz.questions, size, quiz.path]);
+
+  const retry = useCallback(() => {
+    setAnswers({});
+    writePersisted(quiz.path, {});
+    setIndex(0);
+    setDone(false);
+  }, [quiz.path]);
+
+  if (current === undefined) return <></>;
+
+  if (done) {
+    return (
+      <section aria-label="Quiz results">
+        <StudyAidHeader title={quiz.title} description={quiz.description} />
+        <Card className="mx-auto max-w-2xl">
+          <CardContent className="flex flex-col items-center gap-6 py-12 text-center">
+            <p className="font-(family-name:--font-display) text-5xl font-semibold tabular-nums text-fd-foreground">
+              {correctCount}
+              <span className="text-fd-muted-foreground">/{round.length}</span>
+            </p>
+            <p className="max-w-sm text-sm text-fd-muted-foreground">
+              {/* No pass mark, deliberately: this checks understanding of a
+                  document, it does not certify anybody. */}
+              Answers are kept in this browser only.
+            </p>
+            <div className="flex flex-wrap justify-center gap-3">
+              <Button variant="outline" onClick={() => setIndex(0)}>
+                Review answers
+              </Button>
+              {canRedraw ? (
+                <Button onClick={newRound}>
+                  <RotateCcw aria-hidden className="size-4" />
+                  Another round
+                </Button>
+              ) : (
+                <Button onClick={retry}>
+                  <RotateCcw aria-hidden className="size-4" />
+                  Start again
+                </Button>
+              )}
+            </div>
+          </CardContent>
+        </Card>
+      </section>
+    );
+  }
+
+  return (
+    <section aria-label="Quiz">
+      <StudyAidHeader title={quiz.title} description={quiz.description} />
+
+      <div className="mx-auto max-w-2xl">
+        <div className="mb-4 flex items-baseline justify-between gap-4">
+          <p className="font-mono text-xs tracking-wide text-fd-muted-foreground uppercase">
+            Question {index + 1} / {round.length}
+            {canRedraw ? <span> · drawn from {banked}</span> : null}
+          </p>
+          <p className="font-mono text-xs tabular-nums text-fd-muted-foreground">
+            {answeredCount} answered
+          </p>
+        </div>
+        <Progress value={(answeredCount / round.length) * 100} className="mb-8 h-1" />
+
+        <Card>
+          <CardContent className="flex flex-col gap-6 py-8">
+            <h3 className="text-lg leading-snug font-medium text-balance text-fd-foreground">
+              {current.question}
+            </h3>
+
+            <ul className="flex flex-col gap-2">
+              {current.options.map((option, i) => {
+                const isAnswer = i === current.answer;
+                const isChoice = i === chosen;
+                // Three things have to be legible at once after a wrong
+                // answer, and they are three different facts: which option is
+                // RIGHT (green), which one is WRONG (red), and which one YOU
+                // picked (the accent ring). The accent alone cannot carry two
+                // of those, which is what it was doing — the correct option
+                // wore the same colour as a selection, so choosing wrongly
+                // looked like the page had answered for you.
+                //
+                // Colour is never the only channel: the check and cross icons
+                // and the verdict line below say the same thing in shape and
+                // in words.
+                //
+                // Plain CSS classes, not Tailwind arbitrary values: a
+                // `border-[color:var(--x)]` utility did not paint in a real
+                // build even with the rule in the stylesheet and the token
+                // resolving on the element. `app/global.css` is where this
+                // record's semantic colour already lives.
+                const tone = !answered
+                  ? "border-fd-border hover:border-fd-primary/60 hover:bg-fd-accent"
+                  : isAnswer
+                    ? "ksor-answer-correct"
+                    : isChoice
+                      ? "ksor-answer-wrong"
+                      : "border-fd-border opacity-60";
+                // Your own pick keeps the accent, whether it was right or
+                // wrong, so "what I chose" is never in doubt.
+                const mine = answered && isChoice ? " ksor-answer-mine" : "";
+                return (
+                  <li key={option}>
+                    <button
+                      type="button"
+                      disabled={answered}
+                      onClick={() => choose(i)}
+                      aria-pressed={isChoice}
+                      className={`flex w-full items-start gap-3 rounded-lg border px-4 py-3 text-left text-sm transition-colors motion-safe:duration-150 ${tone}${mine} ${answered ? "cursor-default" : "cursor-pointer"}`}
+                    >
+                      <span className="mt-px font-mono text-xs text-fd-muted-foreground">
+                        {letterOf(i)}
+                      </span>
+                      <span className="flex-1 text-fd-foreground">{option}</span>
+                      {answered && isAnswer ? (
+                        <Check
+                          aria-label="correct answer"
+                          className="ksor-answer-correct-text size-4 shrink-0"
+                        />
+                      ) : null}
+                      {answered && isChoice && !isAnswer ? (
+                        <X
+                          aria-label="your answer, which is wrong"
+                          className="ksor-answer-wrong-text size-4 shrink-0"
+                        />
+                      ) : null}
+                    </button>
+                  </li>
+                );
+              })}
+            </ul>
+
+            {answered ? (
+              <div
+                // Announced, because the whole value of the immediate-feedback
+                // model is this text, and a reader using a screen reader gets
+                // it only if the region says it changed.
+                role="status"
+                className="motion-safe:animate-in motion-safe:fade-in flex flex-col gap-3 border-t border-fd-border pt-5 text-sm"
+              >
+                <p className="font-mono text-xs tracking-wide uppercase">
+                  {chosen === current.answer ? (
+                    <span className="ksor-answer-correct-text">Correct</span>
+                  ) : (
+                    <span className="ksor-answer-wrong-text">
+                      Not quite — the answer is {letterOf(current.answer)}
+                    </span>
+                  )}
+                </p>
+                <p className="leading-relaxed text-fd-muted-foreground">{current.explanation}</p>
+                {current.source === undefined ? null : (
+                  // "In the document", never "Source": a citation in this
+                  // product carries a generation, and an attachment has no id
+                  // to pin — calling this a source would sell provenance that
+                  // is not here (spec §3).
+                  <p className="font-mono text-xs text-fd-muted-foreground">
+                    In the document: {current.source}
+                  </p>
+                )}
+              </div>
+            ) : null}
+          </CardContent>
+        </Card>
+
+        <div className="mt-6 flex items-center justify-between gap-4">
+          <Button
+            variant="ghost"
+            disabled={index === 0}
+            onClick={() => setIndex((i) => Math.max(0, i - 1))}
+          >
+            Back
+          </Button>
+          {index === round.length - 1 ? (
+            <Button disabled={!answered} onClick={() => setDone(true)}>
+              Finish
+            </Button>
+          ) : (
+            <Button disabled={!answered} onClick={() => setIndex((i) => i + 1)}>
+              Next
+            </Button>
+          )}
+        </div>
+
+        {/* Rendered only once the reader's own answers are in, so the server
+            HTML never claims a state this reader is not in. */}
+        {hydrated && answeredCount > 0 && !done ? (
+          <p className="mt-4 text-center font-mono text-xs text-fd-muted-foreground">
+            {correctCount} of {answeredCount} correct so far
+          </p>
+        ) : null}
+      </div>
+    </section>
+  );
+}

package/templates/scaffold/system/site/components/slides.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { ExternalLink, Presentation } from "lucide-react";
+import { useState, type ReactElement } from "react";
+
+import { DeckViewer } from "@/components/deck-viewer";
+import { Button } from "@/components/ui/button";
+import type { SlidesEntry } from "@/lib/attachments";
+
+/**
+ * The presentation that teaches this document.
+ *
+ * The predecessor embeds the deck directly — an always-on `<iframe>` to Google
+ * Slides, authored as raw JSX in the lesson's MDX. Two things stop that here,
+ * and the second one changed the design rather than just the authoring:
+ *
+ *  1. `knowledge/` is CommonMark (critical rule 2), so the frame cannot be
+ *     authored in the document. It is an attachment instead.
+ *
+ *  2. The scaffold's browser test asserts **zero external requests** on a
+ *     built page. An always-on frame breaks that on every page carrying a
+ *     deck — and the guarantee is worth keeping, because it is what makes the
+ *     site work offline, behind a firewall, and without telling a third party
+ *     which of your policies someone is reading.
+ *
+ * So the frame is CLICK-TO-LOAD. Nothing reaches the provider until a reader
+ * asks for it: the page ships a placeholder, and the `<iframe>` is created on
+ * click. The link out is always available and costs nothing, because a plain
+ * `<a>` is not a request.
+ *
+ * That is a real divergence from the predecessor and it is an improvement
+ * rather than a compromise — the reader who only wanted the policy never
+ * announces themselves to a slide host.
+ */
+export function Slides({ slides }: { slides: SlidesEntry }): ReactElement {
+  const [loaded, setLoaded] = useState(false);
+  const provider = slides.provider ?? slides.derivedProvider;
+
+  return (
+    <section aria-label="Teaching aid" className="not-prose mt-8 mb-12">
+      {/* A section heading, in the record's own language for one.
+
+          An earlier version dropped the accent bar and greyed the label, on
+          the theory that anything stronger would compete with the document
+          title directly above. That went too far: with no marker and no colour
+          the block read as loose text rather than as a section (owner, seen
+          live). The fix is the established marker at a smaller SIZE, not a
+          weaker one — the label carries the accent so it reads as a marker,
+          and the title sits one step below the document's. */}
+      <header className="mb-6">
+        <p className="font-mono text-xs font-medium tracking-[0.12em] text-fd-primary uppercase">
+          Teaching aid
+        </p>
+        <h2 className="mt-2 font-(family-name:--font-display) text-2xl font-semibold tracking-tight text-fd-foreground">
+          {slides.title}
+        </h2>
+        {/* The record's own marker for "a new region starts here": a short
+            accent bar riding a full-width hairline. Every study-aid header
+            uses it, so a reader has met it before. */}
+        <div className="mt-3 h-px w-full bg-fd-border">
+          <div className="h-[3px] w-24 -translate-y-px bg-fd-primary" />
+        </div>
+        {slides.description === undefined ? null : (
+          <p className="mt-4 text-sm text-fd-muted-foreground">{slides.description}</p>
+        )}
+      </header>
+
+      <div className="flex flex-col gap-4">
+        {/* A deck the record owns needs no link and no permission: it IS the
+            presentation. The linked mode below is for an adopter who already
+            has one somewhere else. */}
+        {slides.deck !== undefined && slides.deck.length > 0 ? (
+          <DeckViewer slides={slides.deck} title={slides.title} />
+        ) : null}
+
+        {slides.url === undefined ? null : (
+          <p className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm">
+            <a
+              href={slides.url}
+              target="_blank"
+              rel="noreferrer"
+              className="inline-flex items-center gap-1.5 text-fd-primary underline underline-offset-4 transition-colors hover:text-fd-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
+            >
+              Open the full presentation
+              <ExternalLink aria-hidden className="size-3.5" />
+            </a>
+            {provider === undefined ? null : (
+              <span className="font-mono text-xs text-fd-muted-foreground">{provider}</span>
+            )}
+          </p>
+        )}
+
+        {slides.embed === undefined ? null : (
+          <div
+            // 16:9, the aspect every deck host serves. A ratio box rather than
+            // a fixed height, so the frame scales with the measure instead of
+            // letterboxing on a narrow window.
+            className="relative w-full overflow-hidden rounded-lg border border-fd-border bg-fd-muted"
+            style={{ paddingBottom: "56.25%" }}
+          >
+            {loaded ? (
+              <iframe
+                src={slides.embed}
+                title={slides.title}
+                allowFullScreen
+                // No referrer: the provider learns that a deck was opened, not
+                // which document of this record it was opened from.
+                referrerPolicy="no-referrer"
+                loading="lazy"
+                className="absolute inset-0 size-full"
+              />
+            ) : (
+              <div className="absolute inset-0 flex flex-col items-center justify-center gap-4 px-6 text-center">
+                <Presentation aria-hidden className="size-8 text-fd-muted-foreground" />
+                <Button onClick={() => setLoaded(true)}>Load the slides</Button>
+                <p className="max-w-sm text-xs text-fd-muted-foreground">
+                  {/* Said plainly, because it is the reason for the click. */}
+                  The deck is hosted{provider === undefined ? " elsewhere" : ` on ${provider}`}.
+                  Nothing is requested from there until you load it.
+                </p>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}

package/templates/scaffold/system/site/components/study-aids.tsx

@@ -4,7 +4,7 @@ import type { ReactElement, ReactNode } from "react";
  * The end-of-document region: what a reader DOES with a document once they
  * have read it.
  *
- * The deck lives here, and the quiz will sit beside it. Deliberately not a tab:
+ * The deck and the quiz live here, in that order. Deliberately not a tab:
  * a study aid is used AFTER the document, and a tab would hide the document
  * while you used it. Deliberately one region rather than each aid finding its
  * own spot on the page, so a second aid is a child here and not a new layout