@hajimism/dek 0.1.0

package/src/core/presenter.ts

@@ -0,0 +1,131 @@
+import type { DekConfig } from "./config.ts";
+import type { PresenterSlide } from "./presenter-state.ts";
+import type { ProjectDeck } from "./resolve.ts";
+import { type ScriptLine, scriptLines } from "./script-lines.ts";
+import { formatSectionScript, sectionTiming } from "./timing.ts";
+
+export {
+  nextPresenterTitle,
+  type PresenterSlide,
+  presenterState,
+} from "./presenter-state.ts";
+
+/**
+ * Who reads the script the page carries: the speaker reads all of it, and a page anyone may open
+ * carries only what is said aloud, since the directions and the comments were for the speaker.
+ */
+export type ScriptReader = "speaker" | "audience";
+
+export function presenterSlides(
+  deck: ProjectDeck,
+  config: DekConfig,
+  reader: ScriptReader = "speaker",
+): PresenterSlide[] {
+  const timing = sectionTiming(deck.deck.sections, deck.deck.duration, config);
+  const budgetBySlug = new Map(timing.map((row) => [row.slug, row.budgetSeconds]));
+  return deck.deck.sections.map((section) => {
+    const script = formatSectionScript(section);
+    return {
+      slug: section.slug,
+      title: section.title,
+      script: reflowScript(reader === "audience" ? withoutDirections(script) : script),
+      beats: section.beats.map((beat) => ({ id: beat.id, title: beat.title })),
+      ...(budgetBySlug.get(section.slug) !== undefined
+        ? { budgetSeconds: budgetBySlug.get(section.slug) }
+        : {}),
+    };
+  });
+}
+
+const COMMENT_RE = /<!--[\s\S]*?(?:-->|$)/g;
+const DIRECTION_RE = /^\s*>/;
+
+/**
+ * The script without what was for the speaker alone: stage directions, which are blockquotes, and
+ * HTML comments. A fenced code block is text the slide shows, so a `>` or a comment in it stays.
+ * The blank lines a removal leaves are folded into one, as between any two paragraphs.
+ */
+export function withoutDirections(script: string): string {
+  const kept: ScriptLine[] = [];
+  for (const run of fenceRuns(scriptLines(script))) {
+    if (run[0]?.fenced) {
+      kept.push(...run);
+      continue;
+    }
+    const prose = run
+      .map((line) => line.text)
+      .join("\n")
+      .replace(COMMENT_RE, "");
+    for (const text of prose.split("\n")) {
+      if (!DIRECTION_RE.test(text)) {
+        kept.push({ text: text.trimEnd(), literal: false, fenced: false });
+      }
+    }
+  }
+  const out: string[] = [];
+  for (const line of kept) {
+    const blank = !line.fenced && line.text.trim() === "";
+    if (blank && (out.length === 0 || out.at(-1) === "")) {
+      continue;
+    }
+    out.push(line.text);
+  }
+  while (out.at(-1) === "") {
+    out.pop();
+  }
+  return out.join("\n");
+}
+
+/** The lines cut into runs that are all fenced or all not, in order. */
+function fenceRuns(lines: ScriptLine[]): ScriptLine[][] {
+  const runs: ScriptLine[][] = [];
+  for (const line of lines) {
+    const run = runs.at(-1);
+    if (run && run[0]?.fenced === line.fenced) {
+      run.push(line);
+    } else {
+      runs.push([line]);
+    }
+  }
+  return runs;
+}
+
+const FENCE_RE = /^\s*(```|~~~)/;
+/** Lines that stand on their own: blank, stage direction, list item, table row, heading. */
+const BLOCK_LINE_RE = /^\s*($|>|[-*+]\s|\d+\.\s|\||#)/;
+const WIDE_RE = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\u3000-\u303f\uff00-\uffef]/u;
+
+/**
+ * Joins the soft line breaks of each paragraph, so the presenter wraps the
+ * script to its own width instead of the editor's. Japanese joins without a
+ * space; everything else joins with one.
+ */
+export function reflowScript(script: string): string {
+  const out: string[] = [];
+  let inFence = false;
+  let joinable = false;
+  for (const raw of script.split(/\r?\n/)) {
+    if (FENCE_RE.test(raw)) {
+      inFence = !inFence;
+      out.push(raw);
+      joinable = false;
+      continue;
+    }
+    if (inFence || BLOCK_LINE_RE.test(raw)) {
+      out.push(raw);
+      joinable = false;
+      continue;
+    }
+    const line = raw.trim();
+    const last = out.length - 1;
+    const previous = out[last];
+    if (joinable && previous !== undefined) {
+      const wide = WIDE_RE.test([...previous].at(-1) ?? "") || WIDE_RE.test([...line][0] ?? "");
+      out[last] = `${previous}${wide ? "" : " "}${line}`;
+    } else {
+      out.push(line);
+    }
+    joinable = true;
+  }
+  return out.join("\n");
+}

package/src/core/prose.ts

@@ -0,0 +1,16 @@
+/** "a", "a and b", "a, b, and c". */
+export function listed(items: string[]): string {
+  return joined(items, "and");
+}
+
+/** "a", "a or b", "a, b, or c". */
+export function either(items: string[]): string {
+  return joined(items, "or");
+}
+
+function joined(items: string[], conjunction: string): string {
+  if (items.length <= 2) {
+    return items.join(` ${conjunction} `);
+  }
+  return `${items.slice(0, -1).join(", ")}, ${conjunction} ${items.at(-1)}`;
+}

package/src/core/pseudo-text.ts

@@ -0,0 +1,67 @@
+import type { CDPSession, Page } from "playwright";
+import { type Box, PSEUDO_TEXT_HOST } from "./slide-measure.ts";
+
+/** What `DOM.getDocument` gives of a node: enough to find a marked host's pseudo-elements. */
+type DomNode = {
+  nodeId: number;
+  attributes?: string[];
+  children?: DomNode[];
+  pseudoElements?: Array<{ nodeId: number; pseudoType?: string }>;
+};
+
+/**
+ * The content box of each pseudo-element `measureSlideInPage` marked as drawing text, keyed
+ * `<host>::<pseudo>`. The page exposes no box for a pseudo-element, and Chromium, which lays it
+ * out, does: through the DevTools protocol. One that is not laid out has no box and is left out.
+ */
+export async function pseudoTextBoxes(page: Page): Promise<Map<string, Box>> {
+  const cdp = await page.context().newCDPSession(page);
+  try {
+    const { root } = (await cdp.send("DOM.getDocument", { depth: -1 })) as { root: DomNode };
+    const boxes = new Map<string, Box>();
+    for (const node of walk(root)) {
+      const host = attribute(node, PSEUDO_TEXT_HOST);
+      for (const pseudo of host === undefined ? [] : (node.pseudoElements ?? [])) {
+        const box = await contentBox(cdp, pseudo.nodeId);
+        if (box && (pseudo.pseudoType === "before" || pseudo.pseudoType === "after")) {
+          boxes.set(`${host}::${pseudo.pseudoType}`, box);
+        }
+      }
+    }
+    return boxes;
+  } finally {
+    await cdp.detach();
+  }
+}
+
+function* walk(node: DomNode): Generator<DomNode> {
+  yield node;
+  for (const child of node.children ?? []) {
+    yield* walk(child);
+  }
+}
+
+/** An attribute's value from CDP's flat `[name, value, name, value, ...]` list. */
+function attribute(node: DomNode, name: string): string | undefined {
+  const attributes = node.attributes ?? [];
+  const at = attributes.indexOf(name);
+  return at >= 0 && at % 2 === 0 ? attributes[at + 1] : undefined;
+}
+
+async function contentBox(cdp: CDPSession, nodeId: number): Promise<Box | undefined> {
+  try {
+    const { model } = (await cdp.send("DOM.getBoxModel", { nodeId })) as {
+      model: { content: number[] };
+    };
+    const xs = model.content.filter((_, index) => index % 2 === 0);
+    const ys = model.content.filter((_, index) => index % 2 === 1);
+    return {
+      left: Math.min(...xs),
+      top: Math.min(...ys),
+      right: Math.max(...xs),
+      bottom: Math.max(...ys),
+    };
+  } catch {
+    return undefined;
+  }
+}

package/src/core/rail-width.ts

@@ -0,0 +1,4 @@
+/** The slide rail's width in px: the page renders it, the player resizes it within these bounds. */
+export const RAIL_WIDTH_DEFAULT = 188;
+export const RAIL_WIDTH_MIN = 120;
+export const RAIL_WIDTH_MAX = 360;

package/src/core/ref-name.ts

@@ -0,0 +1,110 @@
+import { DekError } from "./error.ts";
+
+/**
+ * A ref is someone else's deck, kept as a read-only snapshot to read as a
+ * model. dek.toml `[refs]` pins each one to a commit; the snapshot under
+ * `refs/owner/repo/deck` is only a copy of that commit and can be fetched again.
+ * This module only names refs; `ref.ts` fetches and stores them.
+ */
+export type RefSource = {
+  /** `owner/repo/deck`, the key in dek.toml `[refs]`. */
+  name: string;
+  owner: string;
+  repo: string;
+  deck: string;
+  /** A tag, branch, or sha after `@`. */
+  rev?: string;
+  /** The deck's directory in the repository, known when a GitHub URL named it. */
+  path?: string;
+};
+
+const OWNER_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+const REPO_RE = /^[A-Za-z0-9._-]+$/;
+const DECK_RE = /^[^/\\\s@]+$/;
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+const REF_HINT =
+  "name a ref as owner/repo/deck, e.g. hajimism/dek/why-dek or hajimism/dek/why-dek@v1";
+
+/** True for `owner/repo/deck[@rev]` or a GitHub link, which a deck name never is. */
+export function isRefName(arg: string): boolean {
+  if (/^https?:\/\/(www\.)?github\.com\//i.test(arg)) {
+    return true;
+  }
+  if (arg.startsWith(".") || arg.startsWith("/") || arg.startsWith("~")) {
+    return false;
+  }
+  return arg.split("@")[0]?.split("/").length === 3;
+}
+
+/** A valid `owner/repo/deck` with no rev: the form dek.toml `[refs]` keys take. */
+export function isPlainRefName(name: string): boolean {
+  try {
+    const source = parseRefSource(name);
+    return source.rev === undefined && source.name === name;
+  } catch {
+    return false;
+  }
+}
+
+export function isPinnedRev(rev: string): boolean {
+  return SHA_RE.test(rev);
+}
+
+export function parseRefSource(input: string): RefSource {
+  const trimmed = input.trim();
+  if (/^https?:\/\//i.test(trimmed)) {
+    return parseGithubUrl(trimmed);
+  }
+  const at = trimmed.indexOf("@");
+  const path = at === -1 ? trimmed : trimmed.slice(0, at);
+  const rev = at === -1 ? undefined : trimmed.slice(at + 1);
+  const [owner, repo, deck, ...extra] = path.split("/");
+  const valid =
+    extra.length === 0 &&
+    owner !== undefined &&
+    OWNER_RE.test(owner) &&
+    repo !== undefined &&
+    REPO_RE.test(repo) &&
+    repo !== "." &&
+    repo !== ".." &&
+    deck !== undefined &&
+    DECK_RE.test(deck) &&
+    deck !== "." &&
+    deck !== ".." &&
+    (rev === undefined || /^[^\s@]+$/.test(rev));
+  if (!valid) {
+    throw new DekError(`"${input}" is not a ref name`, { hint: REF_HINT });
+  }
+  return {
+    name: `${owner}/${repo}/${deck}`,
+    owner,
+    repo,
+    deck,
+    ...(rev !== undefined ? { rev } : {}),
+  };
+}
+
+/**
+ * `https://github.com/owner/repo/tree/<rev>/<path>/decks/<deck>[/...]`, the
+ * link people copy from a browser. A branch name with a slash cannot be told
+ * apart from the path, so such a branch goes after `@` instead.
+ */
+function parseGithubUrl(input: string): RefSource {
+  const url = new URL(input);
+  const [owner = "", repo = "", kind, rev, ...rest] = url.pathname.split("/").filter(Boolean);
+  const decks = rest.indexOf("decks");
+  const deck = decks === -1 ? undefined : rest[decks + 1];
+  if (
+    url.hostname !== "github.com" ||
+    (kind !== "tree" && kind !== "blob") ||
+    !rev ||
+    deck === undefined
+  ) {
+    throw new DekError(`"${input}" is not a link to a deck on GitHub`, {
+      hint: "link to the deck's folder, e.g. https://github.com/hajimism/dek/tree/main/sample/decks/why-dek, or name it as owner/repo/deck",
+    });
+  }
+  const source = parseRefSource(`${owner}/${repo.replace(/\.git$/, "")}/${deck}@${rev}`);
+  return { ...source, path: rest.slice(0, decks + 2).join("/") };
+}

package/src/core/ref.ts

@@ -0,0 +1,238 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { loadConfig } from "./config.ts";
+import { DekError } from "./error.ts";
+import { parseRefSource, type RefSource } from "./ref-name.ts";
+import { listSlides, resolveProject } from "./resolve.ts";
+import { outputDir } from "./safe-fs.ts";
+
+export {
+  isPinnedRev,
+  isRefName,
+  parseRefSource,
+  type RefSource,
+} from "./ref-name.ts";
+
+function isLink(path: string): boolean {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** Written into each snapshot; its presence is what makes a directory a ref. */
+export const REF_MARKER = ".ref.json";
+
+export const RefMeta = z.object({
+  name: z.string(),
+  rev: z.string(),
+  /** The deck's directory inside the source repository. */
+  path: z.string(),
+});
+export type RefMeta = z.infer<typeof RefMeta>;
+
+export function refDir(root: string, name: string): string {
+  const { owner, repo, deck } = parseRefSource(name);
+  return join(root, "refs", owner, repo, deck);
+}
+
+/** The marker of a snapshot, or nothing when it is missing or not one dek wrote. */
+export function readRefMeta(dir: string): RefMeta | undefined {
+  const path = join(dir, REF_MARKER);
+  if (!existsSync(path)) {
+    return undefined;
+  }
+  try {
+    const parsed = RefMeta.safeParse(JSON.parse(readFileSync(path, "utf8")));
+    return parsed.success ? parsed.data : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const LICENSE_NAMES = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"];
+
+/** The snapshot's license file, relative to the snapshot, when the source had one. */
+export function refLicense(dir: string): string | null {
+  return LICENSE_NAMES.find((name) => existsSync(join(dir, name))) ?? null;
+}
+
+/** What the project knows about one ref: its pin in dek.toml and whether the snapshot matches it. */
+export type RefState = {
+  name: string;
+  /** The commit dek.toml pins, or nothing when the ref is not added. */
+  pinned?: string;
+  /** The snapshot directory, whether or not anything is there. */
+  dir: string;
+  /** True when the snapshot on disk is the pinned commit. */
+  fetched: boolean;
+};
+
+export function refState(project: { root: string; configPath: string }, name: string): RefState {
+  const pinned = loadConfig(project.configPath).refs?.[name];
+  const dir = refDir(project.root, name);
+  return {
+    name,
+    ...(pinned !== undefined ? { pinned } : {}),
+    dir,
+    fetched: pinned !== undefined && readRefMeta(dir)?.rev === pinned,
+  };
+}
+
+/** A repository's files by path, without the tarball's top directory. */
+export type RepoFiles = Map<string, Blob>;
+
+/** Beyond this, a snapshot is refused: a deck to read is a few hundred kilobytes. */
+const MAX_SNAPSHOT_BYTES = 50 * 1024 * 1024;
+
+/**
+ * Reads a GitHub tarball. Bun leaves out links; a path that is absolute, has
+ * an empty segment, or climbs with `..` is dropped here, so nothing written
+ * later can land outside the snapshot.
+ */
+export async function readTarball(bytes: Uint8Array): Promise<RepoFiles> {
+  const files: RepoFiles = new Map();
+  for (const [path, blob] of await new Bun.Archive(bytes).files()) {
+    const [, ...segments] = path.split("/");
+    const safe =
+      segments.length > 0 &&
+      !path.includes("\\") &&
+      segments.every((segment) => segment !== "" && segment !== "." && segment !== "..");
+    if (safe && !path.startsWith("/")) {
+      files.set(segments.join("/"), blob);
+    }
+  }
+  return files;
+}
+
+const DECK_SCRIPT_RE = /^(?:(.*)\/)?decks\/([^/]+)\/script\.md$/;
+
+/** The decks in a repository: each `decks/<name>/script.md` beside its project's dek.toml. */
+function repoDecks(files: RepoFiles): Array<{ name: string; prefix: string }> {
+  return [...files.keys()].flatMap((path) => {
+    const match = path.match(DECK_SCRIPT_RE);
+    const prefix = match?.[1] ? `${match[1]}/` : "";
+    return match?.[2] && files.has(`${prefix}dek.toml`) ? [{ name: match[2], prefix }] : [];
+  });
+}
+
+/** The directory of the project that holds the deck, as a prefix: "" or "sample/". */
+export function findDeckInRepo(files: RepoFiles, source: RefSource): string {
+  const repo = `${source.owner}/${source.repo}`;
+  const decks = repoDecks(files);
+  const matches = decks.filter(
+    (deck) =>
+      deck.name === source.deck &&
+      (source.path === undefined || `${deck.prefix}decks/${deck.name}` === source.path),
+  );
+  const [match, ...others] = matches;
+  if (!match) {
+    const names = [...new Set(decks.map((deck) => deck.name))].sort();
+    throw new DekError(`${repo} has no deck "${source.deck}"`, {
+      hint:
+        names.length > 0
+          ? `decks in ${repo}: ${names.join(", ")}`
+          : `${repo} holds no dek project (decks/<name>/script.md beside a dek.toml)`,
+    });
+  }
+  if (others.length > 0) {
+    const paths = matches.map((deck) => `${deck.prefix}decks/${deck.name}`).sort();
+    throw new DekError(`${repo} has more than one deck named "${source.deck}"`, {
+      hint: `pass the GitHub link to the one you mean; they are at ${paths.join(", ")}`,
+    });
+  }
+  return match.prefix;
+}
+
+/** Inside the deck, only what reading it needs: not dist/, .cache/, or voice/. */
+function keepsInDeck(path: string): boolean {
+  return (
+    path === "script.md" ||
+    path === "theme.css" ||
+    path.startsWith("slides/") ||
+    path.startsWith("assets/")
+  );
+}
+
+/**
+ * Writes the snapshot of one deck at one commit under refs/, laid out as the
+ * project it came from so it resolves like any dek project. It is written
+ * beside the old one and swapped in, so a failure leaves the old one whole.
+ */
+export async function installSnapshot(
+  root: string,
+  source: RefSource,
+  sha: string,
+  files: RepoFiles,
+): Promise<{ dir: string; license: string | null; path: string }> {
+  const prefix = findDeckInRepo(files, source);
+  const deckPrefix = `${prefix}decks/${source.deck}/`;
+  const license =
+    LICENSE_NAMES.find((name) => files.has(name)) ??
+    LICENSE_NAMES.find((name) => files.has(`${prefix}${name}`));
+  const picked = new Map<string, Blob>();
+  picked.set("dek.toml", files.get(`${prefix}dek.toml`) ?? new Blob([]));
+  for (const [path, blob] of files) {
+    const inDeck = path.startsWith(deckPrefix) ? path.slice(deckPrefix.length) : undefined;
+    if (inDeck !== undefined && keepsInDeck(inDeck)) {
+      picked.set(`decks/${source.deck}/${inDeck}`, blob);
+    }
+  }
+  if (license) {
+    picked.set(license, files.get(license) ?? files.get(`${prefix}${license}`) ?? new Blob([]));
+  }
+  const size = [...picked.values()].reduce((sum, blob) => sum + blob.size, 0);
+  if (size > MAX_SNAPSHOT_BYTES) {
+    throw new DekError(`${source.name} is larger than ${MAX_SNAPSHOT_BYTES / 1024 / 1024} MB`, {
+      hint: "a deck to read as a model should be far smaller; check its assets",
+    });
+  }
+
+  // refs/ is dek's; a link on the way would aim the swap below, and its delete, elsewhere.
+  const refsDir = join(root, "refs");
+  const dir = refDir(root, source.name);
+  outputDir(dirname(dir), root);
+  if (isLink(dir)) {
+    await rm(dir);
+  }
+  const suffix = `${process.pid}-${Date.now().toString(36)}`;
+  const temp = join(refsDir, `.tmp-${suffix}`);
+  const old = join(refsDir, `.old-${suffix}`);
+  const meta: RefMeta = { name: source.name, rev: sha, path: `${prefix}decks/${source.deck}` };
+  try {
+    for (const [path, blob] of picked) {
+      await mkdir(dirname(join(temp, path)), { recursive: true });
+      await writeFile(join(temp, path), new Uint8Array(await blob.arrayBuffer()));
+    }
+    await writeFile(join(temp, REF_MARKER), `${JSON.stringify(meta, null, 2)}\n`);
+    if (existsSync(dir)) {
+      await rename(dir, old);
+    }
+    await rename(temp, dir);
+  } catch (error) {
+    if (!existsSync(dir) && existsSync(old)) {
+      await rename(old, dir);
+    }
+    throw error;
+  } finally {
+    await rm(temp, { recursive: true, force: true });
+    // Until the snapshot is back in place, `old` may be the only copy left.
+    if (existsSync(dir)) {
+      await rm(old, { recursive: true, force: true });
+    }
+  }
+  return { dir, license: license ?? null, path: meta.path };
+}
+
+/** The snapshot deck's title and slide count, or nothing when it does not parse. */
+export function refTitle(dir: string, deck: string): { title: string; slides: number } | undefined {
+  try {
+    const found = resolveProject(dir).decks.find((entry) => entry.name === deck);
+    return found ? { title: found.deck.title, slides: listSlides(found.dir).length } : undefined;
+  } catch {
+    return undefined;
+  }
+}