@hajimism/dek 0.1.0

package/src/core/page.ts

@@ -0,0 +1,66 @@
+import { escapeAttr } from "./escape.ts";
+
+// What the deck page and the player runtime agree on: the ids the page is built with, and the
+// settings it carries on <body>. The runtime bundles this for the browser: no Node imports.
+
+/** The ids of the page's parts, by what they are. */
+export const PAGE_ID = {
+  deck: "deck",
+  data: "dek-data",
+  shell: "dek-shell",
+  rail: "dek-rail",
+  railResize: "dek-rail-resize",
+  current: "dek-current",
+  currentStage: "dek-current-stage",
+  presenter: "dek-presenter",
+  progress: "dek-progress",
+  nextPanel: "dek-next-panel",
+  nextStage: "dek-next-stage",
+  nextEnd: "dek-next-end",
+  next: "dek-next",
+  notesPanel: "dek-notes-panel",
+  beats: "dek-beats",
+  script: "dek-script",
+  presenterBar: "dek-presenter-bar",
+  page: "dek-page",
+  elapsed: "dek-elapsed",
+  budget: "dek-budget",
+  laser: "dek-laser",
+  laserToggle: "dek-laser-toggle",
+  markToggle: "dek-mark-toggle",
+  hint: "dek-hint",
+  announce: "dek-announce",
+} as const;
+
+export type PageMode = "player" | "presenter" | "video";
+
+/** The page's settings, written on <body> as `data-*` and read back once by the runtime. */
+export type PageConfig = {
+  mode: PageMode;
+  deck: string;
+  /** The dev server's page: it follows the server's socket and events. */
+  live: boolean;
+  /** What a presenter page sends as `?token=` on its live channels. */
+  liveToken?: string;
+};
+
+/** `config` as the attributes of <body>, values escaped. */
+export function pageConfigAttrs(config: PageConfig): string {
+  return [
+    ` data-mode="${config.mode}"`,
+    ` data-deck="${escapeAttr(config.deck)}"`,
+    config.live ? ` data-live="true"` : "",
+    config.liveToken ? ` data-live-token="${escapeAttr(config.liveToken)}"` : "",
+  ].join("");
+}
+
+/** The settings `pageConfigAttrs` wrote on `body`. */
+export function readPageConfig(body: HTMLElement): PageConfig {
+  const { mode, deck, live, liveToken } = body.dataset;
+  return {
+    mode: mode === "presenter" || mode === "video" ? mode : "player",
+    deck: deck ?? "",
+    live: live === "true",
+    ...(liveToken ? { liveToken } : {}),
+  };
+}

package/src/core/parse.ts

@@ -0,0 +1,307 @@
+import { DekError } from "./error.ts";
+import { splitLines } from "./lines.ts";
+import { type Beat, Deck, Frontmatter, Id, inferLang, type Section } from "./schema.ts";
+import { scriptLines } from "./script-lines.ts";
+import { configHint, formatZodIssues, parseFailure } from "./zod.ts";
+
+const HEADING_RE = /^(#{2,3})(?!#)\s+(.*)$/;
+const TRAILING_ATTR_RE = /^(.*?)\s*\{([^}]*)\}\s*$/;
+const ID_ATTR_RE = /^#([a-z0-9-]+)$/;
+const YAML_PAIR_RE = /^(\s*[\w-]+\s*:)(\s*)(.*)$/;
+
+/** One thing that stops a script.md from being read, where it is and how to fix it. */
+export type ScriptProblem = { message: string; line?: number; hint?: string };
+
+/**
+ * A script.md that cannot be read, with every problem that stops it, so one run reports them all.
+ * The first is the error's own message, line, and hint, for a command that stops on it.
+ */
+export class ScriptError extends DekError {
+  readonly problems: ScriptProblem[];
+
+  constructor(problems: [ScriptProblem, ...ScriptProblem[]], path: string | undefined) {
+    const [first] = problems;
+    super(first.message, {
+      ...(path !== undefined ? { path } : {}),
+      ...(first.line !== undefined ? { line: first.line } : {}),
+      ...(first.hint !== undefined ? { hint: first.hint } : {}),
+    });
+    this.name = "ScriptError";
+    this.problems = problems;
+  }
+}
+
+/**
+ * The deck a script.md describes. Every problem is collected before any is thrown: the
+ * frontmatter and each heading are read on their own, and a heading that cannot be read still
+ * opens its section, so the beats under it are not reported as well.
+ */
+export function parseScript(source: string, filename?: string): Deck {
+  const problems: ScriptProblem[] = [];
+  const { yaml, body, bodyStartLine } = splitFrontmatter(source, filename);
+  const frontmatter = collect(problems, () => parseFrontmatter(yaml, filename));
+  const sections = parseSections(body, bodyStartLine, problems);
+
+  if (frontmatter !== undefined && problems.length === 0) {
+    const lang = frontmatter.lang ?? inferLang(`${frontmatter.title}\n${body}`);
+    const result = Deck.safeParse({ ...frontmatter, lang, sections });
+    if (result.success) {
+      return result.data;
+    }
+    problems.push({ message: formatZodIssues(result.error) });
+  }
+  // A frontmatter that was not read left its problem, so there is always a first one.
+  const [first = { message: "script.md could not be read" }, ...rest] = problems;
+  throw new ScriptError([first, ...rest], filename);
+}
+
+/** `read`'s value, or undefined with its DekError kept as a problem. */
+function collect<T>(problems: ScriptProblem[], read: () => T): T | undefined {
+  try {
+    return read();
+  } catch (error) {
+    if (!(error instanceof DekError)) {
+      throw error;
+    }
+    problems.push({
+      message: error.message,
+      ...(error.line !== undefined ? { line: error.line } : {}),
+      ...(error.hint !== undefined ? { hint: error.hint } : {}),
+    });
+    return undefined;
+  }
+}
+
+/** A script.md cut at its frontmatter fences; the YAML starts on line 2. */
+export type ScriptParts = { yaml: string; body: string; bodyStartLine: number };
+
+export function splitFrontmatter(source: string, filename?: string): ScriptParts {
+  const lines = splitLines(source);
+  if (lines[0]?.trim() !== "---") {
+    throw new DekError("script.md must start with YAML frontmatter", {
+      line: 1,
+      path: filename,
+      hint: "start it with three lines: ---, title: Your talk, ---",
+    });
+  }
+
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") {
+      return {
+        yaml: lines.slice(1, i).join("\n"),
+        body: lines.slice(i + 1).join("\n"),
+        bodyStartLine: i + 2,
+      };
+    }
+  }
+
+  throw new DekError("YAML frontmatter is not closed", { line: 1, path: filename });
+}
+
+/** The frontmatter's YAML as a value, before the schema reads it; a syntax error throws. */
+export function readFrontmatterYaml(yaml: string): unknown {
+  return Bun.YAML.parse(quoteUnquotedHashes(yaml));
+}
+
+function parseFrontmatter(yaml: string, filename?: string): Frontmatter {
+  let parsed: unknown;
+  try {
+    parsed = readFrontmatterYaml(yaml);
+  } catch (error) {
+    throw new DekError(`invalid YAML frontmatter: ${parseFailure(error)}`, {
+      path: filename,
+      cause: error,
+      hint: configHint("frontmatter"),
+    });
+  }
+
+  const result = Frontmatter.safeParse(parsed);
+  if (!result.success) {
+    throw new DekError(formatZodIssues(result.error), {
+      path: filename,
+      hint: configHint("frontmatter"),
+    });
+  }
+  return result.data;
+}
+
+/** Keep values like `Meetup #42` intact; YAML would otherwise treat `#` as a comment. */
+function quoteUnquotedHashes(yaml: string): string {
+  return splitLines(yaml)
+    .map((line) => {
+      if (/^\s*#/.test(line) || !line.includes("#")) {
+        return line;
+      }
+      const match = line.match(YAML_PAIR_RE);
+      if (!match) {
+        return line;
+      }
+      let value = (match[3] ?? "").trimEnd();
+      if (!value || /^["'[{]/.test(value)) {
+        return line;
+      }
+      const comment = value.match(/^(.*) # .+$/);
+      if (comment) {
+        value = (comment[1] ?? "").trimEnd();
+        if (!value) {
+          return line;
+        }
+      }
+      const prefix = `${match[1] ?? ""}${match[2] ?? ""}`;
+      return `${prefix}${JSON.stringify(value)}`;
+    })
+    .join("\n");
+}
+
+function parseSections(body: string, startLine: number, problems: ScriptProblem[]): Section[] {
+  const sections: Section[] = [];
+  let current: DraftSection | undefined;
+  let bodyLines: string[] = [];
+
+  const flushBody = (): string => {
+    const text = bodyLines.join("\n").replace(/^\n+/, "").replace(/\n+$/, "");
+    bodyLines = [];
+    return text;
+  };
+
+  const finishBeat = (): void => {
+    if (!current?.beat) {
+      return;
+    }
+    current.beats.push({ ...current.beat, body: flushBody() });
+    current.beat = undefined;
+  };
+
+  const finishSection = (): void => {
+    if (!current) {
+      return;
+    }
+    finishBeat();
+    if (current.beats.length === 0) {
+      current.body = flushBody();
+    }
+    sections.push({
+      slug: current.slug,
+      title: current.title,
+      body: current.body,
+      beats: current.beats,
+      line: current.line,
+    });
+    current = undefined;
+  };
+
+  for (const [i, { text: line, literal }] of scriptLines(body).entries()) {
+    const lineNumber = startLine + i;
+    const heading = literal ? null : line.match(HEADING_RE);
+    if (!heading) {
+      bodyLines.push(line);
+      continue;
+    }
+
+    const hashes = heading[1] ?? "";
+    const text = heading[2] ?? "";
+    if (hashes === "##") {
+      finishSection();
+      const parsed = collect(problems, () =>
+        parseHeading(text, lineNumber, { idRequired: true, hashes }),
+      );
+      // A heading that cannot be read still opens its section, so its beats are not reported too.
+      current = {
+        slug: parsed?.id ?? "",
+        title: parsed?.title ?? text.trim(),
+        body: "",
+        beats: [],
+        line: lineNumber,
+      };
+      continue;
+    }
+
+    if (!current) {
+      problems.push({ message: "### beat is not inside a ## section", line: lineNumber });
+      continue;
+    }
+    finishBeat();
+    if (current.beats.length === 0) {
+      current.body = flushBody();
+    }
+    const parsed = collect(problems, () =>
+      parseHeading(text, lineNumber, { idRequired: false, hashes }),
+    );
+    current.beat = {
+      ...(parsed?.id ? { id: parsed.id } : {}),
+      title: parsed?.title ?? text.trim(),
+      line: lineNumber,
+    };
+  }
+
+  finishSection();
+  return sections;
+}
+
+type DraftSection = {
+  slug: string;
+  title: string;
+  body: string;
+  beats: Beat[];
+  line: number;
+  beat?: { id?: string; title: string; line: number };
+};
+
+function parseHeading(
+  text: string,
+  line: number,
+  options: { idRequired: true; hashes: string },
+): { title: string; id: string };
+function parseHeading(
+  text: string,
+  line: number,
+  options: { idRequired: false; hashes: string },
+): { title: string; id?: string };
+function parseHeading(
+  text: string,
+  line: number,
+  options: { idRequired: boolean; hashes: string },
+): { title: string; id?: string } {
+  const attrMatch = text.match(TRAILING_ATTR_RE);
+  if (attrMatch) {
+    const title = (attrMatch[1] ?? "").trim();
+    const attrs = attrMatch[2] ?? "";
+    const idMatch = attrs.match(ID_ATTR_RE);
+    const id = idMatch?.[1];
+    if (!id || !Id.safeParse(id).success) {
+      throw new DekError("heading attribute must be {#id}", {
+        line,
+        hint: headingIdHint(options.hashes, title, attrs.trim().match(/^#(.+)$/)?.[1]),
+      });
+    }
+    return { title, id };
+  }
+
+  const title = text.trim();
+  if (Id.safeParse(title).success) {
+    return { title, id: title };
+  }
+  if (options.idRequired) {
+    throw new DekError("heading requires {#id}", {
+      line,
+      hint: headingIdHint(options.hashes, title),
+    });
+  }
+  return { title };
+}
+
+/** An id built from the ASCII words of `source`, when it has any letters. */
+function suggestId(source: string): string | undefined {
+  const id = source
+    .toLowerCase()
+    .match(/[a-z0-9]+/g)
+    ?.join("-");
+  return id && Id.safeParse(id).success ? id : undefined;
+}
+
+function headingIdHint(hashes: string, title: string, given?: string): string {
+  const id = (given && suggestId(given)) ?? suggestId(title);
+  return id
+    ? `write it as \`${hashes} ${title} {#${id}}\``
+    : `write it as \`${hashes} ${title} {#your-id}\`; ids use a-z, 0-9, and -`;
+}

package/src/core/path.ts

@@ -0,0 +1,58 @@
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function moduleFilePath(url: string | URL): string {
+  return fileURLToPath(url);
+}
+
+export function isInside(filePath: string, root: string): boolean {
+  const rel = relative(resolve(root), resolve(filePath));
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+/** The project a deck belongs to: decks live at `<root>/decks/<name>`. */
+export function deckProjectRoot(deckDir: string): string {
+  return resolve(deckDir, "..", "..");
+}
+
+export const DECK_NAME_HINT =
+  'use a plain name like 2026-10-talk: no "/" or "\\", no control characters, no leading "-"';
+
+export function isDeckName(name: string): boolean {
+  return (
+    name.length > 0 &&
+    !name.includes("/") &&
+    !name.includes("\\") &&
+    name !== "." &&
+    name !== ".." &&
+    // A leading "-" reads as a flag to every tool the name is passed to.
+    !name.startsWith("-") &&
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: a control in a name is the problem.
+    !/[\x00-\x1f\x7f]/.test(name)
+  );
+}
+
+export type DistOptions = {
+  rootDist?: boolean;
+};
+
+export function distDir(
+  project: { root: string },
+  deck: { dir: string },
+  options?: DistOptions,
+): string {
+  return options?.rootDist ? join(project.root, "dist") : join(deck.dir, "dist");
+}
+
+export function distFile(
+  project: { root: string },
+  deck: { dir: string; name: string },
+  ext: string,
+  options?: DistOptions,
+): string {
+  return join(distDir(project, deck, options), `${deck.name}.${ext}`);
+}
+
+export function cacheDir(deckDir: string, kind: "voice" | "video" | "shots" | "visual"): string {
+  return join(deckDir, ".cache", kind);
+}

package/src/core/pdf.ts

@@ -0,0 +1,71 @@
+import { readTheme } from "./assets.ts";
+import { printPageCss } from "./chrome.ts";
+import { deckSlides, htmlShell, slidePlace, stampSlide } from "./html.ts";
+import { type DistOptions, distFile } from "./path.ts";
+import { type PlaywrightRunner, requirePlaywright } from "./playwright.ts";
+import { asResolvedDeck, type ProjectDeck, type ResolvedDeck } from "./resolve.ts";
+import { outputPath } from "./safe-fs.ts";
+import { logicalSize } from "./size.ts";
+import { readSlideScripts, stillPageScript } from "./slide-script.ts";
+import { lastStop, stepKey, stepValuesForBeat } from "./step.ts";
+
+export type PdfResult = {
+  outPath: string;
+};
+
+export type PdfOptions = DistOptions & {
+  runner?: PlaywrightRunner;
+};
+
+export async function pdfDeck(dir: string, options?: PdfOptions): Promise<PdfResult>;
+export async function pdfDeck(source: ResolvedDeck, options?: PdfOptions): Promise<PdfResult>;
+export async function pdfDeck(
+  input: string | ResolvedDeck,
+  options: PdfOptions = {},
+): Promise<PdfResult> {
+  const { project, deck } = asResolvedDeck(input);
+  const outPath = distFile(project, deck, "pdf", options);
+  await requirePlaywright(
+    {
+      kind: "pdf",
+      viewport: logicalSize(deck.deck.ratio),
+      html: renderPdfHtml(deck),
+      // Chromium opens the path itself, so what is there must not be a link it would write through.
+      pdfPath: outputPath(outPath, project.root),
+    },
+    options.runner,
+  );
+  return { outPath };
+}
+
+/**
+ * Every slide of the deck on one page, each at its last beat, as the PDF prints it. `strict` stops
+ * on a slide script that cannot run, as a PDF must; a lenient page leaves it out.
+ */
+export function renderPdfHtml(deck: ProjectDeck, options: { strict?: boolean } = {}): string {
+  const slides = deckSlides(deck);
+  // Every slide at its last beat, as a handout shows it.
+  const { sections } = deck.deck;
+  const slidesHtml = sections
+    .map((section, index) => {
+      const last = lastStop(section.beats);
+      return stampSlide(slides.section(section.slug), {
+        slug: section.slug,
+        place: slidePlace(sections, index),
+        shown: stepValuesForBeat(section.beats, last),
+        beat: { index: last, step: stepKey(section.beats, last) },
+        inline: { deckDir: deck.dir },
+      });
+    })
+    .join("");
+  const themeCss = readTheme(deck.dir, true);
+  const size = logicalSize(deck.deck.ratio);
+  return htmlShell({
+    lang: deck.deck.lang,
+    title: deck.deck.title,
+    head: `<style>${themeCss}</style>
+  <style>${printPageCss(size)}</style>`,
+    body: `<div id="deck">${slidesHtml}</div>
+  ${stillPageScript(readSlideScripts(deck.dir, { strict: options.strict ?? true }))}`,
+  });
+}

package/src/core/playwright-module.d.ts

@@ -0,0 +1,43 @@
+declare module "playwright" {
+  type Viewport = { width: number; height: number };
+  export type Page = {
+    goto(url: string): Promise<unknown>;
+    setContent(html: string, options?: { waitUntil?: string }): Promise<void>;
+    emulateMedia(options: { reducedMotion?: "reduce" | "no-preference" }): Promise<void>;
+    setViewportSize(size: Viewport): Promise<void>;
+    evaluate<T, A = unknown>(fn: (arg: A) => T | Promise<T>, arg?: A): Promise<T>;
+    screenshot(options: {
+      path?: string;
+      fullPage?: boolean;
+      type?: "png" | "jpeg";
+    }): Promise<Buffer>;
+    addScriptTag(options: { content: string }): Promise<unknown>;
+    pdf(options: {
+      path: string;
+      width?: string;
+      height?: string;
+      printBackground?: boolean;
+      margin?: { top?: string; right?: string; bottom?: string; left?: string };
+    }): Promise<Buffer>;
+    close(): Promise<void>;
+    context(): BrowserContext;
+  };
+  /** A DevTools protocol session: Chromium's own answers, for what the page does not expose. */
+  export type CDPSession = {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    detach(): Promise<void>;
+  };
+  export type BrowserContext = {
+    newPage(): Promise<Page>;
+    newCDPSession(page: Page): Promise<CDPSession>;
+    close(): Promise<void>;
+  };
+  export type Browser = {
+    newPage(options?: { viewport?: Viewport }): Promise<Page>;
+    newContext(options?: { viewport?: Viewport }): Promise<BrowserContext>;
+    close(): Promise<void>;
+  };
+  export const chromium: {
+    launch(options?: { headless?: boolean }): Promise<Browser>;
+  };
+}

package/src/core/playwright-motion.ts

@@ -0,0 +1,42 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { Page } from "playwright";
+import { captureGo, loadVideoDoc, settleAt } from "./capture-go.ts";
+import type { MotionSpec } from "./playwright.ts";
+import type { MotionBeat, MotionFrame } from "./sheet.ts";
+
+/**
+ * Plays each beat of the request in the video document `html` the way the talk reaches it, from the
+ * beat before. Each go is held at `fractions` of how long it runs, then ended the way a still
+ * of that beat ends it, so the last frame is the beat as `dekc shot` shows it. A go that moves
+ * nothing is that last frame alone.
+ */
+export async function captureMotion(
+  page: Page,
+  html: string,
+  motion: MotionSpec,
+): Promise<MotionBeat[]> {
+  await loadVideoDoc(page, html);
+  if (motion.from) {
+    await settleAt(page, motion.from);
+  }
+  const framesDir = join(motion.dir, "frames");
+  mkdirSync(framesDir, { recursive: true });
+  const beats: MotionBeat[] = [];
+  for (const [index, beat] of motion.beats.entries()) {
+    const frames: MotionFrame[] = [];
+    await captureGo(
+      page,
+      beat.position,
+      (span) => (span > 0 ? motion.fractions.map((fraction) => fraction * span) : []),
+      async (ms, end) => {
+        const name = end ? "end" : String(Math.round(ms)).padStart(5, "0");
+        const path = join(framesDir, `${index + 1}-${name}.png`);
+        await page.screenshot({ path, fullPage: false });
+        frames.push(end ? { ms, path, end: true } : { ms, path });
+      },
+    );
+    beats.push({ label: beat.label, frames });
+  }
+  return beats;
+}

package/src/core/playwright-sheet.ts

@@ -0,0 +1,32 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { Page } from "playwright";
+import { type SheetSpec, sheetHtml, sheetLayout } from "./sheet.ts";
+
+/**
+ * Draws each contact sheet from the captures on disk, one page at its own size apiece, and
+ * returns their paths in order. The images go in as data: URIs, so the page loads nothing.
+ */
+export async function renderSheets(
+  specs: SheetSpec[],
+  newPage: () => Promise<Page>,
+): Promise<string[]> {
+  const drawn: string[] = [];
+  for (const spec of specs) {
+    const page = await newPage();
+    try {
+      await page.setViewportSize(sheetLayout(spec).size);
+      await page.setContent(sheetHtml(spec, pngDataUri), { waitUntil: "load" });
+      mkdirSync(dirname(spec.path), { recursive: true });
+      await page.screenshot({ path: spec.path, fullPage: false });
+      drawn.push(spec.path);
+    } finally {
+      await page.close();
+    }
+  }
+  return drawn;
+}
+
+function pngDataUri(path: string): string {
+  return `data:image/png;base64,${readFileSync(path).toString("base64")}`;
+}