devcoach 2.7.0-next.600.g5b3bf2c → 2.7.0-next.604.g26d3007

package/assets/references/course.md

@@ -86,9 +86,10 @@ under 900 px the menu becomes a strip above the content. Routing by `location.ha
 (`#step-N`, no hash → step 1): on `hashchange` show that section, scroll to the top. Every
 section ends with *← Previous · Next →* buttons and the line *"Stuck? Ask in the chat — that's
 where the course is being taught."* Mark `:root[data-embedded] nav.steps { display: none }`:
-the dashboard injects `data-embedded`, has its own step list, makes the canvas transparent and
-lifts the `max-width` of `.course`, `section` and `header.intro` to use the width it has — so
-keep those class names.
+the dashboard injects `data-embedded`, has its own step list, makes the canvas transparent,
+lifts the `max-width` of `.course`, `section` and `header.intro` to use the width it has, and
+sets `data-theme` from its own light/dark toggle — so keep those class names and the
+`data-theme` selectors.
 
 **Each section**, in order: **Goal** (one line) → **The idea** (short, one concept, an analogy
 where it helps) → **Worked example** → **Try it** (see the ladder below) → **Check yourself**
@@ -109,35 +110,56 @@ translated into JS just to make it runnable:
    output** (typed or picked, then Reveal), **fill the blank**, or **spot the bug** (3–4
    candidates). No button may pretend to execute Java, Rust or Go.
 
-**Design.** One measure (~68ch), generous spacing, quiet Tufte-like typography; light + dark
-using the dashboard's palette (greys, indigo `#4f46e5` accents, rose for warnings). It must
-also pass as a Claude artifact page: `<title>` is a 2–4 word name (the long title is the
-`<h1>`), colour tokens live on `:root`, dark tokens are set under
-`@media (prefers-color-scheme: dark)` guarded by `:root:not([data-theme="light"])` and again
-under `:root[data-theme="dark"]`, `body` has an explicit background, 16 px side gutters at
-phone width, no horizontal page scroll.
-
-Skeleton (adapt, keep the ids and the class names):
+**Design — conform to the dashboard, do not copy it.** One measure (~68ch), generous spacing,
+quiet Tufte-like typography, light + dark. Every colour is a **token** on `:root`; nothing is
+hard-coded further down (no stray `#fff` on a button, no grey typed by hand in a rule):
+
+- **Neutrals are the dashboard's** — `--bg --panel --text --muted --line --code-bg`, with the
+  values of the skeleton. They are what makes an embedded course sit on the dashboard's canvas
+  without a seam (embedded, the viewer sets these six itself, so keep the names).
+- **The accent is yours** — the brand teal of the skeleton by default, or ONE accent that suits
+  the subject (Rust's orange, Swift's orange-red, a database blue…), as long as `--accent` reads
+  at 4.5:1 or better on `--panel` in both modes and `--on-accent` reads on `--accent`.
+- `--ok` / `--warn` keep their meaning (right / wrong, safe / dangerous). Colours inside a
+  diagram or an illustration are free.
+
+It must also pass as a Claude artifact page: `<title>` is a 2–4 word name (the long title is
+the `<h1>`), dark tokens are set under `@media (prefers-color-scheme: dark)` guarded by
+`:root:not([data-theme="light"])` and again under `:root[data-theme="dark"]`, `body` has an
+explicit background, 16 px side gutters at phone width, no horizontal page scroll.
+
+**Theme switch.** Opened on its own (the file, the artifact) the document follows the OS until
+the reader uses its switch: a `<button class="theme-switch">` in the step menu that sets
+`data-theme` on the root to `dark` or `light`, shows the **current** scheme, carries an
+`aria-label` saying what a click does, and remembers the choice with `localStorage` inside
+`try/catch` (storage is unavailable in a sandboxed open — the switch must still work for the
+visit). Embedded in the dashboard the switch is hidden and the stored choice is NOT applied:
+the dashboard's own toggle drives `data-theme` there.
+
+Skeleton (adapt, keep the ids, the class names and the token names):
 
 ```html
 <!doctype html><html lang="en"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Node error events</title>
 <style>
-  :root { --bg:#f8fafc; --panel:#fff; --text:#0f172a; --muted:#64748b; --line:#e2e8f0; --accent:#4f46e5; --accent-soft:#eef2ff; --warn:#e11d48; }
-  @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --bg:#0b1220; --panel:#111a2e; --text:#e2e8f0; --muted:#94a3b8; --line:#1e293b; --accent:#818cf8; --accent-soft:#1e1b4b; --warn:#fb7185; } }
-  :root[data-theme="dark"] { --bg:#0b1220; --panel:#111a2e; --text:#e2e8f0; --muted:#94a3b8; --line:#1e293b; --accent:#818cf8; --accent-soft:#1e1b4b; --warn:#fb7185; }
+  :root { --bg:#f9fafb; --panel:#ffffff; --text:#111827; --muted:#6b7280; --line:#e5e7eb; --code-bg:#f3f4f6; --accent:#0f766e; --accent-soft:#f0fdfa; --on-accent:#ffffff; --ok:#047857; --ok-soft:#d1fae5; --warn:#be123c; --warn-soft:#ffe4e6; --log-bg:#1e1f22; --log-text:#dfe1e5; }
+  @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --bg:#1e1f22; --panel:#2b2d30; --text:#dfe1e5; --muted:#9da0a8; --line:#43454a; --code-bg:#1e1f22; --accent:#5eead4; --accent-soft:#134e4a; --on-accent:#0b2b28; --ok:#5fad65; --ok-soft:#1f3a24; --warn:#f97583; --warn-soft:#4a1f26; --log-bg:#18191b; --log-text:#dfe1e5; } }
+  :root[data-theme="dark"] { --bg:#1e1f22; --panel:#2b2d30; --text:#dfe1e5; --muted:#9da0a8; --line:#43454a; --code-bg:#1e1f22; --accent:#5eead4; --accent-soft:#134e4a; --on-accent:#0b2b28; --ok:#5fad65; --ok-soft:#1f3a24; --warn:#f97583; --warn-soft:#4a1f26; --log-bg:#18191b; --log-text:#dfe1e5; }
   body { margin:0; background:var(--bg); color:var(--text); font:16px/1.6 system-ui, sans-serif; }
   .course { display:grid; grid-template-columns:16rem minmax(0,1fr); gap:24px; max-width:1100px; margin:0 auto; padding:24px 16px; }
   nav.steps { position:sticky; top:16px; align-self:start; } nav.steps a { display:block; padding:6px 10px; border-radius:8px; color:var(--muted); text-decoration:none; }
   nav.steps a.current { background:var(--accent-soft); color:var(--accent); }
-  :root[data-embedded] nav.steps { display:none } :root[data-embedded] .course { grid-template-columns:minmax(0,1fr); }
-  section { display:none; max-width:68ch; } section.current { display:block; }
+  .theme-switch { margin-top:12px; background:transparent; color:var(--muted); border:1px solid var(--line); border-radius:8px; padding:4px 10px; cursor:pointer; }
+  :root[data-embedded] nav.steps, :root[data-embedded] .theme-switch { display:none } :root[data-embedded] .course { grid-template-columns:minmax(0,1fr); }
+  section { display:none; max-width:68ch; background:var(--panel); border:1px solid var(--line); border-radius:12px; padding:22px 24px; } section.current { display:block; }
+  button.primary { background:var(--accent); color:var(--on-accent); border:1px solid var(--accent); }
   @media (max-width: 900px) { .course { grid-template-columns:minmax(0,1fr); } nav.steps { position:static; display:flex; flex-wrap:wrap; gap:4px; } }
-  /* .goal, .try, .check, .pager, buttons … */
+  /* .goal, .try, .check, .pager … — tokens only */
 </style></head><body>
 <div class="course">
-  <nav class="steps"><a href="#step-1">1 · Sums</a><a href="#step-2">2 · Powers</a></nav>
+  <nav class="steps"><a href="#step-1">1 · Sums</a><a href="#step-2">2 · Powers</a>
+    <button class="theme-switch" type="button"></button></nav>
   <main>
     <section id="step-1"><h2>1 · Sums</h2><p class="goal">…</p> … <div class="check">…<button>Reveal</button></div>
       <div class="pager"><a href="#step-1">← Previous</a><a href="#step-2">Next →</a></div>
@@ -148,17 +170,55 @@ Skeleton (adapt, keep the ids and the class names):
 <script>
   // show one section: on load + hashchange, toggle .current on the section and its nav link, scrollTo(0,0)
   // reveal buttons; the live examples (new Function inside try/catch) or the simulations
+  // theme switch — standalone only; embedded, the dashboard sets data-theme:
+  (function () {
+    var root = document.documentElement, btn = document.querySelector(".theme-switch"), KEY = "course-theme";
+    var isDark = function () {
+      var t = root.getAttribute("data-theme");
+      return t ? t === "dark" : matchMedia("(prefers-color-scheme: dark)").matches;
+    };
+    var paint = function () {
+      btn.textContent = isDark() ? "🌙 Dark" : "☀️ Light";
+      btn.setAttribute("aria-label", isDark() ? "Dark theme — switch to light" : "Light theme — switch to dark");
+    };
+    if (window.parent === window) {
+      try { var saved = localStorage.getItem(KEY); if (saved === "dark" || saved === "light") root.setAttribute("data-theme", saved); } catch (e) {}
+    }
+    btn.addEventListener("click", function () {
+      var next = isDark() ? "light" : "dark";
+      root.setAttribute("data-theme", next);
+      try { localStorage.setItem(KEY, next); } catch (e) {}
+      paint();
+    });
+    matchMedia("(prefers-color-scheme: dark)").addEventListener("change", paint);
+    paint();
+  })();
 </script></body></html>
 ```
 
-### 4b. Share as an artifact — an offer, nothing more
+### 4b. Share as an artifact — an offer, with the disclosure
+
+Publishing is the one moment course content **leaves the machine**: the Artifact tool uploads
+a copy of the document to claude.ai, under the user's account. The offer must say so — a
+"private" link describes who can open it, not where the file lives.
 
 After the last `add_course_step`, **if the Artifact tool is available**, offer ONCE, as a
-choice: *"Publish this course as a Claude artifact too? (private until you share the
-link)"* — **Yes** → publish `document_path` as it is (`icon: "course"`, `description` = the
-goal) and reply with the link in one line; **No**, or no Artifact tool → nothing. The local
-file stays the course; the artifact is a copy for sharing, and the user can ask for it again
-any time ("publish the course as an artifact"). Never store the link anywhere.
+choice, in these terms:
+
+> *Publish this course as a Claude artifact too? That **uploads a copy to claude.ai** — it
+> leaves this machine. Only you can open it until you share the link.*
+
+- A course usually carries the user's own work (examples come from `seed_context`: project and
+  repository names, file paths, snippets, the bug that started it). When this one does, name
+  what it contains **in the same question** — *"It mentions lolcoach and the hang you
+  debugged."* — so the yes is an informed one. Never publish without that yes.
+- **Yes** → publish `document_path` as it is (`icon: "course"`, `description` = the goal) and
+  reply with the link in one line. **No**, or no Artifact tool → nothing, and do not ask again.
+- The local file stays the course; the artifact is a copy for sharing. The user can ask for it
+  any time ("publish the course as an artifact") — the same disclosure applies each time, and
+  to every republish after an edit. devcoach stores nothing about the artifact, so it cannot
+  delete it either: if asked to take it down, use the Artifact tool or point the user to their
+  artifacts on claude.ai.
 
 ## 5. Teach — one step per message
 

package/assets/static/course-frame.js

@@ -1,8 +1,10 @@
 // Injected by the dashboard at the end of every course document it serves (never part of the
 // file on disk). Inside the sandboxed frame the parent cannot measure the document, so the
 // document reports its own height and the step it is showing; the parent grows the frame to fit
-// (the page scrolls, never the frame) and moves its step highlight. Standalone opens (a pasted
-// URL, the artifact copy) never run this: `parent === window` exits at once.
+// (the page scrolls, never the frame) and moves its step highlight. The dashboard in turn tells
+// the document which theme it is in: framed, the document only sees the OS preference, not the
+// dashboard's toggle. Standalone opens (a pasted URL, the artifact copy) never run this:
+// `parent === window` exits at once, and the document's own theme switch is in charge.
 (function () {
   if (window.parent === window) return;
   var root = document.documentElement;
@@ -10,12 +12,19 @@
   // Embedded, the page canvas is the dashboard's: let it show through (sections keep their own
   // panel colours), so the frame reads as part of the page instead of a box inside it.
   root.style.background = "transparent";
-  // …and use the width the dashboard gives it: the reading-column caps of the contract's
-  // `.course` / `section` / `header.intro` are for the standalone page.
+  // …use the width the dashboard gives it (the reading-column caps of the contract's `.course` /
+  // `section` / `header.intro` are for the standalone page), and take the NEUTRALS from the
+  // dashboard palette so panels and text sit on its canvas without a seam. Accent and semantic
+  // tokens stay the document's own: a course conforms to the palette, it does not copy it.
   var style = document.createElement("style");
   style.textContent =
     ":root[data-embedded] .course{max-width:none;padding:4px 0 32px}" +
-    ":root[data-embedded] section,:root[data-embedded] header.intro{max-width:none}";
+    ":root[data-embedded] section,:root[data-embedded] header.intro{max-width:none}" +
+    ":root[data-embedded] .theme-switch{display:none}" +
+    ':root[data-embedded][data-theme="light"]{--bg:#f9fafb;--panel:#ffffff;--text:#111827;' +
+    "--muted:#6b7280;--line:#e5e7eb;--code-bg:#f3f4f6}" +
+    ':root[data-embedded][data-theme="dark"]{--bg:#1e1f22;--panel:#2b2d30;--text:#dfe1e5;' +
+    "--muted:#9da0a8;--line:#43454a;--code-bg:#1e1f22}";
   (document.head || root).appendChild(style);
   function clearBody() { document.body.style.background = "transparent"; }
   if (document.body) clearBody(); else document.addEventListener("DOMContentLoaded", clearBody);
@@ -27,6 +36,15 @@
       "*",
     );
   }
+  // The dashboard answers every report with its theme (the first report is the handshake).
+  window.addEventListener("message", function (event) {
+    var data = event.data;
+    if (event.source !== window.parent || !data || data.type !== "devcoach:theme") return;
+    if (data.theme !== "dark" && data.theme !== "light") return;
+    if (root.getAttribute("data-theme") === data.theme) return;
+    root.setAttribute("data-theme", data.theme);
+    report();
+  });
   window.addEventListener("load", report);
   window.addEventListener("hashchange", report);
   if (typeof ResizeObserver === "function") new ResizeObserver(report).observe(root);

package/assets/static/course-viewer.js

@@ -1,12 +1,13 @@
 // Course page: the sandboxed frame reports its height and current step (course-frame.js, injected
 // by the server); this side sizes the frame to the document so the page scrolls, keeps the step
 // list in sync, and turns step clicks into in-frame navigation (a fragment navigation of the
-// cross-origin frame) instead of a page reload.
+// cross-origin frame) instead of a page reload. It also tells the frame which theme the
+// dashboard is in: the framed document cannot see the toggle, only the OS preference.
 (function () {
   var frame = document.getElementById("course-frame");
   var list = document.getElementById("course-steps");
   if (!frame || !list) return;
-  var CURRENT = ["bg-indigo-50", "dark:bg-indigo-900/30"];
+  var CURRENT = ["bg-accent-50", "dark:bg-accent-900/30"];
   var shown = null;
 
   function select(anchor) {
@@ -22,6 +23,15 @@
     });
   }
 
+  // The frame's origin is opaque (sandbox without allow-same-origin): "*" is the only target
+  // that reaches it, and the payload is one word.
+  function sendTheme() {
+    if (!frame.contentWindow) return;
+    var dark = document.documentElement.classList.contains("dark");
+    frame.contentWindow.postMessage({ type: "devcoach:theme", theme: dark ? "dark" : "light" }, "*");
+  }
+  document.addEventListener("dc:theme", sendTheme);
+
   function scrollToFrame() {
     var top = frame.getBoundingClientRect().top + window.scrollY - 16;
     window.scrollTo({ top: Math.max(0, top), behavior: "smooth" });
@@ -35,6 +45,9 @@
       frame.style.height = Math.min(50000, Math.max(320, Math.ceil(height))) + "px";
     }
     if (typeof data.anchor === "string") select(data.anchor);
+    // Every report is answered with the theme: the first one is the handshake, so the message
+    // can never arrive before the frame listens.
+    sendTheme();
   });
 
   list.addEventListener("click", function (event) {

package/assets/static/style.css

@@ -1,5 +1,56 @@
 /* devcoach — style overrides with light/dark theme support */
 
+/* ── Palette tokens ─────────────────────────────────────────────────────────
+   The one place colours are decided. Values are space-separated RGB triplets so Tailwind can
+   apply its opacity modifiers: layout() in src/web/views.ts points Tailwind's `gray` and
+   `accent` scales at these variables (`rgb(var(--dc-gray-900) / <alpha-value>)`), which is how
+   every `dark:bg-gray-900` in the views picks the palette up without being rewritten.
+   - Light neutrals: Tailwind's own gray.
+   - Dark neutrals: an IDE ramp (JetBrains New UI dark) — page → panel → raised → border.
+   - Accent: the brand teal of the wordmark and the docs site, one step darker from 500 up so
+     white text on accent-600 and accent-600 text on white both clear 4.5:1.
+   tests/theme.test.ts holds the contrast floor for the pairs the UI relies on. */
+
+:root {
+  --dc-gray-50: 249 250 251;
+  --dc-gray-100: 243 244 246;
+  --dc-gray-200: 229 231 235;
+  --dc-gray-300: 209 213 219;
+  --dc-gray-400: 156 163 175;
+  --dc-gray-500: 107 114 128;
+  --dc-gray-600: 75 85 99;
+  --dc-gray-700: 55 65 81;
+  --dc-gray-800: 31 41 55;
+  --dc-gray-900: 17 24 39;
+  --dc-gray-950: 3 7 18;
+
+  --dc-accent-50: 240 253 250;
+  --dc-accent-100: 204 251 241;
+  --dc-accent-200: 153 246 228;
+  --dc-accent-300: 94 234 212;
+  --dc-accent-400: 45 212 191;
+  --dc-accent-500: 13 148 136;
+  --dc-accent-600: 15 118 110;
+  --dc-accent-700: 17 94 89;
+  --dc-accent-800: 19 78 74;
+  --dc-accent-900: 15 61 58;
+  --dc-accent-950: 4 47 46;
+}
+
+.dark {
+  --dc-gray-50: 245 246 247;
+  --dc-gray-100: 236 238 241;
+  --dc-gray-200: 223 225 229;   /* text */
+  --dc-gray-300: 188 190 196;
+  --dc-gray-400: 157 160 168;   /* muted text */
+  --dc-gray-500: 144 150 160;   /* secondary text */
+  --dc-gray-600: 111 115 122;   /* disabled, faint */
+  --dc-gray-700: 67 69 74;      /* borders */
+  --dc-gray-800: 57 59 64;      /* raised: inputs, hover rows */
+  --dc-gray-900: 43 45 48;      /* panels, nav, cards */
+  --dc-gray-950: 30 31 34;      /* page canvas */
+}
+
 /* ── Theme variables ────────────────────────────────────────────────────── */
 
 :root {
@@ -17,10 +68,10 @@
   --md-pre-bg: #f8fafc;
   --md-pre-border: #e2e8f0;
   --md-blockquote-color: #6b7280;
-  --md-blockquote-border: #6366f1;
+  --md-blockquote-border: rgb(var(--dc-accent-500));
   --md-hr: #e5e7eb;
-  --md-link: #4f46e5;
-  --md-link-hover: #6366f1;
+  --md-link: rgb(var(--dc-accent-600));
+  --md-link-hover: rgb(var(--dc-accent-500));
   --md-table-th-bg: #f9fafb;
   --md-table-th-color: #374151;
   --md-table-border: #e5e7eb;
@@ -34,36 +85,40 @@
 }
 
 .dark {
-  --scrollbar-track: #111827;
-  --scrollbar-thumb: #374151;
-  --scrollbar-thumb-hover: #4b5563;
-
-  --md-text: #e5e7eb;
-  --md-heading: #f9fafb;
-  --md-heading-h3: #d1d5db;
-  --md-h2-border: #374151;
-  --md-code-bg: #1f2937;
+  --scrollbar-track: rgb(var(--dc-gray-950));
+  --scrollbar-thumb: rgb(var(--dc-gray-700));
+  --scrollbar-thumb-hover: rgb(var(--dc-gray-600));
+
+  --md-text: rgb(var(--dc-gray-200));
+  --md-heading: rgb(var(--dc-gray-100));
+  --md-heading-h3: rgb(var(--dc-gray-300));
+  --md-h2-border: rgb(var(--dc-gray-700));
+  --md-code-bg: rgb(var(--dc-gray-800));
   --md-code-color: #f472b6;
-  --md-code-border: #374151;
-  --md-pre-bg: #282c34;
-  --md-pre-border: #374151;
-  --md-blockquote-color: #9ca3af;
-  --md-blockquote-border: #6366f1;
-  --md-hr: #374151;
-  --md-link: #818cf8;
-  --md-link-hover: #a5b4fc;
-  --md-table-th-bg: #1f2937;
-  --md-table-th-color: #d1d5db;
-  --md-table-border: #374151;
-  --md-table-td-color: #e5e7eb;
-  --md-table-even-bg: #111827;
-  --md-strong: #f3f4f6;
+  --md-code-border: rgb(var(--dc-gray-700));
+  --md-pre-bg: rgb(var(--dc-gray-950));
+  --md-pre-border: rgb(var(--dc-gray-700));
+  --md-blockquote-color: rgb(var(--dc-gray-400));
+  --md-blockquote-border: rgb(var(--dc-accent-400));
+  --md-hr: rgb(var(--dc-gray-700));
+  --md-link: rgb(var(--dc-accent-300));
+  --md-link-hover: rgb(var(--dc-accent-200));
+  --md-table-th-bg: rgb(var(--dc-gray-800));
+  --md-table-th-color: rgb(var(--dc-gray-300));
+  --md-table-border: rgb(var(--dc-gray-700));
+  --md-table-td-color: rgb(var(--dc-gray-200));
+  --md-table-even-bg: rgb(var(--dc-gray-800) / 0.4);
+  --md-strong: rgb(var(--dc-gray-100));
   --md-em: #c4b5fd;
 
-  --check-border: #4b5563;
-  --check-bg: #111827;
+  --check-border: rgb(var(--dc-gray-600));
+  --check-bg: rgb(var(--dc-gray-900));
 }
 
+/* Code blocks: keep the highlighter's token colours, sit them on the editor background. */
+.dark .markdown-body pre code.hljs,
+.dark .hljs { background: var(--md-pre-bg); }
+
 /* ── Scrollbar ──────────────────────────────────────────────────────────── */
 
 ::-webkit-scrollbar { width: 6px; height: 6px; }
@@ -184,15 +239,15 @@
   transition: background-color 0.12s, border-color 0.12s;
 }
 .dc-check:checked {
-  background-color: #4f46e5;
-  border-color: #4f46e5;
+  background-color: rgb(var(--dc-accent-600));
+  border-color: rgb(var(--dc-accent-600));
   background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20' fill='none' stroke='white' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 10.5l3.5 3.5L15 7'/%3E%3C/svg%3E");
   background-size: 72%;
   background-position: center;
   background-repeat: no-repeat;
 }
 .dc-check:focus-visible {
-  outline: 2px solid #6366f1;
+  outline: 2px solid rgb(var(--dc-accent-500));
   outline-offset: 2px;
 }
 
@@ -220,7 +275,7 @@
 }
 .dc-resize-handle:hover::after,
 .dc-resizing .dc-resize-handle:active::after {
-  background-color: rgba(99, 102, 241, 0.85);
+  background-color: rgb(var(--dc-accent-500) / 0.85);
 }
 .dc-resizing {
   user-select: none;