@hajimism/dek 0.1.0

package/src/core/slide-eval-worker.ts

@@ -0,0 +1,58 @@
+/**
+ * Evaluates compiled slide scripts for lint, away from the dek process.
+ * Reads a JSON array of classic scripts on stdin and writes one JSON line per
+ * script as it finishes. Each script runs in a fresh context with no host
+ * objects, so it cannot reach Bun, process, or the file system, and a loop
+ * that never ends is cut off; the parent's timeout covers anything that
+ * escapes into the microtask queue.
+ */
+import { readFileSync, writeSync } from "node:fs";
+import vm from "node:vm";
+
+const SLIDE_EVAL_TIMEOUT_MS = 1000;
+
+/** Runs inside the context, so reading the module's fields cannot run code in dek. */
+const SUMMARY = `(function () {
+  var module = globalThis.__dekSlides && globalThis.__dekSlides.slide;
+  if (module === null || typeof module !== "object") return JSON.stringify({ object: false });
+  var motion = module.motion;
+  return JSON.stringify({
+    object: true,
+    draw: typeof module.draw,
+    motion: motion === undefined ? "none"
+      : motion === null || typeof motion !== "object" ? "invalid"
+      : Object.keys(motion).map(function (key) {
+          var ms = motion[key];
+          return [key, typeof ms === "number" && isFinite(ms) ? ms : null];
+        }),
+  });
+})()`;
+
+function evaluate(code: string): string {
+  const context = vm.createContext(Object.create(null));
+  try {
+    return vm.runInContext(
+      `var window = globalThis;
+try {
+  new Function(${JSON.stringify(code)})();
+} catch (error) {
+  throw String(error && error.message !== undefined ? error.message : error);
+}
+${SUMMARY}`,
+      context,
+      { timeout: SLIDE_EVAL_TIMEOUT_MS },
+    ) as string;
+  } catch (error) {
+    if (typeof error === "string") {
+      return JSON.stringify({ threw: error });
+    }
+    return JSON.stringify({ timedOut: true });
+  }
+}
+
+const scripts = JSON.parse(readFileSync(0, "utf8")) as string[];
+for (const code of scripts) {
+  writeSync(1, `${evaluate(code)}\n`);
+}
+// Exit before the event loop can drain promises the scripts queued.
+process.exit(0);

package/src/core/slide-measure.ts

@@ -0,0 +1,272 @@
+// This runs in the page. TypeScript 6 and later fold dom.iterable into dom; naming it keeps the
+// spreads of NodeLists and DOMTokenLists typed for any compiler that reads the file.
+/// <reference lib="dom" />
+/// <reference lib="dom.iterable" />
+/**
+ * The id of a still page's `<style>` holding the slide's own CSS, apart from the theme, so a
+ * measurement can take it away and see what the theme alone draws.
+ */
+export const SLIDE_CSS_ID = "dek-slide-css";
+
+/** A rectangle in viewport pixels. */
+export type Box = {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+};
+
+/** One element inside `.slide`, as the page lays it out. */
+export type MeasuredElement = {
+  /** A short, readable selector: tag, id, first authored class, data-step. */
+  box: string;
+  /** Index of the nearest measured ancestor, or -1 when that is the slide itself. */
+  parent: number;
+  rect: Box;
+  /** The element's own text, or its whole text when it has none of its own. */
+  text?: string;
+  /** Whether `text` comes from the element's own text nodes. */
+  ownText: boolean;
+  /** The line boxes of the element's own text, where its glyphs are drawn. */
+  textRects: Box[];
+  /** Its opacity with every ancestor's multiplied in: how faint the page draws it. */
+  opacity: number;
+  fontSize: number;
+  fontWeight: number;
+  /**
+   * Whether it is decoration: it or an ancestor is `aria-hidden="true"`, as a glow or a sample of
+   * bad contrast is. Neither overflow nor contrast is measured on decoration.
+   */
+  decorative: boolean;
+  /**
+   * Whether it draws a picture the audience looks at: an image, an SVG, a video, a canvas, an
+   * embedded frame or object, or an image set as its background.
+   */
+  picture: boolean;
+  /** Whether it paints its own box: a background, or a border in a color that shows. */
+  paints: boolean;
+  /**
+   * What an ancestor inside the slide cuts it to, with `overflow` other than `visible`: the
+   * nearest such ancestor, and the box every one of them leaves visible. `intended` when the cut is
+   * a truncation the author asked for, an ellipsis or a line clamp.
+   */
+  clip?: { box: string; rect: Box; intended: boolean };
+};
+
+/**
+ * Text a `::before` or `::after` draws, such as a folio from `counter()` or a running head. The page
+ * gives no box for it; the worker asks Chromium for one, by the mark this leaves on its host.
+ */
+type PseudoText = {
+  /** The host's mark, `data-dek-text` on the element, shared by both of its pseudo-elements. */
+  host: string;
+  pseudo: "before" | "after";
+  /** The host's short selector with the pseudo-element, as `section.slide::after`. */
+  box: string;
+  /** The `content` it draws, as the page computes it, its strings unquoted. */
+  text: string;
+  opacity: number;
+  fontSize: number;
+  fontWeight: number;
+};
+
+/** The attribute a pseudo text's host carries while it is measured; see `PseudoText`. */
+export const PSEUDO_TEXT_HOST = "data-dek-text";
+
+export type SlideMeasure = {
+  slideBox: Box | undefined;
+  elements: MeasuredElement[];
+  pseudoTexts: PseudoText[];
+};
+
+/**
+ * Measures the first `.slide` in the current document, and marks each element that draws a pseudo
+ * text with `data-dek-text` (and `data-dek-text-before` or `-after`) for the worker to find. It runs
+ * inside the page through `page.evaluate`, which serializes only this function, so it must not
+ * reference anything outside its own body.
+ */
+export function measureSlideInPage(): SlideMeasure {
+  const slide = document.querySelector(".slide");
+  if (!slide) {
+    return { slideBox: undefined, elements: [], pseudoTexts: [] };
+  }
+  const runtimeClasses = new Set(["is-current", "is-shown"]);
+  const pictures = new Set(["img", "svg", "video", "canvas", "iframe", "object", "embed"]);
+  // Computed colors come back as rgba() or, from a newer syntax, with a "/ alpha" at the end.
+  const shows = (color: string): boolean =>
+    color !== "transparent" && !/^rgba\([^)]*,\s*0\)$/.test(color) && !/\/\s*0\)$/.test(color);
+  const paints = (style: CSSStyleDeclaration): boolean =>
+    style.backgroundImage !== "none" ||
+    shows(style.backgroundColor) ||
+    (["Top", "Right", "Bottom", "Left"] as const).some(
+      (side) =>
+        Number.parseFloat(style[`border${side}Width`]) > 0 &&
+        style[`border${side}Style`] !== "none" &&
+        shows(style[`border${side}Color`]),
+    );
+  const toBox = (rect: DOMRect): Box => ({
+    left: rect.left,
+    top: rect.top,
+    right: rect.right,
+    bottom: rect.bottom,
+  });
+  const squash = (text: string): string => text.replace(/\s+/g, " ").trim();
+  // An unbreakable string (a URL, a code line) runs sideways past its box
+  // without growing it, so the element's own text widens the box. Only
+  // sideways: glyphs rise above a tight line box without overflowing anything.
+  const extent = (el: Element, textNodes: Node[]): Box => {
+    const box = toBox(el.getBoundingClientRect());
+    // An element that clips its own content shows none of its text past its box.
+    if (getComputedStyle(el).overflowX !== "visible") {
+      return box;
+    }
+    for (const node of textNodes) {
+      const range = document.createRange();
+      range.selectNodeContents(node);
+      const rect = range.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) {
+        continue;
+      }
+      box.left = Math.min(box.left, rect.left);
+      box.right = Math.max(box.right, rect.right);
+    }
+    return box;
+  };
+  const describe = (el: Element): string => {
+    let box = el.tagName.toLowerCase();
+    if (el.id) {
+      box += `#${el.id}`;
+    }
+    const authored = [...el.classList].find((name) => !runtimeClasses.has(name));
+    if (authored) {
+      box += `.${authored}`;
+    }
+    const step = el.getAttribute("data-step");
+    if (step) {
+      box += `[data-step="${step}"]`;
+    }
+    return box;
+  };
+  const opacityOf = (el: Element): number => {
+    // Hidden text is not drawn at all, however opaque.
+    if (getComputedStyle(el).visibility !== "visible") {
+      return 0;
+    }
+    let opacity = 1;
+    for (let current: Element | null = el; current; current = current.parentElement) {
+      const own = Number.parseFloat(getComputedStyle(current).opacity);
+      opacity *= Number.isNaN(own) ? 1 : own;
+    }
+    return opacity;
+  };
+  const clipped = (clip: MeasuredElement["clip"]) => (clip ? { clip } : {});
+  const truncates = (style: CSSStyleDeclaration): boolean =>
+    style.textOverflow === "ellipsis" ||
+    (style.getPropertyValue("-webkit-line-clamp") || "none") !== "none";
+  const clipOf = (el: Element): MeasuredElement["clip"] => {
+    let found: MeasuredElement["clip"];
+    for (let at = el.parentElement; at && at !== slide; at = at.parentElement) {
+      const style = getComputedStyle(at);
+      if (style.overflowX === "visible" && style.overflowY === "visible") {
+        continue;
+      }
+      const rect = toBox(at.getBoundingClientRect());
+      found = found
+        ? {
+            ...found,
+            rect: {
+              left: Math.max(found.rect.left, rect.left),
+              top: Math.max(found.rect.top, rect.top),
+              right: Math.min(found.rect.right, rect.right),
+              bottom: Math.min(found.rect.bottom, rect.bottom),
+            },
+            intended: found.intended || truncates(style),
+          }
+        : { box: describe(at), rect, intended: truncates(style) };
+    }
+    return found && { ...found, intended: found.intended || truncates(getComputedStyle(el)) };
+  };
+  const lineBoxes = (textNodes: Node[]): Box[] =>
+    textNodes.flatMap((node) => {
+      const range = document.createRange();
+      range.selectNodeContents(node);
+      return [...range.getClientRects()]
+        .filter((rect) => rect.width > 0 && rect.height > 0)
+        .map(toBox);
+    });
+
+  const all = [...slide.querySelectorAll("*")];
+  const indexOf = new Map(all.map((el, index) => [el, index]));
+  const elements = all.map((el): MeasuredElement => {
+    const style = getComputedStyle(el);
+    const textNodes = [...el.childNodes].filter(
+      (node) => node.nodeType === Node.TEXT_NODE && squash(node.textContent ?? "") !== "",
+    );
+    const own = squash(textNodes.map((node) => node.textContent ?? "").join(" "));
+    // innerText separates block children; textContent would run "item 0item 1" together.
+    // SVG and MathML have no innerText, so they fall back to textContent.
+    const whole = el instanceof HTMLElement ? el.innerText : el.textContent;
+    const text = own || squash(whole ?? "");
+    const parentEl = el.parentElement;
+    return {
+      box: describe(el),
+      parent: parentEl ? (indexOf.get(parentEl) ?? -1) : -1,
+      rect: extent(el, textNodes),
+      ...(text ? { text } : {}),
+      ownText: own !== "",
+      textRects: lineBoxes(textNodes),
+      opacity: opacityOf(el),
+      fontSize: Number.parseFloat(style.fontSize),
+      fontWeight: Number(style.fontWeight) || 400,
+      decorative: el.closest('[aria-hidden="true"]') !== null,
+      picture: pictures.has(el.tagName.toLowerCase()) || style.backgroundImage.includes("url("),
+      paints: paints(style),
+      ...clipped(clipOf(el)),
+    };
+  });
+  // A pseudo-element draws text when its content has a letter or a digit, or comes from a
+  // counter or an attribute. A quote mark or an arrow on its own is ornament, and stays with
+  // the background as a glow or a rule does.
+  const readable = (content: string): boolean =>
+    /\b(?:counters?|attr)\(/.test(content) ||
+    [...content.matchAll(/"((?:[^"\\]|\\.)*)"/g)].some(([, text]) =>
+      /[\p{L}\p{N}]/u.test(text ?? ""),
+    );
+  const pseudoTexts: PseudoText[] = [];
+  for (const [index, el] of [slide, ...all].entries()) {
+    if (el.closest('[aria-hidden="true"]') !== null) {
+      continue;
+    }
+    for (const pseudo of ["before", "after"] as const) {
+      const style = getComputedStyle(el, `::${pseudo}`);
+      const { content } = style;
+      if (content === "none" || content === "normal" || !readable(content)) {
+        continue;
+      }
+      const host = String(index);
+      el.setAttribute("data-dek-text", host);
+      el.setAttribute(`data-dek-text-${pseudo}`, "");
+      const own = Number.parseFloat(style.opacity);
+      pseudoTexts.push({
+        host,
+        pseudo,
+        box: `${describe(el)}::${pseudo}`,
+        // As the audience reads it: the strings without their quotes, a counter as written.
+        text: squash(content.replace(/"((?:[^"\\]|\\.)*)"/g, "$1")),
+        opacity: opacityOf(el) * (Number.isNaN(own) ? 1 : own),
+        fontSize: Number.parseFloat(style.fontSize),
+        fontWeight: Number(style.fontWeight) || 400,
+      });
+    }
+  }
+  return { slideBox: toBox(slide.getBoundingClientRect()), elements, pseudoTexts };
+}
+
+/** Runs in the page: takes away the marks `measureSlideInPage` left for pseudo texts. */
+export function unmarkPseudoTextsInPage(): void {
+  for (const el of document.querySelectorAll("[data-dek-text]")) {
+    for (const name of ["data-dek-text", "data-dek-text-before", "data-dek-text-after"]) {
+      el.removeAttribute(name);
+    }
+  }
+}

package/src/core/slide-script-eval.ts

@@ -0,0 +1,258 @@
+import { escapeRegExp } from "./escape.ts";
+import { moduleFilePath } from "./path.ts";
+import {
+  compileSlideScript,
+  IMPORTS_MESSAGE,
+  lineMatching,
+  type SlideScriptProblem,
+  staticProblems,
+} from "./slide-script.ts";
+import { suggest } from "./suggest.ts";
+
+/** One slide script as lint checks it: its source, and the slide's step keys to check `motion` by. */
+export type ScriptInput = { code: string; steps?: string[] };
+
+/** How long lint waits for every slide script's top-level code, in total. */
+const EVAL_BUDGET_MS = 5000;
+
+/**
+ * What stops each `slides/<slug>.ts` from running as a slide script. A script is one
+ * self-contained module whose only export is the default object. Given the slide's step keys,
+ * the module is also evaluated so `motion` can be checked against the beats it names.
+ * Evaluation happens in one child process that cannot reach dek's globals and is killed if it
+ * hangs; this waits for it. Scripts evaluated before are answered from a cache.
+ */
+export function slideScriptsProblems(scripts: ScriptInput[]): SlideScriptProblem[][] {
+  const { results, pending } = prepareScripts(scripts);
+  const codes = uncached(pending);
+  if (codes.length > 0) {
+    const stdout = Bun.spawnSync(evaluatorCommand(), {
+      ...EVALUATOR_OPTIONS,
+      stdin: Buffer.from(JSON.stringify(codes)),
+      timeout: EVAL_BUDGET_MS,
+    }).stdout.toString();
+    cacheSummaries(codes, parseSummaries(codes.length, stdout));
+  }
+  return finishProblems(results, pending);
+}
+
+/**
+ * `slideScriptsProblems` without blocking the event loop while the scripts run, for the dev
+ * server. The answer is about the code passed in, however the files change in the meantime.
+ */
+export async function evaluateSlideScripts(
+  scripts: ScriptInput[],
+): Promise<SlideScriptProblem[][]> {
+  const { results, pending } = prepareScripts(scripts);
+  const codes = uncached(pending);
+  if (codes.length > 0) {
+    const child = Bun.spawn(evaluatorCommand(), {
+      ...EVALUATOR_OPTIONS,
+      stdin: Buffer.from(JSON.stringify(codes)),
+    });
+    const timer = setTimeout(() => child.kill(), EVAL_BUDGET_MS);
+    try {
+      const stdout = await new Response(child.stdout).text();
+      await child.exited;
+      cacheSummaries(codes, parseSummaries(codes.length, stdout));
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  return finishProblems(results, pending);
+}
+
+/**
+ * A pending evaluation. `withoutImports` marks a script evaluated with its
+ * imports removed, so lint can still check `motion`; what then fails at run
+ * time is the missing import's doing, already reported.
+ */
+type PendingScript = {
+  index: number;
+  /** As written, where a problem the evaluation finds is looked for. */
+  source: string;
+  code: string;
+  steps: string[];
+  withoutImports: boolean;
+};
+
+const IMPORT_RE = /^[ \t]*import\s+(?:type\s+)?(?:[\s\S]*?\sfrom\s*)?["'][^"'\n]+["'][ \t]*;?/gm;
+
+/** The code with its import declarations blanked out, lines kept in place. */
+function withoutImports(code: string): string {
+  return code.replace(IMPORT_RE, (match) => match.replace(/[^\n]/g, " "));
+}
+
+function prepareScripts(scripts: ScriptInput[]): {
+  results: SlideScriptProblem[][];
+  pending: PendingScript[];
+} {
+  const results: SlideScriptProblem[][] = [];
+  const pending: PendingScript[] = [];
+  for (const [index, script] of scripts.entries()) {
+    const problems = staticProblems(script.code);
+    // Imports alone do not stop the rest of the checks: report everything in one run.
+    const importsOnly = problems.length > 0 && problems.every((p) => p.message === IMPORTS_MESSAGE);
+    const source = importsOnly ? withoutImports(script.code) : script.code;
+    const compiled =
+      problems.length > 0 && !importsOnly ? undefined : compileSlideScript(source, "slide");
+    if (compiled && "problem" in compiled) {
+      problems.push(compiled.problem);
+    }
+    results.push(problems);
+    if (compiled && "code" in compiled && script.steps) {
+      pending.push({
+        index,
+        source: script.code,
+        code: compiled.code,
+        steps: script.steps,
+        withoutImports: importsOnly,
+      });
+    }
+  }
+  return { results, pending };
+}
+
+/** The compiled code of each pending script the cache has no summary for, once each. */
+function uncached(pending: PendingScript[]): string[] {
+  return [...new Set(pending.map((entry) => entry.code))].filter((code) => !summaryCache.has(code));
+}
+
+function finishProblems(
+  results: SlideScriptProblem[][],
+  pending: PendingScript[],
+): SlideScriptProblem[][] {
+  for (const entry of pending) {
+    const summary = summaryCache.get(entry.code);
+    const blamedOnImports =
+      entry.withoutImports &&
+      summary !== undefined &&
+      ("threw" in summary || "timedOut" in summary);
+    const found = blamedOnImports ? [] : moduleProblems(summary, entry);
+    results[entry.index] = [...(results[entry.index] ?? []), ...found];
+  }
+  return results;
+}
+
+/** What the evaluator reports for one module; see slide-eval-worker.ts. */
+type ModuleSummary =
+  | { threw: string }
+  | { timedOut: true }
+  | { object: false }
+  | { object: true; draw: string; motion: "none" | "invalid" | Array<[string, number | null]> };
+
+/** Summaries by compiled code; the evaluation depends on nothing else. */
+const summaryCache = new Map<string, ModuleSummary>();
+const SUMMARY_CACHE_LIMIT = 256;
+
+const EVALUATOR_OPTIONS = { stdout: "pipe", stderr: "ignore", env: {} } as const;
+
+function evaluatorCommand(): string[] {
+  const worker = moduleFilePath(new URL("./slide-eval-worker.ts", import.meta.url));
+  return [process.execPath, "--no-install", worker];
+}
+
+/** A worker that was killed still wrote a line for every script it finished. */
+function parseSummaries(count: number, stdout: string): Array<ModuleSummary | undefined> {
+  const lines = stdout.split("\n").filter(Boolean);
+  return Array.from({ length: count }, (_, index) => {
+    const line = lines[index];
+    return line ? (JSON.parse(line) as ModuleSummary) : undefined;
+  });
+}
+
+/** A script left unfinished because the budget ran out is not cached; it is tried again. */
+function cacheSummaries(codes: string[], summaries: Array<ModuleSummary | undefined>): void {
+  for (const [index, code] of codes.entries()) {
+    const summary = summaries[index];
+    if (!summary) {
+      continue;
+    }
+    summaryCache.delete(code);
+    summaryCache.set(code, summary);
+    if (summaryCache.size > SUMMARY_CACHE_LIMIT) {
+      const oldest = summaryCache.keys().next().value;
+      if (oldest !== undefined) {
+        summaryCache.delete(oldest);
+      }
+    }
+  }
+}
+
+const TOP_LEVEL_HINT = "move what touches the page into draw(slide, { t }), which runs per frame";
+
+function moduleProblems(
+  summary: ModuleSummary | undefined,
+  { source, steps }: Pick<PendingScript, "source" | "steps">,
+): SlideScriptProblem[] {
+  if (!summary || "timedOut" in summary) {
+    return [
+      {
+        message: "top-level code did not finish; touch the slide only inside draw",
+        hint: TOP_LEVEL_HINT,
+      },
+    ];
+  }
+  if ("threw" in summary) {
+    return [
+      {
+        message: `top-level code threw: ${summary.threw}; touch the slide only inside draw`,
+        hint: TOP_LEVEL_HINT,
+      },
+    ];
+  }
+  const exported = lineMatching(source, /\bexport\s+default\b/);
+  const at = (line: number | undefined) => (line === undefined ? {} : { line });
+  if (!summary.object) {
+    return [
+      {
+        message: "export default must be an object like { motion, draw }",
+        ...at(exported),
+        hint: "export default { motion: { <step>: ms }, draw(slide, { t }) {} } satisfies DekSlide",
+      },
+    ];
+  }
+  const problems: SlideScriptProblem[] = [];
+  if (summary.draw !== "undefined" && summary.draw !== "function") {
+    problems.push({
+      message: "draw must be a function",
+      ...at(lineMatching(source, /\bdraw\b/) ?? exported),
+      hint: "write it as draw(slide, { index, step, t }) { … }",
+    });
+  }
+  if (summary.motion === "none") {
+    return problems;
+  }
+  if (summary.motion === "invalid") {
+    return [
+      ...problems,
+      {
+        message: "motion must be an object keyed by beat",
+        ...at(lineMatching(source, /\bmotion\b/) ?? exported),
+        hint: `write it as motion: { ${steps[0] ?? "1"}: 600 }, one key per beat that moves`,
+      },
+    ];
+  }
+  for (const [key, ms] of summary.motion) {
+    // The key as the object literal writes it: bare, or quoted either way.
+    const keyLine = lineMatching(
+      source,
+      new RegExp(`(?:^|[\\s{,])(["']?)${escapeRegExp(key)}\\1\\s*:`),
+    );
+    if (!steps.includes(key)) {
+      const guess = suggest(key, steps);
+      problems.push({
+        message: `motion key "${key}" is not a beat of this slide`,
+        ...at(keyLine),
+        hint: `${guess ? `did you mean "${guess}"? ` : ""}use one of: ${steps.join(", ")}`,
+      });
+    } else if (ms === null || ms < 0) {
+      problems.push({
+        message: `motion "${key}" must be a non-negative number of milliseconds`,
+        ...at(keyLine),
+        hint: `give it how long the beat moves, like ${key}: 600`,
+      });
+    }
+  }
+  return problems;
+}