@hajimism/dek 0.1.0

package/src/runtime/settle.ts

@@ -0,0 +1,45 @@
+export type AnimationLike = {
+  playState?: string;
+  finished?: Promise<unknown>;
+  effect?: { getComputedTiming(): { endTime?: number | CSSNumberish } } | null;
+};
+
+export type ViewTransitionLike = {
+  finished: Promise<unknown>;
+  /** Rejects when the transition is skipped, which a hurried move does on purpose. */
+  ready?: Promise<unknown>;
+  /** Rejects when the update itself threw. */
+  updateCallbackDone?: Promise<unknown>;
+};
+
+export async function waitForPlaybackSettle(options: {
+  animations?: AnimationLike[];
+  viewTransition?: ViewTransitionLike | null;
+}): Promise<void> {
+  const tasks: Array<Promise<unknown>> = [];
+  const transition = options.viewTransition;
+  if (transition) {
+    // A skipped transition still ran its update; only the animation was dropped.
+    transition.ready?.catch(() => undefined);
+    tasks.push(transition.finished.catch(() => undefined));
+    // The update's own error is the move's, as it is when no transition wraps it.
+    if (transition.updateCallbackDone) {
+      tasks.push(transition.updateCallbackDone);
+    }
+  }
+  for (const animation of options.animations ?? []) {
+    if (animation.playState === "idle" || animation.playState === "finished") {
+      continue;
+    }
+    // One that repeats forever never finishes; waiting on it would stall every later go.
+    if (animation.effect?.getComputedTiming().endTime === Number.POSITIVE_INFINITY) {
+      continue;
+    }
+    if (animation.finished) {
+      tasks.push(animation.finished.catch(() => undefined));
+    }
+  }
+  if (tasks.length > 0) {
+    await Promise.all(tasks);
+  }
+}

package/src/runtime/slide.d.ts

@@ -0,0 +1,28 @@
+// Types for slide scripts, slides/<id>.ts. Generated by dek; `dekc sync` rewrites it.
+//
+//   export default { motion: { growth: 900 }, draw(slide, { t }) {} } satisfies DekSlide;
+
+export {};
+
+declare global {
+  /** What `draw` receives for one frame of a beat. */
+  interface DekMotionFrame {
+    /** Beats reached on the slide: 0 as it arrives, k at its k-th beat. */
+    index: number;
+    /** "0" as the slide arrives; at a beat, its id or 1-based position, the values `data-step` takes. */
+    step: string;
+    /** Milliseconds since the beat began, from 0 up to the beat's `motion`. */
+    t: number;
+  }
+
+  /** The default export of a slide script. */
+  interface DekSlide {
+    /** Milliseconds of motion per beat, keyed like `step`. A beat without an entry is drawn once, at t = 0. */
+    motion?: Record<string, number>;
+    /**
+     * Draws the slide at `t`. The runtime owns the clock: video and screenshots seek it,
+     * so draw from `t` alone and set everything you touch on every call.
+     */
+    draw?(slide: HTMLElement, frame: DekMotionFrame): void;
+  }
+}

package/src/runtime/socket.ts

@@ -0,0 +1,143 @@
+import {
+  decodePointer,
+  decodePosition,
+  encodePointer,
+  encodePosition,
+  type Pointer,
+} from "../core/live-protocol.ts";
+import { positionsEqual } from "../core/position.ts";
+import type { Position } from "../core/step.ts";
+
+const RECONNECT_BASE_MS = 500;
+export const RECONNECT_MAX_MS = 10_000;
+
+/**
+ * How long to wait before reconnect `attempt` (from 0): doubling from half a second up to a cap,
+ * then cut by a random share of up to half, so the phones a Wi-Fi drop cut off together do not
+ * all come back in the same instant.
+ */
+export function reconnectDelay(attempt: number, random: () => number = Math.random): number {
+  const ceiling = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** attempt);
+  return ceiling / 2 + (random() * ceiling) / 2;
+}
+
+/** The part of a WebSocket the deck uses. */
+export type SocketLike = {
+  readyState: number;
+  send(data: string): void;
+  close(): void;
+  addEventListener(
+    type: "open" | "message" | "close",
+    listener: (event: { data?: unknown }) => void,
+  ): void;
+};
+
+const OPEN = 1;
+
+export type PositionSocket = {
+  /** Tell the server where the deck is headed; kept for the next connection while offline. */
+  publish(position: Position): void;
+  /**
+   * Tell the server where the laser points, or null once it went away. Dropped while offline:
+   * a point is stale by the time the line is back, and the next move of the hand sends a new one.
+   */
+  point(pointer: Pointer | null): void;
+  /** Close for good: no reconnect follows. */
+  close(): void;
+};
+
+/**
+ * The deck's line to the server, which relays positions between the presenter, the audience,
+ * and a phone remote, and where the presenter's laser points. Like an EventSource, it reconnects by itself after a drop (a restarted
+ * server, a Wi-Fi blip), backing off with `reconnectDelay`, until `close`.
+ *
+ * On reconnect the server greets with the last position it holds, and the deck follows it, having
+ * missed whatever moved meanwhile. A move this deck made while away is sent instead, and that
+ * greeting, if it is still where the deck was when the line dropped, is stale and passed over.
+ */
+export function createPositionSocket(options: {
+  connect: () => SocketLike;
+  onPosition: (position: Position) => void;
+  /** Where a presenter's laser points, or null once it went away. */
+  onPointer?: (pointer: Pointer | null) => void;
+  setTimer: (fn: () => void, ms: number) => number;
+  clearTimer: (id: number) => void;
+  random?: () => number;
+}): PositionSocket {
+  let socket: SocketLike | undefined;
+  let timer: number | undefined;
+  let attempt = 0;
+  let closed = false;
+  /** Where the server and this deck last agreed the deck was. */
+  let synced: Position | undefined;
+  /** The latest move made while the line was down. */
+  let unsent: Position | undefined;
+  /** A greeting to pass over: the server's position from before `unsent`. */
+  let stale: Position | undefined;
+
+  const connect = (): void => {
+    timer = undefined;
+    const current = options.connect();
+    socket = current;
+    current.addEventListener("open", () => {
+      attempt = 0;
+      if (unsent) {
+        current.send(encodePosition(unsent));
+        stale = synced;
+        synced = unsent;
+        unsent = undefined;
+      }
+    });
+    current.addEventListener("message", (event) => {
+      const laser = decodePointer(event.data);
+      if (laser) {
+        options.onPointer?.(laser.pointer);
+        return;
+      }
+      const position = decodePosition(event.data);
+      if (!position) {
+        return;
+      }
+      const skip = stale !== undefined && positionsEqual(stale, position);
+      stale = undefined;
+      if (skip) {
+        return;
+      }
+      synced = position;
+      options.onPosition(position);
+    });
+    current.addEventListener("close", () => {
+      if (closed || socket !== current) {
+        return;
+      }
+      socket = undefined;
+      timer = options.setTimer(connect, reconnectDelay(attempt++, options.random));
+    });
+  };
+  connect();
+
+  return {
+    publish(position) {
+      if (socket?.readyState === OPEN) {
+        socket.send(encodePosition(position));
+        synced = position;
+      } else {
+        unsent = position;
+      }
+    },
+    point(pointer) {
+      if (socket?.readyState === OPEN) {
+        socket.send(encodePointer(pointer));
+      }
+    },
+    close() {
+      closed = true;
+      if (timer !== undefined) {
+        options.clearTimer(timer);
+        timer = undefined;
+      }
+      socket?.close();
+      socket = undefined;
+    },
+  };
+}

package/src/runtime/stage.ts

@@ -0,0 +1,259 @@
+/// <reference lib="dom" />
+import { PAGE_ID } from "../core/page.ts";
+
+import { advance, type DeckStops, positionsEqual } from "../core/position.ts";
+import type { PresenterSlide } from "../core/presenter-state.ts";
+import { lastStop, type Position, stepKey, stepValuesForBeat } from "../core/step.ts";
+import { fitStage } from "./fit.ts";
+import { slideSelector } from "./live.ts";
+import { createMotion, drawAtEnd, type MotionMode, type SlideModule } from "./motion.ts";
+import { waitForPlaybackSettle } from "./settle.ts";
+import { applyIsShown, applyMorphNames, clearMorphNames, shouldUseViewTransition } from "./step.ts";
+import type { DekMotionHandle } from "./window.ts";
+
+export type Stage = {
+  slideEl(slug: string | undefined): HTMLElement | undefined;
+  /** Mark the slide at `pos` current and show its beats. */
+  render(pos: Position): void;
+  /** Draw the script of the slide at `pos`. Only the live element animates. */
+  showMotion(pos: Position, mode: MotionMode): void;
+  /** Play the step from `from` to `to` when it is one beat forward; else jump to its end. */
+  showMove(from: Position, to: Position): void;
+  /** Draw a clone of `slide` as it stands at `beatIndex`, with no animation. */
+  drawStill(clone: HTMLElement, slide: PresenterSlide, beatIndex: number): void;
+  /** Run `apply` inside a view transition when the slide changes, and wait until it plays out. */
+  present(from: Position, to: Position, apply: () => void): Promise<void>;
+  /** Cut the running move short: a newer one is waiting, and the presenter should not. */
+  hurry(): void;
+  /** Tell a screen reader which slide `pos` is on. */
+  announce(pos: Position): void;
+  /** Give each slide a page at its last beat while printing; `pos` is drawn again after. */
+  setPrinting(on: boolean, pos: Position): void;
+  /** Fit the deck to its stage. */
+  fit(): void;
+  /** What the video recorder seeks. */
+  motion: DekMotionHandle;
+};
+
+/** How the script draws a move: one beat forward animates, anything else jumps to its end. */
+export function motionModeFor(
+  from: Position,
+  to: Position,
+  deck: DeckStops,
+  env: { videoMode: boolean; reducedMotion: boolean },
+): MotionMode {
+  if (env.videoMode) {
+    return "hold";
+  }
+  if (env.reducedMotion) {
+    return "final";
+  }
+  const stepped = advance(from, deck);
+  return stepped && positionsEqual(stepped, to) ? "animate" : "final";
+}
+
+/** What a screen reader hears on arriving at `pos`. */
+export function announcement(
+  slides: ReadonlyArray<{ title: string }>,
+  pos: Position,
+): string | undefined {
+  const slide = slides[pos.slideIndex];
+  return slide ? `Slide ${pos.slideIndex + 1} of ${slides.length}: ${slide.title}` : undefined;
+}
+
+/** Only a running animation with an end can be finished; an endless one would throw. */
+export function isFinishable(animation: {
+  playState: string;
+  effect: { getComputedTiming(): { endTime?: unknown } } | null;
+}): boolean {
+  const end = animation.effect?.getComputedTiming().endTime;
+  return animation.playState === "running" && typeof end === "number" && Number.isFinite(end);
+}
+
+const slideModules = (): Record<string, SlideModule> => window.__dekSlides ?? {};
+
+function slideEl(slug: string | undefined): HTMLElement | undefined {
+  if (!slug) {
+    return undefined;
+  }
+  return document.querySelector<HTMLElement>(slideSelector(slug)) ?? undefined;
+}
+
+function prefersReducedMotion(): boolean {
+  return matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+const morphEls = (el: Element): HTMLElement[] => [
+  ...el.querySelectorAll<HTMLElement>("[data-morph]"),
+];
+
+function drawStill(clone: HTMLElement, slide: PresenterSlide, beatIndex: number): void {
+  drawAtEnd(slideModules()[slide.slug], clone, beatIndex, stepKey(slide.beats, beatIndex));
+}
+
+/** Read the slides afresh on each draw: live reload may have swapped one. */
+function renderSlides(slides: PresenterSlide[], pos: Position): void {
+  const slideEls = [...document.querySelectorAll("#deck > .slide")];
+  const current = slides[pos.slideIndex];
+  const currentEl = slideEl(current?.slug);
+  for (const el of slideEls) {
+    el.classList.toggle("is-current", el === currentEl);
+  }
+  const shown = current ? stepValuesForBeat(current.beats, pos.beatIndex) : new Set<string>();
+  if (currentEl) {
+    applyIsShown([...currentEl.querySelectorAll("[data-step]")], shown);
+    applyMorphNames(morphEls(currentEl));
+  }
+  for (const el of slideEls) {
+    if (el !== currentEl) {
+      clearMorphNames(morphEls(el));
+    }
+  }
+}
+
+/** Each slide at its last beat, as `dekc pdf` gives it a page. */
+function drawPrintPages(slides: PresenterSlide[]): void {
+  for (const slide of slides) {
+    const el = slideEl(slide.slug);
+    if (el) {
+      const last = lastStop(slide.beats);
+      applyIsShown([...el.querySelectorAll("[data-step]")], stepValuesForBeat(slide.beats, last));
+      drawStill(el, slide, last);
+    }
+  }
+}
+
+/**
+ * Start a view transition that runs `apply` when the move changes slide and the browser and
+ * viewer allow one; else run `apply` now.
+ */
+function startTransition(
+  slides: PresenterSlide[],
+  from: Position,
+  to: Position,
+  apply: () => void,
+): ViewTransition | undefined {
+  if (
+    !shouldUseViewTransition(from.slideIndex, to.slideIndex) ||
+    !("startViewTransition" in document) ||
+    prefersReducedMotion()
+  ) {
+    apply();
+    return undefined;
+  }
+  const fromEl = slideEl(slides[from.slideIndex]?.slug);
+  if (fromEl) {
+    applyMorphNames(morphEls(fromEl));
+  }
+  return document.startViewTransition(apply);
+}
+
+function finishAnimations(): void {
+  for (const animation of document.getAnimations()) {
+    if (isFinishable(animation)) {
+      animation.finish();
+    }
+  }
+}
+
+function fitDeck(): void {
+  const deckEl = document.getElementById(PAGE_ID.deck);
+  const currentStage = document.getElementById(PAGE_ID.currentStage);
+  if (deckEl instanceof HTMLElement && currentStage) {
+    fitStage(deckEl, currentStage);
+  }
+}
+
+/** Owns the deck's slides on screen: which is current, its beats, morphs, script, and print. */
+export function createStage(options: {
+  slides: PresenterSlide[];
+  deck: DeckStops;
+  videoMode: boolean;
+}): Stage {
+  const { slides, videoMode } = options;
+  const motion = createMotion({
+    now: () => performance.now(),
+    requestFrame: (fn) => requestAnimationFrame(fn),
+    cancelFrame: (id) => cancelAnimationFrame(id),
+    setTimer: (fn, ms) => window.setTimeout(fn, ms),
+    clearTimer: (id) => window.clearTimeout(id),
+  });
+  let inFlight: { skipTransition(): void } | undefined;
+  let printing = false;
+
+  function showMotion(pos: Position, mode: MotionMode): void {
+    const current = slides[pos.slideIndex];
+    const el = slideEl(current?.slug);
+    if (!current || !el) {
+      motion.stop();
+      return;
+    }
+    motion.show(el, slideModules()[current.slug], current.beats, pos.beatIndex, mode);
+  }
+
+  async function present(from: Position, to: Position, apply: () => void): Promise<void> {
+    const viewTransition = startTransition(slides, from, to, apply);
+    if (viewTransition) {
+      inFlight = viewTransition;
+    }
+    try {
+      await waitForPlaybackSettle({ animations: [...document.getAnimations()], viewTransition });
+    } finally {
+      inFlight = undefined;
+    }
+  }
+
+  /**
+   * Print gives each slide a page at its last beat, as `dekc pdf` does, so each slide's script
+   * draws that beat's end the way the PDF page draws it. Once printed, the stage draws its own
+   * beat again. The browser tells of a print twice (beforeprint and the print media query), and
+   * a PDF export only the second way; each change is drawn once.
+   */
+  function setPrinting(on: boolean, pos: Position): void {
+    if (on === printing) {
+      return;
+    }
+    printing = on;
+    if (on) {
+      motion.stop();
+      drawPrintPages(slides);
+    } else {
+      renderSlides(slides, pos);
+      showMotion(pos, "final");
+    }
+  }
+
+  return {
+    slideEl,
+    render: (pos) => renderSlides(slides, pos),
+    showMotion,
+    showMove: (from, to) =>
+      showMotion(
+        to,
+        motionModeFor(from, to, options.deck, { videoMode, reducedMotion: prefersReducedMotion() }),
+      ),
+    drawStill,
+    present,
+    hurry() {
+      if (videoMode) {
+        return;
+      }
+      inFlight?.skipTransition();
+      finishAnimations();
+    },
+    /** Beats within a slide pass quietly. */
+    announce(pos) {
+      const el = document.getElementById(PAGE_ID.announce);
+      const text = announcement(slides, pos);
+      if (el && text !== undefined) {
+        el.textContent = text;
+      }
+    },
+    setPrinting,
+    fit: fitDeck,
+    motion: {
+      duration: () => motion.duration(),
+      seek: (t: number) => motion.seek(t),
+    },
+  };
+}

package/src/runtime/step.ts

@@ -0,0 +1,139 @@
+import type { Move } from "../core/position.ts";
+
+export type StepElement = {
+  getAttribute(name: string): string | null;
+  classList: { toggle(name: string, force?: boolean): void };
+};
+
+export type MorphElement = {
+  getAttribute(name: string): string | null;
+  style: { setProperty(name: string, value: string): void; removeProperty(name: string): string };
+};
+
+export function applyIsShown(elements: StepElement[], shown: Set<string>): void {
+  for (const el of elements) {
+    const step = el.getAttribute("data-step");
+    el.classList.toggle("is-shown", step !== null && shown.has(step));
+  }
+}
+
+export type MoveKey = {
+  key: string;
+  shiftKey?: boolean;
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+};
+
+/**
+ * The move a key asks for. Clickers send the arrow and page keys; Space goes forward and
+ * Shift+Space back, as on a web page. Chords with Alt, Ctrl, or Cmd belong to the browser
+ * (Alt+← is Back), so they never move the deck.
+ */
+export function keyToMove(event: MoveKey): Move | null {
+  if (event.altKey || event.ctrlKey || event.metaKey) {
+    return null;
+  }
+  switch (event.key) {
+    case " ":
+      return event.shiftKey ? "retreat" : "advance";
+    case "ArrowRight":
+    case "PageDown":
+      return "advance";
+    case "ArrowLeft":
+    case "PageUp":
+    case "Backspace":
+      return "retreat";
+    case "Home":
+      return "first";
+    case "End":
+      return "last";
+    default:
+      return null;
+  }
+}
+
+/**
+ * Whether `event` is the bare letter key `letter`, either case: no Alt, Ctrl, or Cmd, which
+ * belong to the browser, and no auto-repeat, which would toggle on and off while held.
+ */
+export function isLetterKey(
+  event: { key: string; altKey: boolean; ctrlKey: boolean; metaKey: boolean; repeat?: boolean },
+  letter: string,
+): boolean {
+  if (event.repeat || event.altKey || event.ctrlKey || event.metaKey) {
+    return false;
+  }
+  return event.key.toLowerCase() === letter;
+}
+
+/** A finished touch on the slide: where it lifted, and how far it travelled from where it began. */
+export type PointerStroke = { x: number; y: number; dx: number; dy: number };
+
+/**
+ * The move a touch or a click asks for. A tap or click goes forward, except on the left third,
+ * which goes back. A swipe turns the page as a book does (leftward goes forward), but only by
+ * touch or pen: a mouse drag is selecting text. Anything between, such as a vertical scroll or
+ * a short drag, is not a move.
+ */
+export function pointerMove(
+  stroke: PointerStroke,
+  stage: { width: number },
+  pointerType = "touch",
+): Move | null {
+  const ax = Math.abs(stroke.dx);
+  const ay = Math.abs(stroke.dy);
+  if (pointerType !== "mouse" && ax >= SWIPE_MIN_PX && ax > ay * 2) {
+    return stroke.dx < 0 ? "advance" : "retreat";
+  }
+  if (ax < TAP_MAX_PX && ay < TAP_MAX_PX) {
+    return stroke.x < stage.width / 3 ? "retreat" : "advance";
+  }
+  return null;
+}
+
+const SWIPE_MIN_PX = 60;
+const TAP_MAX_PX = 10;
+
+/** Whether a touch on `target` belongs to it (a link, a control, media) rather than to the deck. */
+export function isInteractive(target: unknown): boolean {
+  const el = target as { closest?: (selector: string) => unknown } | null;
+  return typeof el?.closest === "function" && el.closest(INTERACTIVE) !== null;
+}
+
+const INTERACTIVE =
+  "a[href], button, input, textarea, select, label, summary, video, audio, [contenteditable]";
+
+/** Whether keys pressed on `target` are typing: a field or editable text on a slide. */
+export function isTextEntry(target: unknown): boolean {
+  if (typeof target !== "object" || target === null) {
+    return false;
+  }
+  const el = target as { tagName?: unknown; isContentEditable?: unknown };
+  return (
+    el.isContentEditable === true ||
+    el.tagName === "INPUT" ||
+    el.tagName === "TEXTAREA" ||
+    el.tagName === "SELECT"
+  );
+}
+
+export function applyMorphNames(elements: MorphElement[]): void {
+  for (const el of elements) {
+    const name = el.getAttribute("data-morph");
+    if (name) {
+      // The browser reads the CSS property; an attribute of the same name does nothing.
+      el.style.setProperty("view-transition-name", name);
+    }
+  }
+}
+
+export function clearMorphNames(elements: MorphElement[]): void {
+  for (const el of elements) {
+    el.style.removeProperty("view-transition-name");
+  }
+}
+
+export function shouldUseViewTransition(fromSlide: number, toSlide: number): boolean {
+  return fromSlide !== toSlide;
+}

package/src/runtime/window.ts

@@ -0,0 +1,38 @@
+import type { Position } from "../core/step.ts";
+
+/** How capture tools seek the current slide's script, the way they seek Web Animations. */
+export type DekMotionHandle = {
+  /** The current beat's motion in ms; 0 when the slide has none. */
+  duration(): number;
+  seek(t: number): void;
+};
+
+/**
+ * What the player shares through `window` with code outside its bundle: the
+ * video recorder and morph shots (run by Playwright), live reload, and the
+ * slide scripts that register themselves before the player starts.
+ */
+declare global {
+  interface Window {
+    dekGo?: (next: Position | null | undefined) => Promise<void>;
+    dekMotion?: DekMotionHandle;
+    dekLive?: (raw: unknown) => Promise<void>;
+    /** The go the video recorder started and has not awaited yet. */
+    __dekPendingGo?: Promise<void>;
+    /** The animations that go started, so capture tools seek those and nothing older. */
+    __dekStarted?: Animation[];
+    /** The animations the last finished beat ended; the next go did not start them. */
+    __dekSettled?: Set<Animation>;
+    __dekSlides?: Record<string, DekSlide>;
+    /** What each slide's draw threw on a still page, for the worker that measures it. */
+    __dekDrawErrors?: Array<{
+      slug: string;
+      step: string;
+      t: number;
+      kind: "throw" | "reach" | "seek";
+      message: string;
+    }>;
+    /** Takes back what the draws on a still page changed in attributes; absent when nothing. */
+    __dekUndoDraw?: () => void;
+  }
+}