@hajimism/dek 0.1.0

package/src/core/fill.ts

@@ -0,0 +1,100 @@
+import type { Box, MeasuredElement } from "./slide-measure.ts";
+
+/**
+ * How much of the frame a slide fills, and where: what an agent otherwise opens a screenshot to
+ * see, as numbers. What fills a slide is what the audience reads or looks at: each text's lines,
+ * each picture's box, and each painted box that holds nothing, as a chart's bar or a swatch is. A
+ * painted box that holds something, a card or a window, is as full as what it holds, so one whose
+ * words sit in its top half leaves the rest empty. Decoration counts like the rest: aria-hidden
+ * tells lint and screen readers to pass it by, and the audience still sees it take its place.
+ * Text a pseudo-element draws fills nothing (a folio sits in a corner of every slide), nor does
+ * anything the beat has not shown yet. Every share is of the frame, from 0 to 1, to two places.
+ */
+export type Fill = {
+  /** The share of the frame the content covers, overlaps counted once. */
+  coverage: number;
+  /** The smallest box holding all of it, as shares of the frame's width and height. */
+  box?: Box;
+  /** The share of each tenth of the frame, top to bottom, the content covers. */
+  rows: number[];
+  /** The same, left to right. */
+  columns: number[];
+};
+
+const BANDS = 10;
+
+const share = (part: number, whole: number): number =>
+  whole > 0 ? Math.round((part / whole) * 100) / 100 : 0;
+
+export function measureFill(frame: Box, elements: MeasuredElement[]): Fill {
+  const width = Math.max(0, Math.round(frame.right - frame.left));
+  const height = Math.max(0, Math.round(frame.bottom - frame.top));
+  // One cell a pixel, so what overlaps is counted once.
+  const covered = new Uint8Array(width * height);
+  let extent: Box | undefined;
+  const holding = new Set(elements.map((element) => element.parent));
+  for (const [index, element] of elements.entries()) {
+    if (element.opacity <= 0) {
+      continue;
+    }
+    const seen = element.clip?.rect;
+    const mark = element.picture || (element.paints && !holding.has(index));
+    for (const rect of [...(mark ? [element.rect] : []), ...element.textRects]) {
+      const left = Math.max(rect.left, frame.left, seen?.left ?? -Infinity);
+      const top = Math.max(rect.top, frame.top, seen?.top ?? -Infinity);
+      const right = Math.min(rect.right, frame.right, seen?.right ?? Infinity);
+      const bottom = Math.min(rect.bottom, frame.bottom, seen?.bottom ?? Infinity);
+      if (right <= left || bottom <= top) {
+        continue;
+      }
+      extent = extent
+        ? {
+            left: Math.min(extent.left, left),
+            top: Math.min(extent.top, top),
+            right: Math.max(extent.right, right),
+            bottom: Math.max(extent.bottom, bottom),
+          }
+        : { left, top, right, bottom };
+      const [x0, x1] = [Math.round(left - frame.left), Math.round(right - frame.left)];
+      const [y0, y1] = [Math.round(top - frame.top), Math.round(bottom - frame.top)];
+      for (let y = y0; y < y1; y++) {
+        covered.fill(1, y * width + x0, y * width + x1);
+      }
+    }
+  }
+  const rows = new Array<number>(height).fill(0);
+  const columns = new Array<number>(width).fill(0);
+  let total = 0;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      if (covered[y * width + x]) {
+        rows[y] = (rows[y] ?? 0) + 1;
+        columns[x] = (columns[x] ?? 0) + 1;
+        total++;
+      }
+    }
+  }
+  /** Each tenth of `lines`, as the share of it `across` cells deep that is covered. */
+  const bands = (lines: number[], across: number): number[] =>
+    Array.from({ length: BANDS }, (_, band) => {
+      const from = Math.round((band * lines.length) / BANDS);
+      const to = Math.round(((band + 1) * lines.length) / BANDS);
+      const sum = lines.slice(from, to).reduce((a, b) => a + b, 0);
+      return share(sum, (to - from) * across);
+    });
+  return {
+    coverage: share(total, width * height),
+    ...(extent
+      ? {
+          box: {
+            left: share(extent.left - frame.left, width),
+            top: share(extent.top - frame.top, height),
+            right: share(extent.right - frame.left, width),
+            bottom: share(extent.bottom - frame.top, height),
+          },
+        }
+      : {}),
+    rows: bands(rows, width),
+    columns: bands(columns, height),
+  };
+}

package/src/core/finish-beat.ts

@@ -0,0 +1,30 @@
+/**
+ * Brings the page to the end of the beat it shows, the way a still of that beat
+ * looks: every animation run to its end, the view transition over, and the slide
+ * script drawn at the end of its motion. An animation that repeats forever has no
+ * end, so it is held at its first frame instead, and every still of it agrees.
+ *
+ * Runs in the page, shipped by `page.evaluate` or embedded as source in still
+ * pages, so it references nothing outside itself.
+ */
+export function finishBeat(): void {
+  // A paused animation seeked past its own end has no effect, so `getAnimations()` leaves it
+  // out, yet it never finishes: the go that started it would wait on it forever.
+  const held = (window.__dekStarted ?? []).filter((animation) => animation.playState === "paused");
+  for (const animation of new Set([...document.getAnimations(), ...held])) {
+    const end = animation.effect?.getComputedTiming().endTime;
+    if (typeof end === "number" && Number.isFinite(end)) {
+      animation.finish();
+    } else {
+      animation.pause();
+      animation.currentTime = 0;
+    }
+  }
+  // Chromium never reports the end of a transition whose animations were paused and
+  // seeked, even once they finish; its animations are over, so the transition is too.
+  document.activeViewTransition?.skipTransition();
+  const motion = window.dekMotion;
+  motion?.seek(motion.duration());
+  // What the next go finds already here is this beat's, and seeking that go leaves it alone.
+  window.__dekSettled = new Set(document.getAnimations());
+}

package/src/core/github.ts

@@ -0,0 +1,234 @@
+import { DekError } from "./error.ts";
+
+/**
+ * The two GitHub calls dekc ref needs: pin a rev to a commit, and download
+ * that commit. DEK_GITHUB_API points them elsewhere, the way DEK_VOICE_URL
+ * does for the voice engine.
+ */
+const DEFAULT_API = "https://api.github.com";
+
+/** A repository tarball larger than this is refused rather than held in memory. */
+const MAX_TARBALL_BYTES = 200 * 1024 * 1024;
+
+/** A commit lookup is one small answer; a stall this long is a dead connection. */
+const COMMIT_TIMEOUT_MS = 30 * 1000;
+
+/** A tarball near the size cap on a slow line still fits well inside this. */
+const TARBALL_TIMEOUT_MS = 10 * 60 * 1000;
+
+const SIGN_IN_HINT =
+  "if the repository is private, set GITHUB_TOKEN or run `gh auth login`, then run the command again";
+
+export type GithubOptions = {
+  /** Covers the whole call, from connecting to the last byte of the body. */
+  timeoutMs?: number;
+};
+
+export type TarballOptions = GithubOptions & {
+  maxBytes?: number;
+};
+
+function apiBase(): string {
+  return (process.env.DEK_GITHUB_API ?? DEFAULT_API).replace(/\/+$/, "");
+}
+
+/** GITHUB_TOKEN, else what `gh auth token` prints, else nothing: public repositories need no token. */
+function token(): string | undefined {
+  const fromEnv = process.env.GITHUB_TOKEN?.trim();
+  if (fromEnv) {
+    return fromEnv;
+  }
+  try {
+    const result = Bun.spawnSync([process.env.DEK_GH ?? "gh", "auth", "token"], {
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const printed = result.exitCode === 0 ? result.stdout.toString().trim() : "";
+    return printed || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * One call's deadline. `signal` goes to fetch and fires on the timeout or on
+ * `abort`, which is how a download is dropped: cancelling the body reader
+ * alone leaves the connection open. `timeout` tells the two apart.
+ */
+type Deadline = {
+  signal: AbortSignal;
+  timeout: AbortSignal;
+  abort: () => void;
+  expired: () => DekError;
+};
+
+function deadline(what: string, timeoutMs: number): Deadline {
+  const controller = new AbortController();
+  const timeout = AbortSignal.timeout(timeoutMs);
+  return {
+    signal: AbortSignal.any([controller.signal, timeout]),
+    timeout,
+    abort: () => controller.abort(),
+    expired: () =>
+      new DekError(`GitHub timed out after ${timeoutMs / 1000}s while fetching ${what}`, {
+        hint: "check the network and run the command again; GitHub may also be slow, see https://www.githubstatus.com",
+      }),
+  };
+}
+
+function rateLimitHint(retryAfter: string | null): string {
+  const wait = retryAfter ? `wait ${retryAfter}s, and ` : "";
+  return `${wait}set GITHUB_TOKEN or run \`gh auth login\` to raise the limit, then run the command again`;
+}
+
+async function request(
+  path: string,
+  what: string,
+  accept: string,
+  { signal, timeout, expired }: Deadline,
+): Promise<Response> {
+  const auth = token();
+  let response: Response;
+  try {
+    response = await fetch(`${apiBase()}${path}`, {
+      headers: {
+        accept,
+        "user-agent": "dek",
+        ...(auth ? { authorization: `Bearer ${auth}` } : {}),
+      },
+      redirect: "follow",
+      signal,
+    });
+  } catch (error) {
+    if (timeout.aborted) {
+      throw expired();
+    }
+    throw new DekError(`could not reach GitHub for ${what}`, {
+      cause: error,
+      hint: "check the network; an agent sandbox may block it, so run the command yourself",
+    });
+  }
+  if (response.ok) {
+    return response;
+  }
+  if (response.status === 404) {
+    throw new DekError(`${what} not found on GitHub`, { hint: SIGN_IN_HINT });
+  }
+  const retryAfter = response.headers.get("retry-after");
+  if (
+    (response.status === 403 || response.status === 429) &&
+    (retryAfter !== null || response.headers.get("x-ratelimit-remaining") === "0")
+  ) {
+    throw new DekError(`GitHub rate limit reached while fetching ${what}`, {
+      hint: rateLimitHint(retryAfter),
+    });
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new DekError(`GitHub refused access to ${what} (${response.status})`, {
+      hint: SIGN_IN_HINT,
+    });
+  }
+  throw new DekError(`GitHub answered ${response.status} for ${what}`, {
+    hint: "run the command again; if it keeps failing, check https://www.githubstatus.com",
+  });
+}
+
+/** The full sha a rev names; the default branch when `rev` is omitted. */
+export async function resolveRev(
+  owner: string,
+  repo: string,
+  rev?: string,
+  options: GithubOptions = {},
+): Promise<string> {
+  const what = `${owner}/${repo}${rev ? `@${rev}` : ""}`;
+  const response = await request(
+    `/repos/${owner}/${repo}/commits/${encodeURIComponent(rev ?? "HEAD")}`,
+    what,
+    "application/vnd.github.sha",
+    deadline(what, options.timeoutMs ?? COMMIT_TIMEOUT_MS),
+  );
+  const sha = (await response.text()).trim();
+  if (!/^[0-9a-f]{40}$/.test(sha)) {
+    throw new DekError(`GitHub did not return a commit for ${what}`, {
+      hint: "run the command again",
+    });
+  }
+  return sha;
+}
+
+/** The repository at one commit, as a gzipped tarball. */
+export async function downloadTarball(
+  owner: string,
+  repo: string,
+  sha: string,
+  options: TarballOptions = {},
+): Promise<Uint8Array> {
+  const what = `${owner}/${repo}@${sha.slice(0, 7)}`;
+  const maxBytes = options.maxBytes ?? MAX_TARBALL_BYTES;
+  const limit = deadline(what, options.timeoutMs ?? TARBALL_TIMEOUT_MS);
+  const response = await request(`/repos/${owner}/${repo}/tarball/${sha}`, what, "*/*", limit);
+  const tooLarge = new DekError(`${what} is larger than ${maxBytes / 1024 / 1024} MB`, {
+    hint: "dekc ref downloads the whole repository; keep decks in a smaller repository",
+  });
+  if (Number(response.headers.get("content-length") ?? 0) > maxBytes) {
+    throw tooLarge;
+  }
+  return readBody(response, maxBytes, tooLarge, limit);
+}
+
+/**
+ * The body, chunk by chunk, giving up as soon as it passes `maxBytes`:
+ * codeload answers chunked, so the content-length check above rarely applies.
+ * The fetch signal does not wake a read in progress, so the timeout also
+ * cancels the reader.
+ */
+async function readBody(
+  response: Response,
+  maxBytes: number,
+  tooLarge: DekError,
+  { timeout, abort, expired }: Deadline,
+): Promise<Uint8Array> {
+  if (!response.body) {
+    return new Uint8Array(0);
+  }
+  const reader = response.body.getReader();
+  const cancel = () => void reader.cancel().catch(() => {});
+  timeout.addEventListener("abort", cancel, { once: true });
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      total += value.byteLength;
+      if (total > maxBytes) {
+        abort();
+        throw tooLarge;
+      }
+      chunks.push(value);
+    }
+  } catch (error) {
+    if (timeout.aborted) {
+      throw expired();
+    }
+    throw error;
+  } finally {
+    timeout.removeEventListener("abort", cancel);
+  }
+  if (timeout.aborted) {
+    throw expired();
+  }
+  return concat(chunks, total);
+}
+
+function concat(chunks: Uint8Array[], total: number): Uint8Array {
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}

package/src/core/html-scan.ts

@@ -0,0 +1,253 @@
+import { hasSlideClass, uniqueMark } from "./html.ts";
+import { lineLocator } from "./lines.ts";
+import { attributeUrls, type UrlUse } from "./url-attributes.ts";
+
+/** Where something is written: 1-based line, and 1-based column in UTF-16 units, as editors count. */
+export type SourceSpot = { line: number; column: number };
+
+/** One attribute as the parser read it, located at its name. */
+export type HtmlAttribute = SourceSpot & { name: string; value: string };
+
+/**
+ * One start tag, located at its `<`, with its attributes in source order, and whether it is in a
+ * slide: the `<section class="slide">` itself or inside one, rather than a full document's head.
+ */
+type HtmlElement = SourceSpot & {
+  tag: string;
+  attributes: HtmlAttribute[];
+  inSlide: boolean;
+};
+
+/** One URL an attribute names, located where the URL itself is written. */
+export type HtmlRef = SourceSpot & { tag: string; attr: string; value: string; use: UrlUse };
+
+export type HtmlScan = {
+  /** Every start tag in the file, in document order. */
+  elements: HtmlElement[];
+  /** Every `<section class="slide">`; only the first is ever shown. */
+  slides: HtmlElement[];
+  slug?: string;
+  /** The slide section's `data-layout`. */
+  layout?: string;
+  classes: string[];
+  /** Every URL the markup names, a `srcset` candidate apiece. */
+  refs: HtmlRef[];
+  /** Headings with nothing to read: no text, no image, no `aria-label`. */
+  emptyHeadings: HtmlElement[];
+  /**
+   * Each outermost `aria-hidden="true"` element that holds text, with that text, its whitespace
+   * collapsed. An SVG's `<title>` and `<desc>` describe it and are never drawn, so they hold none.
+   */
+  hiddenTexts: Array<{ element: HtmlElement; text: string }>;
+};
+
+const HEADING_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);
+/** Elements that give a heading something to show without any text. */
+const CONTENT_TAGS = new Set(["img", "svg", "picture", "video", "canvas", "object", "math"]);
+/** Elements whose text describes a picture rather than being drawn in it. */
+const UNDRAWN_TAGS = new Set(["title", "desc"]);
+
+/**
+ * What a slide's markup uses and references, read in one pass of the real parser and located in
+ * the source. The parser has no positions, so each start tag gets a marker in front of it; where
+ * the markers land, less their own length, is where the tags were written.
+ */
+export function scanSlideHtml(html: string): HtmlScan {
+  const mark = uniqueMark(html);
+  const parsed: Array<{ tag: string; attributes: Array<[string, string]>; inSlide: boolean }> = [];
+  let slidesOpen = 0;
+  const headings: Array<{ index: number; content: boolean }> = [];
+  const open: Array<{ index: number; content: boolean }> = [];
+  const hidden: Array<{ index: number; text: string }> = [];
+  // The outermost aria-hidden element still open, and how many undrawn elements are open in it.
+  let hiding: { index: number; text: string } | undefined;
+  let undrawn = 0;
+
+  const transformed = new HTMLRewriter()
+    .on("*", {
+      element(el) {
+        el.before(mark, { html: true });
+        const tag = el.tagName.toLowerCase();
+        const attributes = [...el.attributes].map(([name, value]): [string, string] => [
+          name.toLowerCase(),
+          value,
+        ]);
+        if (CONTENT_TAGS.has(tag)) {
+          for (const heading of open) {
+            heading.content = true;
+          }
+        }
+        if (hiding) {
+          // Two elements' texts are two words, whatever whitespace the source puts between them.
+          hiding.text += " ";
+          if (UNDRAWN_TAGS.has(tag) && el.canHaveContent) {
+            undrawn++;
+            el.onEndTag(() => {
+              undrawn--;
+            });
+          }
+        } else if (el.getAttribute("aria-hidden")?.trim() === "true" && el.canHaveContent) {
+          const entry = { index: parsed.length, text: "" };
+          hidden.push(entry);
+          hiding = entry;
+          el.onEndTag(() => {
+            hiding = undefined;
+          });
+        }
+        if (HEADING_TAGS.has(tag) && el.canHaveContent) {
+          const heading = {
+            index: parsed.length,
+            content: (el.getAttribute("aria-label") ?? "").trim() !== "",
+          };
+          headings.push(heading);
+          open.push(heading);
+          el.onEndTag(() => {
+            open.splice(open.indexOf(heading), 1);
+          });
+        }
+        if (tag === "section" && hasSlideClass(el.getAttribute("class")) && el.canHaveContent) {
+          slidesOpen++;
+          el.onEndTag(() => {
+            slidesOpen--;
+          });
+        }
+        parsed.push({ tag, attributes, inSlide: slidesOpen > 0 });
+      },
+    })
+    .onDocument({
+      text(chunk) {
+        if (hiding && undrawn === 0) {
+          hiding.text += chunk.text;
+        }
+        if (open.length > 0 && chunk.text.trim() !== "") {
+          for (const heading of open) {
+            heading.content = true;
+          }
+        }
+      },
+    })
+    .transform(html);
+  if (typeof transformed !== "string") {
+    throw new Error("HTMLRewriter.transform expected a string");
+  }
+
+  const spot = lineLocator(html);
+  const elements: HtmlElement[] = [];
+  const refs: HtmlRef[] = [];
+  let start = 0;
+  for (const [index, before] of transformed.split(mark).slice(0, -1).entries()) {
+    start += before.length;
+    const { tag, attributes, inSlide } = parsed[index] ?? {
+      tag: "",
+      attributes: [],
+      inSlide: false,
+    };
+    const offsets = attributeOffsets(html, start);
+    const element: HtmlElement = {
+      tag,
+      inSlide,
+      ...spot(start),
+      attributes: attributes.map(([name, value]) => ({
+        name,
+        value,
+        ...spot(offsets.get(name)?.name ?? start),
+      })),
+    };
+    elements.push(element);
+    for (const attribute of element.attributes) {
+      const valueAt = offsets.get(attribute.name)?.value;
+      refs.push(
+        ...attributeRefs(element.tag, attribute).map(({ ref, offset }) => ({
+          ...ref,
+          ...(valueAt === undefined ? spot(start) : spot(valueAt + offset)),
+        })),
+      );
+    }
+  }
+
+  const slides = elements.filter(
+    (element) => element.tag === "section" && hasSlideClass(attributeValue(element, "class")),
+  );
+  const slug = slides.map((element) => attributeValue(element, "data-slug")).find(isDefined);
+  const layout = slides[0] && attributeValue(slides[0], "data-layout");
+  return {
+    elements,
+    slides,
+    ...(slug === undefined ? {} : { slug }),
+    ...(layout === undefined ? {} : { layout }),
+    classes: elements.flatMap((element) =>
+      (attributeValue(element, "class") ?? "").split(/\s+/).filter(Boolean),
+    ),
+    refs,
+    emptyHeadings: headings
+      .filter((heading) => !heading.content)
+      .flatMap((heading) => elements[heading.index] ?? []),
+    hiddenTexts: hidden.flatMap(({ index, text }) => {
+      const element = elements[index];
+      const squashed = text.replace(/\s+/g, " ").trim();
+      return element && squashed !== "" ? [{ element, text: squashed }] : [];
+    }),
+  };
+}
+
+/** The value of `name` on `element`, as the parser read it. */
+function attributeValue(element: HtmlElement, name: string): string | undefined {
+  return element.attributes.find((attribute) => attribute.name === name)?.value;
+}
+
+function isDefined<T>(value: T | undefined): value is T {
+  return value !== undefined;
+}
+
+/** The URLs one attribute names, each with its offset into the value. */
+function attributeRefs(
+  tag: string,
+  attribute: HtmlAttribute,
+): Array<{ ref: Omit<HtmlRef, keyof SourceSpot>; offset: number }> {
+  const named = attributeUrls(tag, attribute.name, attribute.value);
+  if (!named) {
+    return [];
+  }
+  return named.urls.map(({ url, offset }) => ({
+    ref: { tag, attr: attribute.name, value: url, use: named.use },
+    offset,
+  }));
+}
+
+/**
+ * Where each attribute of the start tag at `start` is written: its name, and its value when it
+ * has one. Only positions come from here; names and values are the parser's.
+ */
+function attributeOffsets(
+  html: string,
+  start: number,
+): Map<string, { name: number; value?: number }> {
+  const offsets = new Map<string, { name: number; value?: number }>();
+  const re = /\s*(?:([^\s"'>/=]+)(?:(\s*=\s*)(["']?))?|\/)/y;
+  re.lastIndex = start + 1 + (html.slice(start + 1).match(/^[^\s/>]*/)?.[0].length ?? 0);
+  while (re.lastIndex < html.length && html[re.lastIndex] !== ">") {
+    const at = re.lastIndex;
+    const match = re.exec(html);
+    if (!match || match[0].length === 0) {
+      break;
+    }
+    const [whole, attr, equals, quote] = match;
+    if (attr === undefined) {
+      continue;
+    }
+    const nameAt = at + whole.indexOf(attr);
+    let valueAt: number | undefined;
+    if (equals !== undefined) {
+      valueAt = nameAt + attr.length + equals.length + (quote ? 1 : 0);
+      const end = quote
+        ? html.indexOf(quote, valueAt)
+        : valueAt + Math.max(0, html.slice(valueAt).search(/[\s>]/));
+      re.lastIndex = end === -1 ? html.length : quote ? end + 1 : end;
+    }
+    const key = attr.toLowerCase();
+    if (!offsets.has(key)) {
+      offsets.set(key, valueAt === undefined ? { name: nameAt } : { name: nameAt, value: valueAt });
+    }
+  }
+  return offsets;
+}