@hajimism/dek 0.1.0

package/src/core/html.ts

@@ -0,0 +1,234 @@
+import { assetInliner } from "./assets.ts";
+import { deckPaths } from "./deck-paths.ts";
+import { escapeAttr, escapeHtml } from "./escape.ts";
+import { isInside } from "./path.ts";
+import { type ProjectDeck, readDeckFile } from "./resolve.ts";
+import { FALLBACK_LANG, type Section } from "./schema.ts";
+import { deckLayouts, type SkeletonLayouts, skeletonHtml } from "./skeleton.ts";
+
+export function htmlShell(options: {
+  lang?: string;
+  title?: string;
+  head?: string;
+  body: string;
+  bodyAttrs?: string;
+}): string {
+  const lang = escapeAttr(options.lang ?? FALLBACK_LANG);
+  const title =
+    options.title === undefined ? "" : `\n  <title>${escapeHtml(options.title)}</title>`;
+  const head = options.head ? `\n  ${options.head}` : "";
+  return `<!DOCTYPE html>
+<html lang="${lang}">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">${title}${head}
+</head>
+<body${options.bodyAttrs ?? ""}>
+  ${options.body}
+</body>
+</html>
+`;
+}
+
+export function hasSlideClass(className: string | null | undefined): boolean {
+  return (className ?? "").split(/\s+/).some((token) => token.toLowerCase() === "slide");
+}
+
+/**
+ * The first `<section class="slide">`, as written, read by the same parser the lint scan uses: a
+ * slide inside a comment or a `data-class` attribute is not one. A marker goes before its start
+ * tag and after its end tag; where the markers land, less their own length, is where it was
+ * written. A slide that never closes runs to `</body>`, or to the end.
+ */
+export function extractSlideSection(html: string): string | undefined {
+  const mark = uniqueMark(html);
+  let found = false;
+  let closed = false;
+  const marked = rewriteHtml(html, (rewriter) => {
+    rewriter.on("section", {
+      element(el) {
+        if (found || !hasSlideClass(el.getAttribute("class"))) {
+          return;
+        }
+        found = true;
+        el.before(mark, { html: true });
+        el.onEndTag((end) => {
+          closed = true;
+          end.after(mark, { html: true });
+        });
+      },
+    });
+  });
+  if (!found) {
+    return undefined;
+  }
+  const start = marked.indexOf(mark);
+  const slide = closed
+    ? html.slice(start, marked.indexOf(mark, start + mark.length) - mark.length)
+    : undefined;
+  // The parser closes an unclosed slide at the end of its parent, past `</body>`.
+  if (slide !== undefined && /<\/section\s*>$/i.test(slide)) {
+    return slide;
+  }
+  const bodyClose = html.slice(start).search(/<\/body>/i);
+  return bodyClose >= 0 ? html.slice(start, start + bodyClose) : html.slice(start);
+}
+
+/** A deck's slide markup, each file read at most once. */
+export type DeckSlides = {
+  /** Whether `slides/<slug>.html` holds a slide section. */
+  has(slug: string): boolean;
+  /** The slide section as `slides/<slug>.html` writes it, or undefined when it holds none. */
+  written(slug: string): string | undefined;
+  /**
+   * The slide section to show: the written one, or the skeleton `dekc sync` would write when the
+   * file is missing or holds no slide. Lint reports those as DEK001 and DEK007; rendering never
+   * stops on them, because at the venue a deck that shows beats one that does not.
+   */
+  section(slug: string): string;
+};
+
+export function deckSlides(deck: ProjectDeck): DeckSlides {
+  const paths = deckPaths(deck.dir);
+  const read = new Map<string, string | undefined>();
+  let layouts: SkeletonLayouts | undefined;
+  const skeleton = (slug: string): string | undefined => {
+    layouts ??= deckLayouts(deck.dir);
+    return skeletonHtml(deck.deck, slug, layouts);
+  };
+  const written = (slug: string): string | undefined => {
+    if (!read.has(slug)) {
+      const path = paths.slide(slug, ".html");
+      // A slug from a URL may try to climb out of slides/.
+      const source =
+        isSafeSlideSlug(slug) && isInside(path, paths.slides)
+          ? readDeckFile(deck.dir, path)
+          : undefined;
+      read.set(slug, source === undefined ? undefined : extractSlideSection(source));
+    }
+    return read.get(slug);
+  };
+  return {
+    has: (slug) => written(slug) !== undefined,
+    written,
+    section: (slug) => written(slug) ?? extractSlideSection(skeleton(slug) ?? "") ?? "",
+  };
+}
+
+function isSafeSlideSlug(slug: string): boolean {
+  return slug.length > 0 && !slug.includes("/") && !slug.includes("\\") && !slug.includes("\0");
+}
+
+/**
+ * Where the script puts a slide: its 1-based number and how many slides the deck has. Every
+ * page shows it the same, so a theme can print a folio that follows the script's order.
+ */
+export type SlidePlace = { number: number; count: number };
+
+/** The place of the script's `index`-th section. */
+export function slidePlace(sections: readonly Section[], index: number): SlidePlace {
+  return { number: index + 1, count: sections.length };
+}
+
+/** What a slide's section carries on a page; everything but the slug and place is for still pages. */
+export type SlideStamp = {
+  slug: string;
+  place: SlidePlace;
+  /** The `data-step` values shown; the slide is the current one, as the player would mark it. */
+  shown?: Set<string>;
+  /** The beat a still page shows, for its `stillDrawScript`. */
+  beat?: { index: number; step: string };
+  /** Inline the deck's files as data: URIs, for a page that stands alone. */
+  inline?: { deckDir: string };
+};
+
+/**
+ * One slide section with what the page needs on it, in one parser pass: its `data-slug` unless
+ * it names its own, its place as `--dek-slide-number` and `--dek-slide-count`, and for a still
+ * page the classes and beat the player would have set.
+ */
+export function stampSlide(html: string, stamp: SlideStamp): string {
+  let done = false;
+  return rewriteHtml(html, (rewriter) => {
+    rewriter.on("section", {
+      element(el) {
+        if (done || !hasSlideClass(el.getAttribute("class"))) {
+          return;
+        }
+        done = true;
+        if (el.getAttribute("data-slug") === null) {
+          el.setAttribute("data-slug", stamp.slug);
+        }
+        // Ahead of the author's own style, so a slide can still set its own.
+        const place = `--dek-slide-number: ${stamp.place.number}; --dek-slide-count: ${stamp.place.count}`;
+        const own = el.getAttribute("style")?.trim();
+        el.setAttribute("style", own ? `${place}; ${own}` : place);
+        if (stamp.shown) {
+          addClass(el, "is-current");
+        }
+        if (stamp.beat) {
+          el.setAttribute("data-dek-beat", String(stamp.beat.index));
+          el.setAttribute("data-dek-step", stamp.beat.step);
+        }
+      },
+    });
+    const { shown } = stamp;
+    if (shown) {
+      rewriter.on("[data-step]", {
+        element(el) {
+          const step = el.getAttribute("data-step");
+          if (step !== null && shown.has(step)) {
+            addClass(el, "is-shown");
+          }
+        },
+      });
+    }
+    if (stamp.inline) {
+      rewriter.on("*", assetInliner(stamp.inline.deckDir));
+    }
+  });
+}
+
+/** Every slide of the deck in script order, as the player pages hold them. */
+export function collectSlidesHtml(deck: ProjectDeck, options: { inline: boolean }): string {
+  const slides = deckSlides(deck);
+  const { sections } = deck.deck;
+  return sections
+    .map((section, index) =>
+      stampSlide(slides.section(section.slug), {
+        slug: section.slug,
+        place: slidePlace(sections, index),
+        ...(options.inline ? { inline: { deckDir: deck.dir } } : {}),
+      }),
+    )
+    .join("");
+}
+
+function addClass(el: HTMLRewriterTypes.Element, className: string): void {
+  const current = el.getAttribute("class");
+  const tokens = current ? current.split(/\s+/).filter(Boolean) : [];
+  if (tokens.includes(className)) {
+    return;
+  }
+  tokens.push(className);
+  el.setAttribute("class", tokens.join(" "));
+}
+
+function rewriteHtml(html: string, configure: (rewriter: HTMLRewriter) => void): string {
+  const rewriter = new HTMLRewriter();
+  configure(rewriter);
+  const output = rewriter.transform(html);
+  if (typeof output !== "string") {
+    throw new Error("HTMLRewriter.transform expected a string");
+  }
+  return output;
+}
+
+/** A marker the file does not contain, so splitting on it finds only the ones inserted. */
+export function uniqueMark(html: string): string {
+  let mark = "\u{F8FF}";
+  while (html.includes(mark)) {
+    mark += "\u{F8FF}";
+  }
+  return mark;
+}

package/src/core/in-page-go.ts

@@ -0,0 +1,128 @@
+import type { Position } from "./step.ts";
+
+/** The part of a Playwright page these in-page functions are shipped through. */
+export type EvaluatingPage = {
+  evaluate<T, A>(fn: (arg: A) => T | Promise<T>, arg?: A): Promise<T>;
+};
+
+/**
+ * Runs in the page, shipped by `page.evaluate`, so it references nothing outside itself.
+ * Every animation `go` started runs on one clock, so all of them stop at the same moment:
+ * `at` of the view transition's span, the longest end among its pseudo-elements (or among
+ * every animation, when the transition animates nothing). A short fade is then over at
+ * `at` of a long morph, as it is when the talk plays.
+ */
+export function freezeAt(at: number): void {
+  const animations = window.__dekStarted ?? document.getAnimations();
+  const endOf = (animation: Animation): number => {
+    const end = animation.effect?.getComputedTiming().endTime;
+    return typeof end === "number" && Number.isFinite(end) ? end : 0;
+  };
+  const isTransition = (animation: Animation): boolean => {
+    const effect = animation.effect as { pseudoElement?: string | null } | null;
+    return (effect?.pseudoElement ?? "").startsWith("::view-transition");
+  };
+  const transition = animations.filter(isTransition);
+  const span = Math.max(0, ...(transition.length > 0 ? transition : animations).map(endOf));
+  const moment = at * span;
+  for (const animation of animations) {
+    animation.pause();
+    animation.currentTime = moment;
+  }
+  // The script started with the same go, so it is as many ms in as the morph.
+  window.dekMotion?.seek(moment);
+}
+
+/**
+ * Runs in the page, shipped by `page.evaluate`, so it references nothing outside itself.
+ * Pauses the animations the last `startGoPaused` began, and returns how long they run: the
+ * longest finite end among them, or the slide script's motion when that is longer. An animation
+ * that repeats forever has no end and adds nothing. With no go recorded, every animation on the
+ * page counts, as on a page that has just loaded.
+ */
+export function holdStarted(): number {
+  const started = window.__dekStarted ?? document.getAnimations();
+  let span = window.dekMotion?.duration() ?? 0;
+  for (const animation of started) {
+    animation.pause();
+    const end = animation.effect?.getComputedTiming().endTime;
+    if (typeof end === "number" && Number.isFinite(end)) {
+      span = Math.max(span, end);
+    }
+  }
+  return span;
+}
+
+/**
+ * Runs in the page, shipped by `page.evaluate`, so it references nothing outside itself.
+ * Seeks the animations the last go began, and the slide script, to `ms` into that go. Nothing
+ * older moves: a finished animation still answers `getAnimations()`, and seeking it would play
+ * an earlier beat again.
+ */
+export function seekStarted(ms: number): void {
+  for (const animation of window.__dekStarted ?? document.getAnimations()) {
+    animation.currentTime = ms;
+  }
+  window.dekMotion?.seek(ms);
+}
+
+/**
+ * Runs in the page, shipped by `page.evaluate`, so it references nothing
+ * outside itself. Starts the player's `go(position)`, keeps it unawaited on
+ * `window.__dekPendingGo`, and resolves once the view transition it opened
+ * is ready to seek (true), or after one frame when it opened none or the
+ * browser skipped it (false),
+ * and every animation the go began has started.
+ * `startViewTransition` is wrapped only to get hold of the transition and is
+ * put back before this returns; the runtime is not modified.
+ */
+export async function startGoPaused(position: Position): Promise<boolean> {
+  const go = window.dekGo;
+  if (!go) {
+    return false;
+  }
+  // Older engines have no view transitions, whatever lib.dom says.
+  const unwrapped = document.startViewTransition as typeof document.startViewTransition | undefined;
+  const original = unwrapped?.bind(document);
+  let captured: ViewTransition | undefined;
+  let pending: Promise<void>;
+  // Whatever the last finished beat left belongs to it; on a page that has just loaded, nothing
+  // does, so the first slide's entrance counts as this go's.
+  const settled = window.__dekSettled;
+  try {
+    if (original) {
+      const wrapped: typeof document.startViewTransition = (update) => {
+        captured = original(update);
+        return captured;
+      };
+      document.startViewTransition = wrapped;
+    }
+    pending = go(position);
+  } finally {
+    if (unwrapped) {
+      document.startViewTransition = unwrapped;
+    }
+  }
+  window.__dekPendingGo = pending;
+  void pending.catch(() => undefined);
+  // A transition the browser skips, as it does for a duplicate name, still runs its update;
+  // the talk carries on without the animation, and so does this, as a go that opened none.
+  const transitioned = captured
+    ? await captured.ready.then(
+        () => true,
+        () => false,
+      )
+    : false;
+  if (captured && !transitioned) {
+    await captured.updateCallbackDone.catch(() => undefined);
+  }
+  if (!transitioned) {
+    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+  }
+  const started = document.getAnimations().filter((animation) => !settled?.has(animation));
+  window.__dekStarted = started;
+  // A pending animation may already run a frame ahead on the compositor while its main-thread
+  // time still reads 0, where a seek to 0 changes nothing. Once started, the two agree.
+  await Promise.allSettled(started.map((animation) => animation.ready));
+  return transitioned;
+}

package/src/core/lines.ts

@@ -0,0 +1,43 @@
+export function splitLines(source: string): string[] {
+  return source.split(/\r?\n/);
+}
+
+export function joinLines(source: string, lines: string[]): string {
+  const newline = source.includes("\r\n") ? "\r\n" : "\n";
+  return lines.join(newline);
+}
+
+/**
+ * The lines of each section, as script.md has them: from its heading up to the next section's,
+ * the last one to the end. `lines` is the whole file and `starts` the 1-based heading lines, in
+ * order.
+ */
+export function sectionChunks(lines: string[], starts: number[]): string[][] {
+  return starts.map((start, index) =>
+    lines.slice(start - 1, (starts[index + 1] ?? lines.length + 1) - 1),
+  );
+}
+
+/** Where an offset into a source is written: 1-based line, and 1-based column in UTF-16 units. */
+export type LineColumn = { line: number; column: number };
+
+/** Turns offsets into `source` into lines and columns, from one pass over its newlines. */
+export function lineLocator(source: string): (offset: number) => LineColumn {
+  const starts = [0];
+  for (let index = source.indexOf("\n"); index !== -1; index = source.indexOf("\n", index + 1)) {
+    starts.push(index + 1);
+  }
+  return (offset) => {
+    let low = 0;
+    let high = starts.length - 1;
+    while (low < high) {
+      const mid = (low + high + 1) >> 1;
+      if ((starts[mid] ?? 0) <= offset) {
+        low = mid;
+      } else {
+        high = mid - 1;
+      }
+    }
+    return { line: low + 1, column: offset - (starts[low] ?? 0) + 1 };
+  };
+}

package/src/core/lint/asset-refs.ts

@@ -0,0 +1,109 @@
+import { existsSync } from "node:fs";
+import { dirname, join, posix, resolve } from "node:path";
+import { classifyAssetRef, isCanonicalAssetPath } from "../assets.ts";
+import { type Diagnostic, diag } from "../diagnostic.ts";
+import type { HtmlRef } from "../html-scan.ts";
+import { isInside } from "../path.ts";
+
+/**
+ * DEK020 to DEK023 for one reference, whether it comes from a slide's markup
+ * or a stylesheet's `url()`. A resource the page loads must exist and be written
+ * as `assets/...`; a link must only stay local and inside the deck.
+ */
+export function assetRefDiagnostics(
+  ref: Pick<HtmlRef, "value" | "use"> & { tag?: string },
+  where: { path: string; line?: number; column?: number; slug?: string; deckDir: string },
+): Diagnostic[] {
+  const { deckDir, ...location } = where;
+  const from = dirname(where.path);
+  const classified = classifyAssetRef(ref.value, { deckDir, from }).kind;
+  // A link someone follows, `<a>` or `<area>`, leaves from wherever the slide is read, the deck
+  // or its slides/, and must stay in the deck from both. A resource is found from either, and a
+  // full document's `<link>` sits in the head the deck never shows.
+  const followed = ref.use === "link" && ref.tag !== "link";
+  const kind =
+    followed &&
+    (classified === "missing" || classified === "file") &&
+    leavesFromEither(ref.value, deckDir, from)
+      ? "escape"
+      : classified;
+  if (kind === "skip") {
+    return [];
+  }
+  if (kind === "remote") {
+    return [
+      diag("DEK020", {
+        message: `remote URL "${ref.value}"`,
+        ...location,
+        hint: remoteHint(ref.value),
+        data: { url: ref.value },
+      }),
+    ];
+  }
+  if (kind === "escape") {
+    return [
+      diag("DEK022", {
+        message: `path "${ref.value}" is outside the deck directory`,
+        ...location,
+        data: { path: ref.value },
+      }),
+    ];
+  }
+  if (ref.use === "link") {
+    return [];
+  }
+  if (kind === "missing") {
+    return [
+      diag("DEK021", {
+        message: `missing ${ref.tag === "img" ? "image" : "file"} "${ref.value}"`,
+        ...location,
+        ...missingImageHint(ref.value, deckDir),
+        data: { src: ref.value },
+      }),
+    ];
+  }
+  if (!isCanonicalAssetPath(ref.value)) {
+    return [
+      diag("DEK023", {
+        message: `asset "${ref.value}" must be referenced as assets/${posix.basename(ref.value.trim())}`,
+        ...location,
+        data: { src: ref.value },
+      }),
+    ];
+  }
+  return [];
+}
+
+function leavesFromEither(value: string, deckDir: string, from: string): boolean {
+  const path = value.trim().split(/[?#]/)[0] ?? "";
+  return (
+    path !== "" &&
+    [resolve(deckDir, path), resolve(from, path)].some((target) => !isInside(target, deckDir))
+  );
+}
+
+/**
+ * Decks copy what they use from the project's `assets/` (so a deck stays whole when moved);
+ * when the project has the file, the fix is that copy.
+ */
+function missingImageHint(value: string, deckDir: string): { hint?: string } {
+  const name = value.trim().split(/[?#]/)[0] ?? "";
+  if (!name.startsWith("assets/")) {
+    return {};
+  }
+  const projectFile = join(dirname(dirname(deckDir)), name);
+  if (!existsSync(projectFile)) {
+    return {};
+  }
+  return { hint: `the project has it: copy ../../${name} into the deck's assets/` };
+}
+
+function remoteHint(value: string): string {
+  let name = "";
+  try {
+    name = posix.basename(new URL(value.trim(), "https://dek.invalid").pathname);
+  } catch {}
+  return name
+    ? `download it into assets/ and use assets/${name}`
+    : "download it into assets/ and reference it from there";
+}

package/src/core/lint/context.ts

@@ -0,0 +1,116 @@
+import { type DekConfig, loadConfig } from "../config.ts";
+import { cssLayoutNames, parseCss, type Stylesheet } from "../css.ts";
+import { deckPaths } from "../deck-paths.ts";
+import type { Diagnostic } from "../diagnostic.ts";
+import { type HtmlScan, scanSlideHtml } from "../html-scan.ts";
+import { type ScriptParts, splitFrontmatter } from "../parse.ts";
+import {
+  listSlideFiles,
+  listSlides,
+  type Project,
+  type ProjectDeck,
+  readDeckFile,
+} from "../resolve.ts";
+import type { Section } from "../schema.ts";
+import { skeletonHtml } from "../skeleton.ts";
+import { type ThemeFacts, themeFacts } from "../theme-facts.ts";
+
+type SlideFile = { slug: string; path: string };
+
+type SlideSource = { html: string; scan: HtmlScan; skeleton: boolean };
+
+/**
+ * What every rule reads: the deck, its config, and the files beside script.md. Rules see every
+ * slide; `lintDeck` narrows their findings to one slide when asked.
+ */
+export type LintContext = DeckFiles & {
+  /** DEK016 and DEK017 of each slide script, by slug: evaluated before the rules run. */
+  scripts: Map<string, Diagnostic[]>;
+};
+
+/** The deck as read from disk, each file once. */
+export type DeckFiles = {
+  project: Project;
+  deck: ProjectDeck;
+  config: DekConfig;
+  /** script.md, read once and cut at its frontmatter; none when it cannot be cut. */
+  script?: ScriptParts;
+  /** The first section of each slug, in script order; a second one is DEK004. */
+  sectionsBySlug: Map<string, Section>;
+  slidesBySlug: Map<string, SlideFile>;
+  stylesBySlug: Map<string, SlideFile>;
+  /** theme.css, parsed once for every rule that reads it. */
+  theme?: ThemeFacts & { path: string; sheet: Stylesheet };
+  /** A slide's HTML, read and scanned once, and whether it is still the skeleton `dekc sync` wrote. */
+  slideSource(slug: string): SlideSource | undefined;
+  /** A slide's own stylesheet, read and parsed once for every rule that reads it. */
+  slideStyle(slug: string): { path: string; sheet: Stylesheet } | undefined;
+};
+
+export function readDeckFiles(project: Project, deck: ProjectDeck): DeckFiles {
+  const themePath = deckPaths(deck.dir).theme;
+  const themeCss = readDeckFile(deck.dir, themePath);
+  const sectionsBySlug = new Map<string, Section>();
+  for (const section of deck.deck.sections) {
+    if (!sectionsBySlug.has(section.slug)) {
+      sectionsBySlug.set(section.slug, section);
+    }
+  }
+  const slidesBySlug = new Map(listSlides(deck.dir).map((slide) => [slide.slug, slide]));
+  const sources = new Map<string, SlideSource | undefined>();
+  const stylesBySlug = new Map(listSlideFiles(deck.dir, ".css").map((file) => [file.slug, file]));
+  const styles = new Map<string, { path: string; sheet: Stylesheet } | undefined>();
+  const sheet = themeCss === undefined ? undefined : parseCss(themeCss);
+  const layouts = sheet === undefined ? new Set<string>() : cssLayoutNames(sheet);
+  const script = scriptParts(deck);
+  return {
+    project,
+    deck,
+    config: loadConfig(project.configPath),
+    ...(script ? { script } : {}),
+    sectionsBySlug,
+    slidesBySlug,
+    stylesBySlug,
+    ...(sheet === undefined
+      ? {}
+      : {
+          theme: { path: themePath, sheet, ...themeFacts(sheet) },
+        }),
+    slideSource(slug) {
+      if (!sources.has(slug)) {
+        const slide = slidesBySlug.get(slug);
+        const html = slide && readDeckFile(deck.dir, slide.path);
+        sources.set(
+          slug,
+          html === undefined
+            ? undefined
+            : {
+                html,
+                scan: scanSlideHtml(html),
+                skeleton: html === skeletonHtml(deck.deck, slug, layouts),
+              },
+        );
+      }
+      return sources.get(slug);
+    },
+    slideStyle(slug) {
+      if (!styles.has(slug)) {
+        const style = stylesBySlug.get(slug);
+        const css = style && readDeckFile(deck.dir, style.path);
+        styles.set(
+          slug,
+          style && css !== undefined ? { path: style.path, sheet: parseCss(css) } : undefined,
+        );
+      }
+      return styles.get(slug);
+    },
+  };
+}
+
+function scriptParts(deck: ProjectDeck): ScriptParts | undefined {
+  try {
+    return splitFrontmatter(readDeckFile(deck.dir, deck.scriptPath) ?? "", deck.scriptPath);
+  } catch {
+    return undefined;
+  }
+}