explico 0.13.1 → 0.14.0

package/src/session/deck-memory.ts

@@ -0,0 +1,263 @@
+/**
+ * What a reader's decks remember (`docs/authoring/deck.md`, "Present mode and
+ * the study page"): for each deck, the frame and the step Present mode last
+ * stood on, and every frame it showed them, as it was. A frame's content is
+ * named by its id (`ManifestDeckFrame.id`, 12 hex digits of a hash over what
+ * it shows), so a frame that changed since the reader was shown it is told
+ * from one they were never shown, as `page-marks.ts` tells pages apart.
+ *
+ * One small JSON map per course,
+ * `{ "v": 2, "decks": { slug: { at, step, seen } } }`, kept through the
+ * `PreferenceStore` under `deckPositionsKey(base)`. It is reading memory
+ * (`reading-memory.ts`): with the reader's yes it is kept
+ * across visits; before an answer it is kept for the tab, as kept cards are;
+ * after a no, only where each deck stopped is, for the tab. Version 1,
+ * `{ slug: number }`, held the stopping place alone, and reads as version 2
+ * with no frame shown.
+ *
+ * Pure: `components/deck/deck-controller.ts` does the DOM and the storage on
+ * a deck's page, the sidebar's script (`LayoutSidebar.astro`) its two
+ * actions, which cover every deck, `reading-memory.ts` what the reader's
+ * answer does to the tab's record, and `tests/unit/deck-memory.test.ts`
+ * checks this in Node.
+ */
+
+/** A frame as the page knows it: its number in the deck, and its content's id. */
+export interface DeckFrameId {
+  readonly number: number;
+  readonly id: string;
+}
+
+/** A frame as the study page knows it, with the steps it has (`data-steps`). */
+export interface DeckFrameSteps extends DeckFrameId {
+  readonly steps: number;
+}
+
+/** A deck as the sidebar's two actions need it. */
+export interface DeckFrames {
+  /** Its route, as `.deck[data-deck]` names it: `motion/position-and-coordinates/slides`. */
+  readonly slug: string;
+  readonly frames: readonly DeckFrameId[];
+}
+
+/** What one deck remembers. */
+export interface DeckRecord {
+  /** The frame Present mode last stood on, by number. */
+  readonly at?: number;
+  /** The step of that frame it stood on: none in a record kept before steps were. */
+  readonly step?: number;
+  /** The frames Present mode showed, by number: the id each had then. */
+  readonly seen: ReadonlyMap<number, string>;
+}
+
+/** Where "Continue" presents from (`resumeAt`). */
+export interface Resume {
+  /** The frame, by its number now; the first frame for "Present again". */
+  readonly number: number;
+  /** The reader was shown every step of the deck's last frame: "Present again". */
+  readonly again: boolean;
+}
+
+/** Every deck's record, by its slug. */
+export type DeckMemory = ReadonlyMap<string, DeckRecord>;
+
+/** A frame's mark on the study page: not shown in Present mode yet, or changed since it was. */
+export type FrameMark = 'unseen' | 'changed';
+
+/**
+ * Told on a page after deck memory was written there, so the deck's page and
+ * the sidebar read it again; another tab hears the `storage` event.
+ */
+export const DECK_MEMORY_EVENT = 'explico:deck-memory';
+
+/** Bumped whenever the stored shape changes. */
+const VERSION = 2;
+const ID = /^[0-9a-f]{12}$/u;
+const NUMBER = /^[1-9][0-9]*$/u;
+
+function isFrameNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+
+/** A record holding `at`, and `step` with it when there is one. */
+function place(at: number | undefined, step: number | undefined): { at?: number; step?: number } {
+  if (at === undefined) return {};
+  return step === undefined ? { at } : { at, step };
+}
+
+function byText(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** One deck's stored record, or none when nothing in it can be trusted. */
+function readRecord(value: unknown): DeckRecord | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const { at, step, seen } = value as { at?: unknown; step?: unknown; seen?: unknown };
+  const frames = new Map<number, string>();
+  if (seen && typeof seen === 'object' && !Array.isArray(seen)) {
+    for (const [number, id] of Object.entries(seen as Record<string, unknown>)) {
+      if (NUMBER.test(number) && isFrameNumber(Number(number)) && typeof id === 'string' && ID.test(id)) {
+        frames.set(Number(number), id);
+      }
+    }
+  }
+  if (!isFrameNumber(at) && frames.size === 0) return undefined;
+  // A step belongs to its frame: none without one.
+  return { ...(isFrameNumber(at) ? place(at, isFrameNumber(step) ? step : undefined) : {}), seen: frames };
+}
+
+/**
+ * Every deck's record, from the stored text. Version 1 becomes version 2,
+ * each deck's place kept and no frame shown. Anything else, and any entry
+ * that is not a frame number or a frame's id, is dropped, never trusted.
+ */
+export function decodeDeckMemory(raw: string | null): DeckMemory {
+  const memory = new Map<string, DeckRecord>();
+  if (!raw) return memory;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return memory;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return memory;
+  const stored = parsed as Record<string, unknown>;
+  if (!('v' in stored)) {
+    for (const [slug, at] of Object.entries(stored)) {
+      if (slug.length > 0 && isFrameNumber(at)) memory.set(slug, { at, seen: new Map() });
+    }
+    return memory;
+  }
+  const { v, decks } = stored;
+  if (v !== VERSION || !decks || typeof decks !== 'object' || Array.isArray(decks)) return memory;
+  for (const [slug, value] of Object.entries(decks as Record<string, unknown>)) {
+    const record = slug.length > 0 ? readRecord(value) : undefined;
+    if (record) memory.set(slug, record);
+  }
+  return memory;
+}
+
+/** The stored text: decks sorted by slug, frames by number, so the same state is always the same string. */
+export function encodeDeckMemory(memory: DeckMemory): string {
+  const decks = [...memory]
+    .sort(([a], [b]) => byText(a, b))
+    .map(([slug, record]) => [
+      slug,
+      {
+        ...place(record.at, record.step),
+        seen: Object.fromEntries([...record.seen].sort(([a], [b]) => a - b).map(([number, id]) => [String(number), id])),
+      },
+    ]);
+  return JSON.stringify({ v: VERSION, decks: Object.fromEntries(decks) });
+}
+
+/** `memory` with `slug`'s record replaced; a record that holds nothing goes. */
+function withRecord(memory: DeckMemory, slug: string, record: DeckRecord | undefined): Map<string, DeckRecord> {
+  const next = new Map(memory);
+  if (record && (record.at !== undefined || record.seen.size > 0)) next.set(slug, record);
+  else next.delete(slug);
+  return next;
+}
+
+/**
+ * The record after Present mode stood on step `step` of frame `number` of
+ * `slug`, while the frames shown are not kept: the place alone, the frames
+ * shown left as they were.
+ */
+export function withPosition(memory: DeckMemory, slug: string, number: number, step: number): Map<string, DeckRecord> {
+  return withRecord(memory, slug, { ...place(number, step), seen: memory.get(slug)?.seen ?? new Map() });
+}
+
+/**
+ * The record after Present mode showed `frame` of `slug` at step `step`, in
+ * the room's window or the presenter's (D8): the reader stands there, and has
+ * seen the frame as it is now, whichever of its steps they saw.
+ */
+export function withShown(memory: DeckMemory, slug: string, frame: DeckFrameId, step: number): Map<string, DeckRecord> {
+  const seen = new Map(memory.get(slug)?.seen);
+  seen.set(frame.number, frame.id);
+  return withRecord(memory, slug, { ...place(frame.number, step), seen });
+}
+
+/** "Mark all as seen" on a deck's page: every frame of `slug` seen as it is now. Where it stopped stays. */
+export function withAllSeen(memory: DeckMemory, slug: string, frames: readonly DeckFrameId[]): Map<string, DeckRecord> {
+  const record = memory.get(slug);
+  return withRecord(memory, slug, {
+    ...place(record?.at, record?.step),
+    seen: new Map(frames.map((frame) => [frame.number, frame.id])),
+  });
+}
+
+/** "Mark all as unseen" on a deck's page: no frame of `slug` seen. Where it stopped stays. */
+export function withNoneSeen(memory: DeckMemory, slug: string): Map<string, DeckRecord> {
+  const record = memory.get(slug);
+  return withRecord(memory, slug, record?.at === undefined ? undefined : { ...place(record.at, record.step), seen: new Map() });
+}
+
+/**
+ * Two records as one, for the reader's yes (`reading-memory.ts`): what the
+ * tab kept before it (`newer`) joins what the browser kept from an earlier
+ * visit (`older`). Each deck stops where `newer` says, when it says; a frame
+ * shown in both is as `newer` saw it.
+ */
+export function mergeDeckMemory(older: DeckMemory, newer: DeckMemory): Map<string, DeckRecord> {
+  const merged = new Map(older);
+  for (const [slug, record] of newer) {
+    const before = older.get(slug);
+    const at = record.at ?? before?.at;
+    merged.set(slug, {
+      ...place(at, record.at === undefined ? before?.step : record.step),
+      seen: new Map([...(before?.seen ?? []), ...record.seen]),
+    });
+  }
+  return merged;
+}
+
+/** The sidebar's "Mark all as seen" (D9): every frame of every deck seen as it is now. */
+export function withEveryDeckSeen(memory: DeckMemory, decks: readonly DeckFrames[]): Map<string, DeckRecord> {
+  let next = new Map(memory);
+  for (const deck of decks) next = withAllSeen(next, deck.slug, deck.frames);
+  return next;
+}
+
+/** The sidebar's "Mark all as unseen" (D9): no frame of any deck seen. Where each stopped stays. */
+export function withEveryDeckUnseen(memory: DeckMemory): Map<string, DeckRecord> {
+  let next = new Map(memory);
+  for (const slug of memory.keys()) next = withNoneSeen(next, slug);
+  return next;
+}
+
+/**
+ * A frame's mark for a reader whose record of its deck is `record`: none
+ * when they were shown it as it is now, whatever its number was then (a
+ * frame added before it moves it, and it is still the frame they saw);
+ * `changed` when its place showed them something else; else `unseen`.
+ */
+export function frameMark(frame: DeckFrameId, record: DeckRecord | undefined): FrameMark | undefined {
+  const seen = record?.seen;
+  if (!seen || seen.size === 0) return 'unseen';
+  if (seen.get(frame.number) === frame.id) return undefined;
+  for (const id of seen.values()) if (id === frame.id) return undefined;
+  return seen.has(frame.number) ? 'changed' : 'unseen';
+}
+
+/**
+ * Where "Continue at slide N" presents from (D7): the frame the reader
+ * stopped at, unless they were shown its every step, then the frame after it
+ * — or, after the last frame, "Present again" from the first. The frame is
+ * followed to its number now when frames were added or taken out before it,
+ * by the id it had. None when nothing is remembered or the deck no longer
+ * has that frame. A record kept before steps were counts as stopped partway.
+ */
+export function resumeAt(record: DeckRecord | undefined, frames: readonly DeckFrameSteps[]): Resume | undefined {
+  const at = record?.at;
+  if (at === undefined) return undefined;
+  const id = record?.seen.get(at);
+  const there = frames.find((frame) => frame.number === at);
+  const moved = id === undefined || there?.id === id ? undefined : frames.find((frame) => frame.id === id);
+  const stopped = moved ?? there;
+  if (!stopped) return undefined;
+  if (record?.step === undefined || record.step < stopped.steps) return { number: stopped.number, again: false };
+  const after = frames[frames.indexOf(stopped) + 1];
+  return after ? { number: after.number, again: false } : { number: frames[0]!.number, again: true };
+}

package/src/session/reading-memory.ts

@@ -0,0 +1,243 @@
+/**
+ * The one question explico asks a reader: may this course remember their
+ * reading in this browser? (`readingMemory` in the course settings.)
+ *
+ * **Reading memory** is what records what the reader did, across visits:
+ * which chapters they opened (the sidebar marks and the "changed since you
+ * last opened it" note, `page-marks.ts`), the cards they kept open on a page
+ * (`card-memory.ts`), the cards they carry from page to page
+ * (`card-carry.ts`), and where each deck stopped and which slides Present
+ * mode showed them (`deck-memory.ts`). It is kept only with the reader's yes.
+ * Without it — before they answer, after a no, or when the course turns the
+ * question off — nothing of their reading outlives the tab: no visit is
+ * recorded and no page is marked, and kept and carried cards and where a deck
+ * stopped live in the tab's session storage, so they still work until the tab
+ * is closed. The slides Present mode showed live there too before an answer,
+ * marked on the deck's page; a no clears them, and none is recorded after it.
+ *
+ * **Settings** are not reading memory: the theme, the text size, the panels'
+ * layout, a folded section or sidebar part, which edition a lesson's sidebar
+ * row opens, the "Carry cards" switch. The
+ * reader sets each of them, and they are kept because the reader set them,
+ * the exemption the ePrivacy rules give a preference the user asked for. They
+ * need no answer. Nothing explico stores is a cookie, and nothing leaves the
+ * browser.
+ *
+ * The answer itself is kept (storing a consent choice needs no consent), per
+ * course, for 13 months, after which the course asks again. A no deletes
+ * whatever reading memory the course had; "Forget what this course stored"
+ * (the `[?]` panel) deletes everything, the answer included.
+ *
+ * Storage goes through the `PreferenceStore` only. The pure half
+ * (`decodeAnswer`, `courseKeys`, …) is checked in Node by
+ * `tests/unit/reading-memory.test.ts`.
+ */
+import {
+  createBrowserPreferenceStore,
+  createSessionPreferenceStore,
+  type PreferenceStore,
+} from './PreferenceStore';
+import {
+  decodeDeckMemory,
+  encodeDeckMemory,
+  mergeDeckMemory,
+  withEveryDeckUnseen,
+} from './deck-memory';
+
+/** The reader's answer: yes, no, or not asked yet (or asked too long ago). */
+export type ReadingAnswer = 'yes' | 'no' | 'unasked';
+
+/** The course's `readingMemory` setting: ask the reader, or never keep reading memory. */
+export type ReadingMemoryMode = 'ask' | 'off';
+
+/** How long an answer stands before the course asks again: 13 months. */
+export const ANSWER_LIFETIME_DAYS = 396;
+
+/** Bumped whenever the stored answer's shape changes; another version counts as not asked. */
+const VERSION = 1;
+const DAY = 24 * 60 * 60 * 1000;
+
+/** The event every part of the page listens to when the reader answers or forgets. */
+export const READING_MEMORY_EVENT = 'explico:reading-memory';
+
+export interface ReadingMemoryChange {
+  readonly base: string;
+  readonly answer: ReadingAnswer;
+}
+
+/** Where a course keeps the reader's answer. */
+export function answerKey(base: string): string {
+  return `explico-reading-memory:${base}`;
+}
+
+/** The stored answer's text. */
+export function encodeAnswer(yes: boolean, now: Date): string {
+  return JSON.stringify({ v: VERSION, remember: yes, at: now.toISOString().slice(0, 10) });
+}
+
+/** The answer a stored text holds on `now`: anything unreadable, or older than its lifetime, is not asked. */
+export function decodeAnswer(raw: string | null, now: Date): ReadingAnswer {
+  if (!raw) return 'unasked';
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return 'unasked';
+  }
+  if (!parsed || typeof parsed !== 'object') return 'unasked';
+  const { v, remember, at } = parsed as { v?: unknown; remember?: unknown; at?: unknown };
+  if (v !== VERSION || typeof remember !== 'boolean' || typeof at !== 'string') return 'unasked';
+  const given = Date.parse(`${at}T00:00:00Z`);
+  if (!Number.isFinite(given) || now.getTime() - given > ANSWER_LIFETIME_DAYS * DAY || given - now.getTime() > DAY) {
+    return 'unasked';
+  }
+  return remember ? 'yes' : 'no';
+}
+
+/** Explico's settings that every course on one site shares: not named by a course's base path. */
+const SHARED_SETTINGS = [
+  /^explico:display:/u,
+  /^explico:layout:/u,
+  /^explico-sidebar-groups$/u,
+  /^explico-sidebar-editions$/u,
+  /^explico:cards:carry$/u,
+];
+
+/**
+ * Where a course keeps, for each of its decks, the frame Present mode last
+ * stood on and the frames it showed (`deck-memory.ts`, `deck-controller.ts`).
+ */
+export function deckPositionsKey(base: string): string {
+  return `explico:decks:${base}`;
+}
+
+/**
+ * A key that is this course's reading memory: its visits, its kept and its
+ * carried cards, where its decks stopped and the slides they showed.
+ */
+export function isReadingMemoryKey(key: string, base: string): boolean {
+  return (
+    key === `explico-page-marks:${base}` ||
+    key === `explico:cards:carried:${base}` ||
+    key === deckPositionsKey(base) ||
+    (key.startsWith(`explico:cards:${base}`) && !key.startsWith('explico:cards:carried:'))
+  );
+}
+
+/**
+ * Every key this course stored, of the keys a store holds: its reading
+ * memory, its answer, its sections' and cards' per-page state, and the
+ * settings every explico course on this site shares, which forgetting this
+ * course resets too. Starlight's own theme key goes with them.
+ */
+export function courseKeys(keys: readonly string[], base: string): string[] {
+  return keys.filter(
+    (key) =>
+      isReadingMemoryKey(key, base) ||
+      key === answerKey(base) ||
+      key.startsWith(`disclosure:${base}`) ||
+      key === 'explico:cards:opened-at' ||
+      key === 'starlight-theme' ||
+      key === 'sl-sidebar-state' ||
+      SHARED_SETTINGS.some((pattern) => pattern.test(key)),
+  );
+}
+
+// --- in the browser -----------------------------------------------------
+
+const local = createBrowserPreferenceStore();
+const session = createSessionPreferenceStore();
+
+function remove(store: PreferenceStore, key: string): void {
+  if (store.remove) store.remove(key);
+  else store.set(key, '');
+}
+
+/** The course's setting, from the element `ReadingMemoryNotice.astro` renders on every page. */
+export function readingMemoryMode(): ReadingMemoryMode {
+  const element = document.querySelector<HTMLElement>('[data-explico-reading-memory]');
+  return element?.dataset.explicoReadingMemory === 'off' ? 'off' : 'ask';
+}
+
+/** The reader's answer for the course at `base`. */
+export function readingAnswer(base: string, now = new Date()): ReadingAnswer {
+  return decodeAnswer(local.get(answerKey(base)), now);
+}
+
+/** Whether the course may keep the reader's reading memory: they said yes, and the course asks. */
+export function rememberReading(base: string): boolean {
+  return readingMemoryMode() === 'ask' && readingAnswer(base) === 'yes';
+}
+
+/**
+ * Where reading memory goes: kept in the browser with the reader's yes, else
+ * the tab's session only. Read the session copy too when kept, so the cards
+ * of a visit that started before the yes are not lost.
+ */
+export function readingMemoryStore(base: string): PreferenceStore {
+  if (!rememberReading(base)) return session;
+  return {
+    get: (key) => local.get(key) ?? session.get(key),
+    set: (key, value) => local.set(key, value),
+    remove: (key) => {
+      remove(local, key);
+      remove(session, key);
+    },
+  };
+}
+
+/** Delete the course's reading memory from the browser (the tab's session copy stays). */
+export function forgetReadingMemory(base: string): void {
+  for (const key of local.keys?.() ?? []) if (isReadingMemoryKey(key, base)) remove(local, key);
+}
+
+function announce(base: string): void {
+  window.dispatchEvent(
+    new CustomEvent<ReadingMemoryChange>(READING_MEMORY_EVENT, { detail: { base, answer: readingAnswer(base) } }),
+  );
+}
+
+/**
+ * The slides this tab recorded as shown before an answer, and where each deck
+ * stopped, kept in the browser with the reader's yes: the next visit marks
+ * them too.
+ */
+function keepShownSlides(base: string): void {
+  const raw = session.get(deckPositionsKey(base));
+  if (!raw) return;
+  const kept = mergeDeckMemory(decodeDeckMemory(local.get(deckPositionsKey(base))), decodeDeckMemory(raw));
+  local.set(deckPositionsKey(base), encodeDeckMemory(kept));
+}
+
+/**
+ * The slides this tab recorded as shown before an answer, cleared after a
+ * no: where each deck stopped stays for the tab, as kept cards do.
+ */
+function forgetShownSlides(base: string): void {
+  const raw = session.get(deckPositionsKey(base));
+  if (raw) session.set(deckPositionsKey(base), encodeDeckMemory(withEveryDeckUnseen(decodeDeckMemory(raw))));
+}
+
+/**
+ * Record the reader's answer. A yes keeps the slides the tab recorded before
+ * it; a no deletes the course's reading memory, and those slides. Everything
+ * on the page is told.
+ */
+export function answerReadingMemory(base: string, yes: boolean, now = new Date()): void {
+  local.set(answerKey(base), encodeAnswer(yes, now));
+  if (yes) {
+    keepShownSlides(base);
+  } else {
+    forgetReadingMemory(base);
+    forgetShownSlides(base);
+  }
+  announce(base);
+}
+
+/** "Forget what this course stored": every key of the course, in the browser and the tab; the course asks again. */
+export function forgetCourse(base: string): void {
+  for (const store of [local, session]) {
+    for (const key of courseKeys(store.keys?.() ?? [], base)) remove(store, key);
+  }
+  announce(base);
+}