@hajimism/dek 0.5.0 → 0.6.0

package/src/plugin-api.ts

@@ -0,0 +1,126 @@
+/// <reference lib="dom" />
+
+/**
+ * The types a dek plugin is written against, published as `@hajimism/dek/plugin` (ADR 32). They
+ * are types only: a plugin runs in a process of its own and shares no code with dek, only these
+ * shapes, which travel as JSON. Each grows only by adding; a change to one is a new `schema` or
+ * `protocol`.
+ */
+
+export type Severity = "error" | "warning";
+
+/** One rule a check can report. Only `error` fails `dekc lint`. */
+export type PluginRule = {
+  severity: Severity;
+  /** One line of fact, at most 120 characters; dek shows it only in SARIF's rule list. */
+  summary: string;
+};
+
+/** A plugin's rules by id: `<PREFIX>` and three digits, the prefix the name in capitals with `_` for `-`. */
+export type PluginRules<Prefix extends string = string> = Record<`${Prefix}${number}`, PluginRule>;
+
+/** What `dek-<name> manifest` prints: the promise the project pins in `plugins/<name>/plugin.json`. */
+export type PluginManifest<Prefix extends string = string> = {
+  schema: 1;
+  /** The `<name>` of `dek-<name>`. */
+  name: string;
+  /** Letters, digits, `.`, `+`, and `-`, at most 64 characters. */
+  version: string;
+  /** Without it, dek runs no check. */
+  check?: { protocol: 1; rules: PluginRules<Prefix> };
+  /** A page in the player and the build, which calls `dek.plugin` (page API 1). */
+  page?: {
+    api: 1;
+    /** Single letters the page binds; none of dek's own (a f l m p s). */
+    keys?: string[];
+  };
+  /**
+   * Files the plugin reads, which AGENTS.md names: relative to the deck's folder, or, with
+   * `in: "project"`, to `plugins/<name>/` in the project, for data the whole project shares. Only
+   * the deck's are served to a page.
+   */
+  data?: Array<{ path: string; in?: "project" }>;
+};
+
+/** One slide of the deck, as `check` reads it. Each path is relative to the deck's folder, or null when the file is not there. */
+export type CheckSlide = {
+  slug: string;
+  title: string;
+  html: string | null;
+  css: string | null;
+  ts: string | null;
+};
+
+/** What `dek-<name> check --protocol 1` reads on stdin, run in the deck's folder. */
+export type CheckInput = {
+  protocol: 1;
+  /** The version of the dek that runs the check. */
+  dek: string;
+  deck: { name: string; lang: string; slides: CheckSlide[] };
+  /**
+   * The absolute path of `plugins/<name>/` in the project, where the project's data files are,
+   * whether or not the folder exists (ADR 35). An older dek does not send it: read that as no
+   * project data.
+   */
+  pluginDir?: string;
+};
+
+/** One finding in a check's SARIF: the fields dek reads, and no others. */
+export type CheckResult<RuleId extends string = string> = {
+  /** A rule the manifest declares; its severity is the manifest's, whatever `level` says. */
+  ruleId: RuleId;
+  message: { text: string };
+  locations?: Array<{
+    physicalLocation: {
+      /**
+       * Relative to the deck's folder, or a `file:` URL inside it or inside `pluginDir`. dek drops
+       * a location anywhere else.
+       */
+      artifactLocation: { uri: string };
+      region?: { startLine: number; startColumn?: number };
+    };
+  }>;
+  /** What to do next. */
+  properties?: { hint?: string };
+};
+
+/** What `dek-<name> check` prints on stdout: SARIF 2.1.0, of which dek reads each run's results. */
+export type CheckOutput<RuleId extends string = string> = {
+  version: "2.1.0";
+  $schema?: string;
+  runs: Array<{
+    tool?: { driver: { name: string; version?: string } };
+    results: Array<CheckResult<RuleId>>;
+  }>;
+};
+
+/** Where the deck stands: the slide, its index, and the beat (0 is the slide's arrival). */
+export type PagePosition = { slug: string; index: number; beat: number };
+
+/**
+ * A slide drawn on the stage, for a page to draw over. `root` is the slide, to read and never to
+ * change: lint checked what is in it. `layer` lies over the slide, in the slide's own pixels, and
+ * is the plugin's alone. A slide a live reload replaced is mounted again.
+ */
+export type PageMount = { slug: string; root: HTMLElement; layer: ShadowRoot; view: "stage" };
+
+/** What `dek.plugin` hands a plugin's page: page API 1. */
+export type PageApi = {
+  deck: { name: string };
+  slides: Array<{ slug: string; title: string }>;
+  current(): PagePosition;
+  /** After the deck settles at a position, at the start and after every move, wherever it came from. */
+  on(event: "change", listener: (position: PagePosition) => void): void;
+  on(event: "mount", listener: (mount: PageMount) => void): void;
+  /** Whether `element` shows at the current beat: no beat that hides it is still to come. */
+  shown(element: Element): boolean;
+  /** A data file the manifest declares, as the project has it; `version` changes with the text. */
+  data(path: string): { text: string; version: string } | null;
+  /** Binds a key the manifest declares; false for any other. */
+  key(letter: string, listener: () => void): boolean;
+};
+
+/** The one global a plugin's page touches. */
+export type DekPage = {
+  plugin(name: string, options: { api: 1 }, setup: (api: PageApi) => void): void;
+};

package/src/plugins/study/check.ts

@@ -0,0 +1,128 @@
+import type { CheckInput } from "../../plugin-api.ts";
+import { type RuleId, STUDY_FILE } from "./manifest.ts";
+import { follows, normalize, occurrences, placeStickers } from "./place.ts";
+import { readStudy, type Sticker } from "./study.ts";
+import { slideText } from "./text.ts";
+
+/** A finding, which can name only a rule the manifest declares. Paths are relative to the deck. */
+export type Finding = { rule: RuleId; message: string; path: string; line: number; hint: string };
+
+/** Reads a file of the deck by its path relative to the deck's folder; undefined when absent. */
+export type ReadFile = (path: string) => Promise<string | undefined>;
+
+/**
+ * Checks the deck's stickers against its slides: each sticker's words are on its slide (STUDY001),
+ * no other place on the slide shows them unhidden (STUDY002), and study.yaml reads (STUDY003). A
+ * deck with no study.yaml has nothing to check.
+ */
+export async function check(input: CheckInput, read: ReadFile): Promise<Finding[]> {
+  const source = await read(STUDY_FILE);
+  if (source === undefined) {
+    return [];
+  }
+  const { stickers, problems } = readStudy(source);
+  const findings: Finding[] = problems.map((problem) => ({
+    rule: "STUDY003",
+    message: problem.message,
+    path: STUDY_FILE,
+    line: problem.line,
+    hint: "write study.yaml as https://hajimism.github.io/dek/reference/plugins.html#dek-study shows",
+  }));
+
+  const texts = new Map<string, string>();
+  const htmlPaths = new Map<string, string>();
+  for (const slide of input.deck.slides) {
+    const html = slide.html === null ? undefined : await read(slide.html);
+    texts.set(slide.slug, html === undefined ? "" : await slideText(html));
+    htmlPaths.set(slide.slug, slide.html ?? `slides/${slide.slug}.html`);
+  }
+
+  /** The one other slide the sticker would find its place on, prefix and all, if exactly one. */
+  const elsewhere = (sticker: Sticker): string | undefined => {
+    const found = [...texts].filter(
+      ([slug, text]) => slug !== sticker.slide && placeStickers(text, [sticker]).lost.length === 0,
+    );
+    return found.length === 1 ? found[0]?.[0] : undefined;
+  };
+  const lost = (sticker: Sticker, message: string, fallback: string): Finding => {
+    const other = elsewhere(sticker);
+    return {
+      rule: "STUDY001",
+      message,
+      path: STUDY_FILE,
+      line: sticker.line,
+      hint:
+        other === undefined
+          ? fallback
+          : `the words are on slide ${other}: set the sticker's \`slide: ${other}\``,
+    };
+  };
+
+  /**
+   * Why a sticker on a slide that is there found no place: its words are gone, no place of them
+   * follows its prefix, or the stickers before it took every place. Only gone words are looked
+   * for on other slides; words still on the slide are the sticker's to find there.
+   */
+  const lostOnSlide = (sticker: Sticker, slug: string, text: string, path: string): Finding => {
+    const quote = normalize(sticker.quote);
+    const places = occurrences(text, quote);
+    if (places.length === 0) {
+      return lost(
+        sticker,
+        `sticker ${sticker.id}: 「${sticker.quote}」 is not on slide ${slug}`,
+        `find where the words went in ${path} and set the sticker's quote and prefix to them, or delete the sticker`,
+      );
+    }
+    const prefix = sticker.prefix === undefined ? undefined : normalize(sticker.prefix);
+    if (prefix !== undefined && !places.some((place) => follows(text, place, prefix))) {
+      return {
+        rule: "STUDY001",
+        message: `sticker ${sticker.id}: 「${sticker.quote}」 is on slide ${slug}, but not after 「${sticker.prefix}」`,
+        path: STUDY_FILE,
+        line: sticker.line,
+        hint: `set the sticker's prefix to the words right before 「${sticker.quote}」 in ${path}, or leave the prefix out`,
+      };
+    }
+    return {
+      rule: "STUDY001",
+      message: `sticker ${sticker.id}: every 「${sticker.quote}」 on slide ${slug} has a sticker before this one`,
+      path: STUDY_FILE,
+      line: sticker.line,
+      hint: "delete the sticker, since another already hides these words",
+    };
+  };
+
+  const bySlide = Map.groupBy(stickers, (sticker) => sticker.slide);
+  for (const [slug, onSlide] of bySlide) {
+    const text = texts.get(slug);
+    if (text === undefined) {
+      for (const sticker of onSlide) {
+        findings.push(
+          lost(
+            sticker,
+            `sticker ${sticker.id}: slide ${slug} is not in this deck`,
+            "set the sticker's `slide` to the slide its words are on, or delete the sticker",
+          ),
+        );
+      }
+      continue;
+    }
+    const placement = placeStickers(text, onSlide);
+    for (const sticker of placement.lost) {
+      findings.push(lostOnSlide(sticker, slug, text, htmlPaths.get(slug) ?? ""));
+    }
+    for (const { first, count } of placement.shown) {
+      findings.push({
+        rule: "STUDY002",
+        message: `「${first.quote}」 is hidden by sticker ${first.id} but shows ${count} more ${count === 1 ? "time" : "times"} on slide ${slug}`,
+        path: STUDY_FILE,
+        line: first.line,
+        hint: `add a sticker for each other 「${first.quote}」 on the slide, with a prefix that tells it apart, or reword the others`,
+      });
+    }
+  }
+  // The same deck gives the same output, in the same order.
+  return findings.sort(
+    (a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.rule.localeCompare(b.rule),
+  );
+}

package/src/plugins/study/main.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+/**
+ * dek-study, the plugin dek ships (ADR 34). dek runs it as any plugin (ADR 32), in a bun of its
+ * own: `manifest` to pin what it promises, and `check --protocol 1` in a deck's folder, with the
+ * deck on stdin, for SARIF. It shares only the types in plugin-api.ts with dek, never its code.
+ */
+import { readFileSync } from "node:fs";
+import type { CheckInput } from "../../plugin-api.ts";
+import { check } from "./check.ts";
+import { MANIFEST } from "./manifest.ts";
+import { toSarif } from "./sarif.ts";
+
+const USAGE = "usage: dek-study manifest | dek-study check --protocol 1  (dek runs both)";
+
+async function main(args: string[]): Promise<number> {
+  switch (args[0]) {
+    case "manifest":
+      process.stdout.write(`${JSON.stringify(MANIFEST)}\n`);
+      return 0;
+    case "check": {
+      if (args[1] !== "--protocol" || args[2] !== "1") {
+        process.stderr.write(
+          `dek-study speaks check protocol 1; dek asked for ${args.slice(1).join(" ")}\n`,
+        );
+        return 2;
+      }
+      const input = JSON.parse(await Bun.stdin.text()) as CheckInput;
+      const findings = await check(input, async (path) => readIfThere(path));
+      process.stdout.write(`${JSON.stringify(toSarif(findings))}\n`);
+      return 0;
+    }
+    default:
+      process.stderr.write(`${USAGE}\n`);
+      return 2;
+  }
+}
+
+/** A file of the deck, relative to its folder, which is where dek runs the check. */
+function readIfThere(path: string): string | undefined {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+process.exit(await main(process.argv.slice(2)));

package/src/plugins/study/manifest.ts

@@ -0,0 +1,32 @@
+import type { PluginManifest, PluginRules } from "../../plugin-api.ts";
+
+/**
+ * The one place each rule is declared: the manifest prints it, and a finding can name only a rule
+ * here, so dek-study cannot report an id its manifest does not declare.
+ */
+const RULES = {
+  STUDY001: { severity: "error", summary: "a sticker's words are not on its slide" },
+  STUDY002: { severity: "warning", summary: "a sticker's words also show elsewhere on its slide" },
+  STUDY003: { severity: "error", summary: "study.yaml cannot be read" },
+} as const satisfies PluginRules<"STUDY">;
+
+export type RuleId = keyof typeof RULES;
+
+/** The file of stickers, in each deck's folder. */
+export const STUDY_FILE = "study.yaml";
+
+/**
+ * dek-study's own version, apart from dek's: a project accepts a change to what it promises, and
+ * a dek release that leaves the rules as they were must not ask for that.
+ */
+const VERSION = "0.1.0";
+
+/** What `dek-study manifest` prints: the same every time, since dek pins it. */
+export const MANIFEST = {
+  schema: 1,
+  name: "study",
+  version: VERSION,
+  check: { protocol: 1, rules: RULES },
+  page: { api: 1, keys: ["r"] },
+  data: [{ path: STUDY_FILE }],
+} as const satisfies PluginManifest<"STUDY">;

package/src/plugins/study/page.ts

@@ -0,0 +1,295 @@
+/// <reference lib="dom" />
+/**
+ * dek-study's page (ADR 34): a sheet of stickers over the words in study.yaml. `r` lays the sheet
+ * on and takes it off, and the page remembers which for the deck. The pointer on a sticker peels it
+ * back, and the words show through. It finds each sticker's words as the check does, with
+ * the same reader and the same placement, so a deck that passes lint is a deck the sheet covers.
+ */
+import type { DekPage, PageApi } from "../../plugin-api.ts";
+import { STUDY_FILE } from "./manifest.ts";
+import { normalize, placeStickers } from "./place.ts";
+import { readStudy, type Sticker } from "./study.ts";
+
+declare const dek: DekPage;
+
+/** How long a sticker takes to fade away under the pointer, and to come back after it. */
+const FADE_OUT_MS = 180;
+const FADE_IN_MS = 120;
+/** How long the sheet's state shows after `r`, before it gets out of the slide's way. */
+const TOAST_MS = 1500;
+/** How far a sticker reaches past its words, in ems of the words it hides: a little to each side, barely above and below. */
+const PAD_X = 0.18;
+const PAD_Y = 0.04;
+const UNSEEN = new Set(["SCRIPT", "STYLE", "TEMPLATE", "NOSCRIPT"]);
+
+/**
+ * A sticker is a slip of pale yellow paper, as a sticky note is, with square corners and the same
+ * on every theme, so it reads as something laid on the slide rather than part of it. Under the
+ * pointer it fades away and leaves a yellow rule under the words, so the place still reads as a
+ * sticker's; it comes back once the pointer leaves.
+ */
+const STYLE = `
+  .sheet { position: absolute; inset: 0; }
+  .sheet[hidden] { display: none; }
+  .sticker {
+    position: absolute;
+    pointer-events: auto;
+    background: rgb(255 240 160);
+    box-shadow: inset 0 calc(-1 * max(2px, 0.08em)) 0 rgb(240 206 72);
+    transition: background-color ${FADE_IN_MS}ms ease-in;
+  }
+  .sticker.peek {
+    background: rgb(255 240 160 / 0);
+    transition: background-color ${FADE_OUT_MS}ms ease-out;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .sticker, .sticker.peek, .toast, .toast.show { transition: none; }
+  }
+  .toast {
+    opacity: 0;
+    visibility: hidden;
+    transition: opacity ${FADE_OUT_MS}ms ease-in, visibility 0s ${FADE_OUT_MS}ms;
+    position: absolute;
+    top: 0;
+    right: 0;
+    padding: 6px 12px;
+    background: var(--study-ink);
+    color: var(--study-paper);
+    font: 600 13px/1.4 system-ui, sans-serif;
+    letter-spacing: 0.08em;
+  }
+  .toast.show {
+    opacity: 1;
+    visibility: visible;
+    transition: opacity ${FADE_IN_MS}ms ease-out, visibility 0s;
+  }
+`;
+
+dek.plugin("study", { api: 1 }, (api) => {
+  const file = api.data(STUDY_FILE);
+  const stickers = file ? readStudy(file.text).stickers : [];
+  const bySlide = Map.groupBy(stickers, (sticker) => sticker.slide);
+  const storage = `dek-study:${api.deck.name}:sheet`;
+  let on = readOn(storage);
+  const mounted = new Map<
+    string,
+    { root: HTMLElement; layer: ShadowRoot; sheet: HTMLElement; toast: HTMLElement }
+  >();
+  let toastTimer: ReturnType<typeof setTimeout> | undefined;
+
+  api.on("mount", ({ slug, root, layer }) => {
+    // The slide's own ink and paper, for the hairline and the notice, through the layer's host.
+    const slideStyle = getComputedStyle(root);
+    const host = layer.host as HTMLElement;
+    host.style.setProperty("--study-ink", slideStyle.color);
+    host.style.setProperty("--study-paper", paper(slideStyle.backgroundColor));
+    const style = document.createElement("style");
+    style.textContent = STYLE;
+    const sheet = document.createElement("div");
+    sheet.className = "sheet";
+    const toast = document.createElement("div");
+    toast.className = "toast";
+    layer.append(style, sheet, toast);
+    mounted.set(slug, { root, layer, sheet, toast });
+  });
+  api.on("change", ({ slug }) => draw(slug));
+  api.key("r", () => {
+    on = !on;
+    writeOn(storage, on);
+    const slug = api.current().slug;
+    draw(slug);
+    announce(slug);
+  });
+  // Text set in a web font moves once the font arrives.
+  void document.fonts?.ready.then(() => draw(api.current().slug));
+
+  /** Says for a moment whether the sheet is on. */
+  function announce(slug: string): void {
+    const toast = mounted.get(slug)?.toast;
+    if (!toast) {
+      return;
+    }
+    toast.textContent = on ? "SHEET ON" : "SHEET OFF";
+    toast.classList.add("show");
+    clearTimeout(toastTimer);
+    toastTimer = setTimeout(() => {
+      toast.classList.remove("show");
+    }, TOAST_MS);
+  }
+
+  function draw(slug: string): void {
+    const view = mounted.get(slug);
+    if (!view) {
+      return;
+    }
+    const { root, layer, sheet } = view;
+    sheet.replaceChildren();
+    sheet.hidden = !on;
+    if (!on) {
+      return;
+    }
+    const onSlide = bySlide.get(slug) ?? [];
+
+    const host = layer.host as HTMLElement;
+    const box = host.getBoundingClientRect();
+    const scale = host.offsetWidth > 0 ? box.width / host.offsetWidth : 1;
+    const words = readWords(root);
+    for (const { sticker, at } of placeStickers(words.text, onSlide).placed) {
+      const range = words.range(at, normalize(sticker.quote).length);
+      if (!range || !shown(api, range)) {
+        continue;
+      }
+      const ink = getComputedStyle(range.startContainer.parentElement ?? root);
+      const em = Number.parseFloat(ink.fontSize) || 16;
+      const pieces = lines(range.getClientRects()).map((rect) =>
+        stickerEl(sticker, ink, {
+          left: (rect.left - box.left) / scale - em * PAD_X,
+          top: (rect.top - box.top) / scale - em * PAD_Y,
+          width: (rect.right - rect.left) / scale + em * PAD_X * 2,
+          height: (rect.bottom - rect.top) / scale + em * PAD_Y * 2,
+        }),
+      );
+      peekTogether(pieces);
+      sheet.append(...pieces);
+    }
+  }
+});
+
+type Box = { left: number; top: number; right: number; bottom: number };
+
+/**
+ * The words' boxes, one per line: a range across elements, such as `<strong>外部</strong>視点`,
+ * gives a box for each, and one sticker over the words reads as one.
+ */
+function lines(rects: DOMRectList): Box[] {
+  const merged: Box[] = [];
+  const sorted = [...rects]
+    .filter((rect) => rect.width > 0 && rect.height > 0)
+    .sort((a, b) => a.top - b.top || a.left - b.left);
+  for (const rect of sorted) {
+    const last = merged.at(-1);
+    const sameLine = last && rect.top < last.bottom && rect.bottom > last.top;
+    if (last && sameLine && rect.left <= last.right + 1) {
+      last.left = Math.min(last.left, rect.left);
+      last.top = Math.min(last.top, rect.top);
+      last.right = Math.max(last.right, rect.right);
+      last.bottom = Math.max(last.bottom, rect.bottom);
+    } else {
+      merged.push({ left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom });
+    }
+  }
+  return merged;
+}
+
+/** A sticker in the color and size of the words under it, so its ems are theirs. */
+function stickerEl(
+  sticker: Sticker,
+  ink: CSSStyleDeclaration,
+  box: { left: number; top: number; width: number; height: number },
+): HTMLElement {
+  const el = document.createElement("div");
+  el.className = "sticker";
+  el.dataset.id = sticker.id;
+  el.style.cssText = `left:${box.left}px;top:${box.top}px;width:${box.width}px;height:${box.height}px;font-size:${ink.fontSize}`;
+  return el;
+}
+
+/** The slide's background, or white where the slide leaves it transparent. */
+function paper(background: string): string {
+  return background === "" || background === "transparent" || /rgba\(.*,\s*0\)$/.test(background)
+    ? "#fff"
+    : background;
+}
+
+/** A sticker that wraps onto two lines is one sticker: the pointer on either piece peels both. */
+function peekTogether(pieces: HTMLElement[]): void {
+  const peek = (on: boolean) => {
+    for (const piece of pieces) {
+      piece.classList.toggle("peek", on);
+    }
+  };
+  for (const piece of pieces) {
+    piece.addEventListener("pointerenter", () => peek(true));
+    piece.addEventListener("pointerleave", () => peek(false));
+  }
+}
+
+/** A sticker covers words only once they show: one over a beat still to come would give it away. */
+function shown(api: PageApi, range: Range): boolean {
+  const start = range.startContainer.parentElement;
+  const end = range.endContainer.parentElement;
+  return (!start || api.shown(start)) && (!end || api.shown(end));
+}
+
+/**
+ * The slide's words as the check reads them, whitespace collapsed, and a way back from a place in
+ * them to the DOM: each character kept remembers the text node and offset it came from.
+ */
+function readWords(root: HTMLElement): {
+  text: string;
+  range: (at: number, length: number) => Range | undefined;
+} {
+  const chars: Array<{ node: Text; offset: number }> = [];
+  let text = "";
+  let space = false;
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+    acceptNode: (node) =>
+      unseen(node, root) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT,
+  });
+  for (let node = walker.nextNode() as Text | null; node; node = walker.nextNode() as Text | null) {
+    const data = node.data;
+    for (let offset = 0; offset < data.length; offset += 1) {
+      const char = data[offset] as string;
+      if (/\s/.test(char)) {
+        space = text.length > 0;
+        continue;
+      }
+      if (space) {
+        text += " ";
+        chars.push({ node, offset });
+        space = false;
+      }
+      text += char;
+      chars.push({ node, offset });
+    }
+  }
+  return {
+    text,
+    range(at, length) {
+      const first = chars[at];
+      const last = chars[at + length - 1];
+      if (!first || !last) {
+        return undefined;
+      }
+      const range = document.createRange();
+      range.setStart(first.node, first.offset);
+      range.setEnd(last.node, last.offset + 1);
+      return range;
+    },
+  };
+}
+
+function unseen(node: Node, root: HTMLElement): boolean {
+  for (let el = node.parentElement; el && el !== root; el = el.parentElement) {
+    if (UNSEEN.has(el.tagName)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function readOn(key: string): boolean {
+  try {
+    return localStorage.getItem(key) === "on";
+  } catch {
+    return false;
+  }
+}
+
+function writeOn(key: string, on: boolean): void {
+  try {
+    localStorage.setItem(key, on ? "on" : "off");
+  } catch {
+    // A page whose storage is blocked forgets; the sheet still works for the visit.
+  }
+}