@hajimism/dek 0.1.0

package/src/core/slide-script.ts

@@ -0,0 +1,252 @@
+import { readFileSync } from "node:fs";
+import { DekError } from "./error.ts";
+import { escapeRegExp } from "./escape.ts";
+import { listSlideFiles } from "./resolve.ts";
+import { stillDrawScript } from "./slide-draw.ts";
+
+/** Slide scripts are `slides/<slug>.ts`; plain JavaScript is valid TypeScript. */
+const transpiler = new Bun.Transpiler({ loader: "ts" });
+
+const DEFAULT_EXPORT_RE = /\bexport\s+default\b/;
+/** In transpiled output, comments are gone and each statement starts a line. */
+const EXPORT_DEFAULT_LINE_RE = /^export default\b/gm;
+const DECLARATION_RE =
+  /^export default ((?:async\s+)?function\s*\*?\s*|class\s+)([A-Za-z_$][\w$]*)/;
+
+export type SlideScript = {
+  slug: string;
+  path: string;
+  /** A classic script that registers the slide, safe to put inside `<script>`. */
+  code: string;
+};
+
+/** What stops a slide script from running: where, when the source has a place for it, and the fix. */
+export type SlideScriptProblem = { message: string; line?: number; hint?: string };
+
+export const IMPORTS_MESSAGE = "imports are not supported; keep the slide script self-contained";
+
+/** The 1-based line of the first line `re` matches, if any. */
+export function lineMatching(code: string, re: RegExp): number | undefined {
+  const index = code.split("\n").findIndex((line) => re.test(line));
+  return index < 0 ? undefined : index + 1;
+}
+
+function withLine(problem: SlideScriptProblem, line: number | undefined): SlideScriptProblem {
+  return line === undefined ? problem : { ...problem, line };
+}
+
+/**
+ * What stops a script from being one self-contained module whose only export is the default
+ * object, found without running it.
+ */
+export function staticProblems(code: string): SlideScriptProblem[] {
+  let scan: ReturnType<Bun.Transpiler["scan"]>;
+  try {
+    scan = transpiler.scan(code);
+  } catch (error) {
+    return [syntaxProblem(error)];
+  }
+  const problems: SlideScriptProblem[] = [];
+  if (scan.imports.length > 0) {
+    problems.push(
+      withLine(
+        {
+          message: IMPORTS_MESSAGE,
+          hint: "remove the import and write what it gave in this file; DekSlide is global, from .dek/slide.d.ts",
+        },
+        lineMatching(code, /^\s*import\b/),
+      ),
+    );
+  }
+  for (const name of scan.exports.filter((entry) => entry !== "default")) {
+    problems.push(
+      withLine(
+        {
+          message: `only a default export is allowed; found "${name}"`,
+          hint: `drop export from "${name}", or make it part of the default export`,
+        },
+        lineMatching(
+          code,
+          new RegExp(`^\\s*export\\b(?!\\s+default\\b).*\\b${escapeRegExp(name)}\\b`),
+        ),
+      ),
+    );
+  }
+  if (!scan.exports.includes("default") || !DEFAULT_EXPORT_RE.test(code)) {
+    problems.push({
+      message: "missing export default",
+      hint: "end the script with export default { draw(slide, { t }) {} } satisfies DekSlide",
+    });
+  }
+  return problems;
+}
+
+const SYNTAX_HINT = "fix the syntax there; until the script parses, the slide shows without it";
+
+/**
+ * A syntax error as Bun reports it: one message with its position, or several, of which the first
+ * says the most. "Parse error" alone names neither.
+ */
+function syntaxProblem(error: unknown): SlideScriptProblem {
+  type Located = { message?: string; position?: { line?: number } | null };
+  const first: Located =
+    error instanceof AggregateError && error.errors.length > 0
+      ? (error.errors[0] as Located)
+      : (error as Located);
+  const message = first.message ?? messageOf(error);
+  const line = first.position?.line;
+  return {
+    message: `syntax error: ${message}`,
+    ...(typeof line === "number" && line > 0 ? { line } : {}),
+    hint: SYNTAX_HINT,
+  };
+}
+
+/**
+ * Turns the module into a classic script that registers its default export
+ * as `window.__dekSlides[slug]`, each slide in its own function scope. Of the
+ * lines that start with `export default`, the real one is the only one whose
+ * rewrite parses; a template literal can hold look-alikes, a comment cannot.
+ */
+export function compileSlideScript(
+  code: string,
+  slug: string,
+): { code: string } | { problem: SlideScriptProblem } {
+  let js: string;
+  try {
+    js = transpiler.transformSync(code);
+  } catch (error) {
+    return { problem: syntaxProblem(error) };
+  }
+  let firstError: unknown;
+  for (const match of js.matchAll(EXPORT_DEFAULT_LINE_RE)) {
+    const body = rewriteDefaultExport(js, match.index ?? 0);
+    try {
+      const wrapped = escapeForScriptTag(wrap(body, slug, false));
+      new Function(wrapped);
+      return { code: wrapped };
+    } catch (error) {
+      firstError ??= error;
+      if (parses(wrap(body, slug, true))) {
+        return {
+          problem: withLine(
+            {
+              message:
+                "top-level await is not supported; the slide script must finish when it loads",
+              hint: "drop the await: draw from t alone, with nothing to wait for",
+            },
+            lineMatching(code, /\bawait\b/),
+          ),
+        };
+      }
+    }
+  }
+  return {
+    problem: firstError
+      ? { message: `syntax error: ${messageOf(firstError)}`, hint: SYNTAX_HINT }
+      : { message: "missing export default" },
+  };
+}
+
+/** Keeps a declaration's name bound: `export default function draw` still defines `draw`. */
+function rewriteDefaultExport(js: string, index: number): string {
+  const rest = js.slice(index);
+  const declaration = DECLARATION_RE.exec(rest);
+  if (declaration) {
+    const kept = rest.slice("export default ".length);
+    return `${js.slice(0, index)}${kept}\n__dekDefault = ${declaration[2]};`;
+  }
+  return `${js.slice(0, index)}__dekDefault =${rest.slice("export default".length)}`;
+}
+
+function wrap(body: string, slug: string, async: boolean): string {
+  return `(window.__dekSlides ||= {})[${JSON.stringify(slug)}] = (${async ? "async " : ""}function () {
+"use strict";
+var __dekDefault;
+${body}
+return __dekDefault;
+})();
+`;
+}
+
+function parses(code: string): boolean {
+  try {
+    new Function(code);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `</script` and `<!--` would end or confuse the tag; `<\/` means the same inside JS. */
+function escapeForScriptTag(code: string): string {
+  return code.replace(/<(\/script|!--)/gi, "<\\$1");
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** A slide script as read from disk: compiled, or the problem that stops it. */
+export type SlideScriptEntry =
+  | SlideScript
+  | { slug: string; path: string; problem: SlideScriptProblem };
+
+/** Compiles every `slides/<slug>.ts`, or only `only`'s, without deciding what a problem means. */
+export function loadSlideScripts(deckDir: string, only?: string): SlideScriptEntry[] {
+  return listSlideFiles(deckDir, ".ts")
+    .filter((slide) => only === undefined || slide.slug === only)
+    .map((slide) => {
+      const source = readFileSync(slide.path, "utf8");
+      const problem = staticProblems(source)[0];
+      const compiled = problem ? { problem } : compileSlideScript(source, slide.slug);
+      return { slug: slide.slug, path: slide.path, ...compiled };
+    });
+}
+
+/**
+ * The scripts that can run. A broken one is skipped and left to lint (DEK016),
+ * unless `strict`, where the render refuses to build without it.
+ */
+export function usableSlideScripts(entries: SlideScriptEntry[], strict: boolean): SlideScript[] {
+  return entries.flatMap((entry) => {
+    if (!("problem" in entry)) {
+      return [entry];
+    }
+    if (strict) {
+      throw new DekError(`invalid slide script "${entry.slug}": ${entry.problem.message}`, {
+        path: entry.path,
+        hint: "run `dekc lint`",
+      });
+    }
+    return [];
+  });
+}
+
+/**
+ * The deck's slide scripts, compiled. The dev server skips a broken one and
+ * lets lint report it (DEK016); `strict` renders refuse to build without it.
+ * `only` limits the read to one slide, for pages that show one slide.
+ */
+export function readSlideScripts(
+  deckDir: string,
+  options: { strict?: boolean; only?: string } = {},
+): SlideScript[] {
+  return usableSlideScripts(loadSlideScripts(deckDir, options.only), options.strict ?? false);
+}
+
+/** One tag per slide, so a script that throws while loading cannot stop the others. */
+export function slideScriptTags(scripts: SlideScript[]): string {
+  return scripts
+    .map((script) => `<script data-dek-slides="${script.slug}">${script.code}</script>`)
+    .join("");
+}
+
+/**
+ * What a still page runs: its slides' scripts, then the still script that draws
+ * them and ends every animation. Every still page carries it, since the theme's
+ * own animations need ending even where no slide has a script.
+ */
+export function stillPageScript(scripts: SlideScript[]): string {
+  return `${slideScriptTags(scripts)}<script>${stillDrawScript()}</script>`;
+}

package/src/core/spawn.ts

@@ -0,0 +1,128 @@
+import { DekError } from "./error.ts";
+
+export async function awaitPiped(proc: {
+  stdout: ReadableStream<Uint8Array> | number;
+  stderr: ReadableStream<Uint8Array> | number;
+  exited: Promise<number>;
+}): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout as ReadableStream<Uint8Array>).text(),
+    new Response(proc.stderr as ReadableStream<Uint8Array>).text(),
+    proc.exited,
+  ]);
+  return { stdout, stderr, exitCode };
+}
+
+/** `bin` as a command line: a .ts worker runs under bun, anything else as is. */
+export function workerCommand(bin: string, args: string[] = []): string[] {
+  return bin.endsWith(".ts") ? ["bun", "--no-install", bin, ...args] : [bin, ...args];
+}
+
+/** A browser that hangs must not hang dek; a whole visual run or capture fits well inside this. */
+const DEFAULT_WORKER_TIMEOUT_MS = 10 * 60 * 1000;
+
+type PipedOptions = {
+  /** The error message when the command cannot start or overruns, such as "ffmpeg failed". */
+  label: string;
+  /** The hint when the command cannot start. */
+  hint: string;
+  /** Written to the command's stdin, which is then closed. */
+  stdin?: string;
+  /** Covers the whole run, from spawn to exit. */
+  timeoutMs: number;
+};
+
+type Piped = { stdout: string; stderr: string; exitCode: number };
+
+/**
+ * Runs `cmd` to its exit with its output piped back. A command that cannot start, or runs past
+ * `timeoutMs` and is killed, is a DekError named `label`; any exit code is the caller's to judge.
+ */
+export async function runPiped(cmd: string[], options: PipedOptions): Promise<Piped> {
+  let proc: Bun.Subprocess<"pipe", "pipe", "pipe">;
+  try {
+    proc = Bun.spawn(cmd, { stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+  } catch (error) {
+    throw new DekError(options.label, { hint: options.hint, cause: error });
+  }
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill();
+  }, options.timeoutMs);
+  try {
+    // Read before writing: a command that answers while still reading must not block on a full pipe.
+    const piped = awaitPiped(proc);
+    if (options.stdin !== undefined) {
+      proc.stdin.write(options.stdin);
+    }
+    await proc.stdin.end();
+    const result = await piped;
+    if (timedOut) {
+      throw new DekError(options.label, {
+        hint: `it did not finish within ${Math.round(options.timeoutMs / 1000)}s and was stopped`,
+      });
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof DekError) {
+      throw error;
+    }
+    throw new DekError(options.label, { hint: options.hint, cause: error });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+type JsonWorkerOptions = {
+  /** The error message for any failure, such as "Playwright worker failed". */
+  label: string;
+  /** The hint when the worker gives no reason of its own. */
+  hint: string;
+  /** Covers the whole run, from spawn to exit. */
+  timeoutMs?: number;
+};
+
+/**
+ * Runs a worker that takes one JSON request on stdin and answers with JSON on
+ * stdout. Every failure is a DekError named `label`: a worker that exits
+ * non-zero contributes its stderr as the hint, one that overruns the timeout
+ * is killed and says so, and output `parse` rejects is invalid JSON.
+ */
+export async function runJsonWorker<T>(
+  cmd: string[],
+  request: unknown,
+  parse: (stdout: string) => T | null,
+  options: JsonWorkerOptions,
+): Promise<T> {
+  const { stdout, stderr, exitCode } = await runPiped(cmd, {
+    label: options.label,
+    hint: options.hint,
+    stdin: JSON.stringify(request),
+    timeoutMs: options.timeoutMs ?? DEFAULT_WORKER_TIMEOUT_MS,
+  });
+  if (exitCode !== 0) {
+    throw new DekError(options.label, { hint: stderr.trim().slice(0, 200) || options.hint });
+  }
+  const parsed = parse(stdout);
+  if (parsed === null) {
+    throw new DekError(options.label, { hint: "worker returned invalid JSON" });
+  }
+  return parsed;
+}
+
+/** The worker's side of `runJsonWorker`: its request, or exit 2 with the reason on stderr. */
+export async function readWorkerRequest<T>(): Promise<T> {
+  const text = await new Response(Bun.stdin).text();
+  try {
+    return JSON.parse(text) as T;
+  } catch (error) {
+    return exitWorker(error);
+  }
+}
+
+/** Exits a worker with the reason on stderr, so the parent's hint says what went wrong. */
+export function exitWorker(error: unknown): never {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(2);
+}

package/src/core/step.ts

@@ -0,0 +1,94 @@
+export type BeatRef = {
+  id?: string;
+};
+
+/**
+ * Where the talk stands. `beatIndex` counts the beats reached on the slide: 0 is the slide as it
+ * arrives, with nothing bound to a beat shown yet, and k is its k-th `###`.
+ */
+export type Position = {
+  slideIndex: number;
+  beatIndex: number;
+};
+
+/** How many positions a slide has: its arrival, then one per beat. */
+export function stopCount(beats: BeatRef[]): number {
+  return beats.length + 1;
+}
+
+/** The stop with every beat reached. */
+export function lastStop(beats: BeatRef[]): number {
+  return beats.length;
+}
+
+/** The beat reached last at `beatIndex`; none as the slide arrives. */
+export function beatAt<T extends BeatRef>(beats: T[], beatIndex: number): T | undefined {
+  return beatIndex > 0 ? beats[beatIndex - 1] : undefined;
+}
+
+const STOP_NUMBER_RE = /^(0|[1-9]\d*)$/;
+
+/** The beatIndex a stop token names: `0` to the beat count by position, or a beat id. */
+export function resolveStop(beats: BeatRef[], token: string): number | undefined {
+  if (STOP_NUMBER_RE.test(token)) {
+    const index = Number(token);
+    return index <= lastStop(beats) ? index : undefined;
+  }
+  const found = beats.findIndex((beat) => beat.id === token);
+  return found < 0 ? undefined : found + 1;
+}
+
+/** The beat a `data-step` value names (1-based), by id or position. The arrival is no beat. */
+export function resolveStep(beats: BeatRef[], value: string): number | undefined {
+  const index = resolveStop(beats, value);
+  return index === 0 ? undefined : index;
+}
+
+/** The value `data-step` takes for the beat at `index` (0-based): its id, or its 1-based position. */
+export function beatStep(beats: BeatRef[], index: number): string {
+  return beats[index]?.id ?? String(index + 1);
+}
+
+/** The key `motion` and `draw` use for a position: `"0"` for the arrival, else the beat's step. */
+export function stepKey(beats: BeatRef[], beatIndex: number): string {
+  return beatIndex <= 0 ? "0" : beatStep(beats, beatIndex - 1);
+}
+
+/** Every `stepKey` of a slide, arrival first. */
+export function stepKeys(beats: BeatRef[]): string[] {
+  return Array.from({ length: stopCount(beats) }, (_, index) => stepKey(beats, index));
+}
+
+/** The `data-step` values shown once `beatIndex` beats have been reached. */
+export function stepValuesForBeat(beats: BeatRef[], beatIndex: number): Set<string> {
+  const shown = new Set<string>();
+  for (let i = 0; i < beatIndex && i < beats.length; i++) {
+    shown.add(String(i + 1));
+    const id = beats[i]?.id;
+    if (id) {
+      shown.add(id);
+    }
+  }
+  return shown;
+}
+
+/** The values a step may take on a slide: beat ids, then the position range. Empty without beats. */
+export function stepChoices(beats: BeatRef[]): string[] {
+  if (beats.length === 0) {
+    return [];
+  }
+  return [
+    ...beats.flatMap((beat) => (beat.id ? [beat.id] : [])),
+    beats.length === 1 ? "1" : `1-${beats.length}`,
+  ];
+}
+
+/** "use hook, turn, or 1-2" for a slide with beats. */
+export function formatStepChoices(choices: string[]): string {
+  const head = choices.slice(0, -1);
+  const last = choices[choices.length - 1] ?? "1";
+  if (head.length === 0) {
+    return `use ${last}`;
+  }
+  return head.length === 1 ? `use ${head[0]} or ${last}` : `use ${head.join(", ")}, or ${last}`;
+}

package/src/core/still-page.ts

@@ -0,0 +1,70 @@
+import { type DeckStyles, readDeckStyles } from "./assets.ts";
+import { playerChromeCss } from "./chrome.ts";
+import { type DeckSlides, deckSlides, htmlShell, slidePlace, stampSlide } from "./html.ts";
+import { type ProjectDeck, requireSection } from "./resolve.ts";
+import { logicalSize } from "./size.ts";
+import { SLIDE_CSS_ID } from "./slide-measure.ts";
+import {
+  loadSlideScripts,
+  type SlideScriptEntry,
+  stillPageScript,
+  usableSlideScripts,
+} from "./slide-script.ts";
+import { stepKey, stepValuesForBeat } from "./step.ts";
+
+/** What a run of still pages shares, read once instead of once per page. */
+export type SlideSources = {
+  deck: ProjectDeck;
+  styles: DeckStyles;
+  slides: DeckSlides;
+  scripts: SlideScriptEntry[];
+  /** Whether a broken slide script fails its page (shots) or is skipped (visual lint). */
+  strict: boolean;
+};
+
+export function loadSlideSources(
+  deck: ProjectDeck,
+  options: { strict?: boolean } = {},
+): SlideSources {
+  return {
+    deck,
+    styles: readDeckStyles(deck.dir, false),
+    slides: deckSlides(deck),
+    scripts: loadSlideScripts(deck.dir),
+    strict: options.strict ?? true,
+  };
+}
+
+/**
+ * One slide alone on a page, held at `beatIndex`, as shots and visual lint measure it. Its own
+ * CSS sits in a style element of its own after the theme, and no other slide's comes along.
+ */
+export function renderSlideHtml(sources: SlideSources, slug: string, beatIndex: number): string {
+  const { deck } = sources;
+  const section = requireSection(deck, slug);
+  const { sections } = deck.deck;
+  const slide = stampSlide(sources.slides.section(slug), {
+    slug,
+    place: slidePlace(sections, sections.indexOf(section)),
+    shown: stepValuesForBeat(section.beats, beatIndex),
+    beat: { index: beatIndex, step: stepKey(section.beats, beatIndex) },
+    inline: { deckDir: deck.dir },
+  });
+  const scripts = usableSlideScripts(
+    sources.scripts.filter((entry) => entry.slug === slug),
+    sources.strict,
+  );
+  const own = sources.styles.slides.get(slug);
+  return htmlShell({
+    lang: deck.deck.lang,
+    head: `<style>${playerChromeCss(logicalSize(deck.deck.ratio))}</style>
+  <style>${sources.styles.theme}</style>${
+    own === undefined
+      ? ""
+      : `
+  <style id="${SLIDE_CSS_ID}">${own}</style>`
+  }`,
+    body: `<div id="deck">${slide}</div>
+  ${stillPageScript(scripts)}`,
+  });
+}

package/src/core/suggest.ts

@@ -0,0 +1,33 @@
+/** The candidate within two edits of `word` (transpositions count as one), closest first. */
+export function suggest(word: string, candidates: string[]): string | undefined {
+  let best: { name: string; distance: number } | undefined;
+  for (const name of candidates) {
+    const distance = editDistance(word, name);
+    if (distance <= 2 && (!best || distance < best.distance)) {
+      best = { name, distance };
+    }
+  }
+  return best?.name;
+}
+
+/** Optimal string alignment distance: insertions, deletions, substitutions, adjacent swaps. */
+function editDistance(a: string, b: string): number {
+  const rows = Array.from({ length: a.length + 1 }, (_, i) =>
+    Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
+  );
+  const at = (i: number, j: number): number => rows[i]?.[j] ?? Number.POSITIVE_INFINITY;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let value = Math.min(at(i - 1, j) + 1, at(i, j - 1) + 1, at(i - 1, j - 1) + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        value = Math.min(value, at(i - 2, j - 2) + 1);
+      }
+      const row = rows[i];
+      if (row) {
+        row[j] = value;
+      }
+    }
+  }
+  return at(a.length, b.length);
+}