fix(jspsych): capture document stylesheets so replay preserves CSS

Previously the recorder only serialized the display element subtree, so
replays reconstructed DOM structure but rendered unstyled — class hooks
like .jspsych-display-element had no rules to attach to.

Snapshot document.styleSheets at session start. For each <style> tag we
record the resolved cssRules text (falling back to textContent); for each
<link rel=stylesheet> we record the href and, when accessible, the
resolved CSS so cross-origin sheets degrade to href-only rather than
breaking. Also covers @import-only sheets that have no DOM owner.

Author: claude

docs/reference/session-recording-schema.md

@@ -12,7 +12,8 @@ A replayer treats this recording as observational. It does not re-execute trial
 
 1. The DOM snapshot captured at each trial's `on_load` (`trial.initial_dom`).
 2. The chronological mutation and input event log scoped to that trial (`trial.events`).
-3. Session-level metadata for context (viewport, scroll, RNG outputs, focus/blur, fullscreen).
+3. The session-level stylesheet snapshot (`stylesheets`) so the reconstructed DOM is styled identically to the original.
+4. Session-level metadata for context (viewport, scroll, RNG outputs, focus/blur, fullscreen).
 
 Each trial is a self-contained replay unit because jsPsych wipes the display element between trials.
 
@@ -28,6 +29,7 @@ interface SessionRecording {
   viewport: ViewportState;
   rng: { seed: string | null; math_random_patched: boolean };
   display_element_id: string;
+  stylesheets: StylesheetSnapshot[];
   trials: TrialRecording[];
   viewport_changes: ViewportChange[];
   rng_calls: RngCall[];
@@ -47,6 +49,7 @@ interface SessionRecording {
 | `rng.seed` | The seed installed via `jsPsych.randomization.setSeed` for the session, or `null` if `Math.random` was already non-native at recording start. |
 | `rng.math_random_patched` | `true` while recording is active; `Math.random` is wrapped to log every call into `rng_calls`. |
 | `display_element_id` | The `id` attribute of the display element (`#jspsych-content` by default). |
+| `stylesheets` | Snapshot of every stylesheet attached to the document at session start. See [Stylesheets](#stylesheets). |
 | `trials` | Per-trial recordings, in chronological order. See [`TrialRecording`](#trialrecording). |
 | `viewport_changes` | Session-level log of viewport changes (window resize, page zoom, pinch zoom, pinch pan). |
 | `rng_calls` | Chronological log of every `Math.random` output. Includes calls outside trial boundaries (parameter eval, ITI, `on_finish`). |
@@ -120,7 +123,32 @@ Every node in `initial_dom` is assigned a monotonically-increasing integer `id`.
 - Canvas/WebGL pixel content. Only the element and its dimensions are recorded.
 - Audio/video media data. Only playback events (`media.play`, `media.pause`, etc.) and the source URL are recorded.
 - Shadow DOM. jsPsych does not use it in core; recordings will not capture mutations inside shadow roots.
-- Styles applied via `<link rel="stylesheet">` referencing external sheets. The link element itself is recorded; the resolved CSS is not. Replayers generally need to load the same stylesheets out-of-band.
+- Stylesheet additions, removals, or rule mutations that occur after `start()`. The session-level [stylesheets](#stylesheets) snapshot is taken once at session start; it is not updated when later trials inject `<style>` tags or modify rules at runtime.
+
+## Stylesheets
+
+```ts
+type StylesheetSnapshot =
+  | { kind: "inline"; css: string;        media: string | null }
+  | { kind: "link";   href: string; css: string | null; media: string | null };
+```
+
+`stylesheets` is the snapshot of every entry in `document.styleSheets` at session start. It exists so a replayer can re-apply the same CSS to the reconstructed DOM — `initial_dom` carries class hooks like `.jspsych-display-element`, and without the matching rules the replay would render unstyled.
+
+| Field | Description |
+| ----- | ----------- |
+| `kind` | `"inline"` for `<style>` tags; `"link"` for `<link rel="stylesheet">`. |
+| `css` | Resolved rule text (joined `cssRules.cssText`). `null` for `<link>` sheets when `cssRules` access throws (cross-origin sheets without CORS headers). |
+| `href` | The link's resolved URL. Replayers can refetch the source from this URL when `css` is `null`. |
+| `media` | The sheet's `media` attribute, or `null` if unset. |
+
+**Replay guidance.** For each entry, inject a `<style>` element with the captured `css` text into the replayer's document head. When `css` is `null` for a `link` entry, fetch the stylesheet from `href` (or substitute a known-good copy of the same asset) and inject the result. Apply the `media` attribute on the injected element so media-conditional rules behave correctly.
+
+**Limitations.**
+
+- Snapshot is taken once at `start()`. Later mutations to the document's stylesheets — additions, removals, or `CSSOM` rule edits — are not tracked.
+- `@import` rules within a captured stylesheet are recorded as text. The imported sheet itself is not inlined; if the replayer's environment cannot resolve the import URL, those rules will not apply.
+- Pseudo-classes (`:hover`, `:focus`) and media queries are recorded as part of the rule text but only take effect during replay if the replayer reproduces the corresponding state or viewport.
 
 ## Event types
 

packages/jspsych/src/modules/recording.ts

@@ -21,6 +21,7 @@ export interface SessionRecording {
   viewport: ViewportState;
   rng: { seed: string | null; math_random_patched: boolean };
   display_element_id: string;
+  stylesheets: StylesheetSnapshot[];
   trials: TrialRecording[];
   viewport_changes: ViewportChange[];
   // Chronological log of every Math.random output consumed during the
@@ -33,6 +34,15 @@ export interface SessionRecording {
   end_reason: "finished" | "aborted" | "unload" | null;
 }
 
+// A snapshot of one stylesheet attached to the document at session start.
+// `inline` covers `<style>` tags; `link` covers `<link rel="stylesheet">`.
+// `css` is the resolved rule text where readable. Cross-origin sheets throw
+// SecurityError on `cssRules` access; for those we record `href` only and
+// leave `css` null so a replayer can fetch the source out-of-band.
+export type StylesheetSnapshot =
+  | { kind: "inline"; css: string; media: string | null }
+  | { kind: "link"; href: string; css: string | null; media: string | null };
+
 export interface ViewportState {
   w: number;
   h: number;
@@ -228,6 +238,7 @@ export class SessionRecorder {
       viewport: { w: 0, h: 0, dpr: 1, scale: 1, offset_x: 0, offset_y: 0 },
       rng: { seed: null, math_random_patched: false },
       display_element_id: "",
+      stylesheets: [],
       trials: [],
       viewport_changes: [],
       rng_calls: [],
@@ -258,6 +269,7 @@ export class SessionRecorder {
     this.recording.display_element_id = displayElement.id || "";
     this.recording.viewport = readViewport();
     this.lastViewport = { ...this.recording.viewport };
+    this.recording.stylesheets = this.captureStylesheets();
 
     // Reset per-session ephemeral state so a reused recorder doesn't carry
     // stale node ids, throttle flags, or pending event buffers.
@@ -541,6 +553,70 @@ export class SessionRecorder {
     return null;
   }
 
+  // -------- stylesheet snapshot --------
+
+  // Captured at session start so a replayer can apply the same CSS to the
+  // recorded DOM. Without this, `initial_dom` reconstructs structure but
+  // not appearance — class hooks like `.jspsych-display-element` have no
+  // rules to attach to.
+  //
+  // We walk the DOM directly (rather than just `document.styleSheets`) so
+  // that <link rel="stylesheet"> tags whose sheet has not yet loaded — or
+  // failed to load — are still captured by href. For each element we then
+  // try to read the resolved rule text via the associated CSSStyleSheet:
+  //   - <style> tags: read `cssRules` (always readable for same-document
+  //     inline sheets); fall back to the element's `textContent` if rule
+  //     access throws.
+  //   - <link rel="stylesheet">: read `cssRules` if the sheet is loaded
+  //     and same-origin (or CORS-permissive). Otherwise record `href`
+  //     with `css: null` so a replayer can refetch out-of-band.
+  // Stylesheets added or mutated after `start()` are not tracked; the
+  // session-level snapshot is taken once at start.
+  private captureStylesheets(): StylesheetSnapshot[] {
+    if (typeof document === "undefined") return [];
+    const out: StylesheetSnapshot[] = [];
+    const seen = new Set<Node>();
+
+    const elements = document.querySelectorAll<HTMLElement>('style, link[rel~="stylesheet"]');
+    for (const el of Array.from(elements)) {
+      try {
+        seen.add(el);
+        const sheet = (el as unknown as { sheet?: CSSStyleSheet | null }).sheet ?? null;
+        const media = readMedia(el, sheet);
+        if (el instanceof HTMLLinkElement) {
+          const href = el.href || el.getAttribute("href") || "";
+          out.push({ kind: "link", href, css: sheet ? readSheetText(sheet) : null, media });
+        } else if (el instanceof HTMLStyleElement) {
+          const css = (sheet ? readSheetText(sheet) : null) ?? el.textContent ?? "";
+          out.push({ kind: "inline", css, media });
+        }
+      } catch {
+        // Capture must never break the experiment.
+      }
+    }
+
+    // Also include any sheets that weren't reached via the DOM walk —
+    // notably sheets pulled in via @import, which exist in
+    // `document.styleSheets` but have no `ownerNode` element.
+    for (const sheet of Array.from(document.styleSheets)) {
+      try {
+        const owner = sheet.ownerNode as Node | null;
+        if (owner && seen.has(owner)) continue;
+        const css = readSheetText(sheet);
+        const media = sheet.media && sheet.media.mediaText ? sheet.media.mediaText : null;
+        if (sheet.href) {
+          out.push({ kind: "link", href: sheet.href, css, media });
+        } else if (css !== null) {
+          out.push({ kind: "inline", css, media });
+        }
+      } catch {
+        // Capture must never break the experiment.
+      }
+    }
+
+    return out;
+  }
+
   private assignId(node: Node): number {
     let id = this.nodeIds.get(node);
     if (id === undefined) {
@@ -812,6 +888,33 @@ export class SessionRecorder {
 // Helpers
 // ---------------------------------------------------------------------------
 
+// Reads the `media` attribute, preferring the parsed value on the
+// CSSStyleSheet (which normalizes whitespace/casing) and falling back to
+// the raw attribute on the owning element.
+function readMedia(el: HTMLElement, sheet: CSSStyleSheet | null): string | null {
+  const fromSheet = sheet?.media?.mediaText;
+  if (fromSheet) return fromSheet;
+  const attr = el.getAttribute("media");
+  return attr && attr.length > 0 ? attr : null;
+}
+
+// Reads the resolved CSS rule text from a stylesheet. Returns null when
+// `cssRules` is unreadable (cross-origin sheets without CORS access throw
+// SecurityError) so callers can record only the href in that case.
+function readSheetText(sheet: CSSStyleSheet): string | null {
+  try {
+    const rules = sheet.cssRules;
+    if (!rules) return null;
+    const parts: string[] = [];
+    for (let i = 0; i < rules.length; i++) {
+      parts.push(rules[i].cssText);
+    }
+    return parts.join("\n");
+  } catch {
+    return null;
+  }
+}
+
 function readViewport(): ViewportState {
   const vv = window.visualViewport;
   return {

packages/jspsych/tests/core/record-session.test.ts

@@ -150,6 +150,74 @@ describe("record_session option", () => {
     expect(rec.end_reason).toBe("finished");
   });
 
+  describe("stylesheet capture", () => {
+    afterEach(() => {
+      // Each test installs sheets directly on document.head; clean up so
+      // they don't leak across cases or pollute later tests in the file.
+      for (const el of Array.from(document.head.querySelectorAll("style,link"))) {
+        el.remove();
+      }
+    });
+
+    test("captures inline <style> rule text at session start", async () => {
+      const style = document.createElement("style");
+      style.textContent = ".jspsych-display-element { color: rebeccapurple; }";
+      document.head.appendChild(style);
+
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline([{ type: htmlKeyboardResponse, stimulus: "x" }], jsPsych);
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const inline = rec.stylesheets.filter((s) => s.kind === "inline");
+      expect(inline.length).toBeGreaterThan(0);
+      expect(inline.some((s) => s.css.includes("rebeccapurple"))).toBe(true);
+    });
+
+    test("captures <link rel=stylesheet> href even when CSS is unreadable", async () => {
+      const link = document.createElement("link");
+      link.rel = "stylesheet";
+      link.href = "https://example.test/jspsych.css";
+      document.head.appendChild(link);
+
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline([{ type: htmlKeyboardResponse, stimulus: "x" }], jsPsych);
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const linkSnaps = rec.stylesheets.filter((s) => s.kind === "link");
+      expect(linkSnaps.some((s) => s.href === "https://example.test/jspsych.css")).toBe(true);
+    });
+
+    test("snapshot is taken once at start and is not mutated by later <style> additions", async () => {
+      const style = document.createElement("style");
+      style.textContent = ".pre-existing { color: red; }";
+      document.head.appendChild(style);
+
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: "x",
+            on_load: () => {
+              const late = document.createElement("style");
+              late.textContent = ".added-during-trial { color: blue; }";
+              document.head.appendChild(late);
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const allCss = rec.stylesheets.map((s) => s.css ?? "").join("\n");
+      expect(allCss).toContain("pre-existing");
+      expect(allCss).not.toContain("added-during-trial");
+    });
+  });
+
   test("captures window scroll events", async () => {
     const jsPsych = initJsPsych({ record_session: true });
     await startTimeline(