@hajimism/dek 0.1.0

package/src/runtime/rail-view.ts

@@ -0,0 +1,229 @@
+/// <reference lib="dom" />
+import { PAGE_ID } from "../core/page.ts";
+
+import type { PresenterSlide } from "../core/presenter-state.ts";
+import { lastStop } from "../core/step.ts";
+import { deckSize, stillFrame, visualClone } from "./clone.ts";
+import { fitStage } from "./fit.ts";
+import {
+  clampRailWidth,
+  pageStorage,
+  RAIL_VISIBLE_KEY,
+  RAIL_WIDTH_KEY,
+  RAIL_WIDTH_STEP,
+  readStoredRailVisible,
+  readStoredRailWidth,
+} from "./rail.ts";
+import type { Stage } from "./stage.ts";
+
+export type RailView = {
+  /** Whether the page has a rail. */
+  available(): boolean;
+  isOpen(): boolean;
+  setOpen(open: boolean): void;
+  /** Draw every thumbnail again from its slide. */
+  fill(): void;
+  fit(): void;
+  /** Mark the thumbnail of slide `slideIndex` current and scroll it into view. */
+  markCurrent(slideIndex: number): void;
+};
+
+/** Which way an arrow key on a thumbnail moves along the rail. */
+export function thumbStep(key: string): 1 | -1 | undefined {
+  if (key === "ArrowDown") {
+    return 1;
+  }
+  return key === "ArrowUp" ? -1 : undefined;
+}
+
+/** How far an arrow key on the resize handle moves the rail's edge. */
+export function resizeStep(key: string): number | undefined {
+  if (key === "ArrowRight") {
+    return RAIL_WIDTH_STEP;
+  }
+  return key === "ArrowLeft" ? -RAIL_WIDTH_STEP : undefined;
+}
+
+function persist(key: string, value: string): void {
+  try {
+    pageStorage()?.setItem(key, value);
+  } catch {
+    // file:// or private mode may reject storage
+  }
+}
+
+function setWidth(handle: HTMLElement | null, px: number): number {
+  const width = clampRailWidth(px);
+  document.documentElement.style.setProperty("--dek-rail-w", `${width}px`);
+  handle?.setAttribute("aria-valuenow", String(width));
+  return width;
+}
+
+function fillThumbs(railEl: HTMLElement, slides: PresenterSlide[], stage: Stage): void {
+  const deckEl = document.getElementById(PAGE_ID.deck);
+  if (!deckEl) {
+    return;
+  }
+  const size = deckSize(deckEl);
+  for (const [index, slide] of slides.entries()) {
+    const frame = railEl.querySelector(`[data-slide-index="${index}"] .dek-thumb-frame`);
+    if (!(frame instanceof HTMLElement)) {
+      continue;
+    }
+    const source = stage.slideEl(slide.slug);
+    const clone = source ? visualClone(source) : undefined;
+    if (!clone) {
+      frame.replaceChildren();
+      continue;
+    }
+    const thumbStage = stillFrame("dek-thumb-stage", clone, size);
+    frame.replaceChildren(thumbStage);
+    // Drawn once in the document, so a script that measures its slide gets real boxes. The
+    // rail shows every beat's elements, so the script draws the last beat to match them.
+    stage.drawStill(clone, slide, lastStop(slide.beats));
+    fitStage(thumbStage, frame);
+  }
+}
+
+function fitThumbs(railEl: HTMLElement): void {
+  if (railEl.offsetParent === null) {
+    return;
+  }
+  for (const frame of railEl.querySelectorAll(".dek-thumb-frame")) {
+    const thumbStage = frame.querySelector(".dek-thumb-stage");
+    if (frame instanceof HTMLElement && thumbStage instanceof HTMLElement) {
+      fitStage(thumbStage, frame);
+    }
+  }
+}
+
+function markCurrent(railEl: HTMLElement, slideIndex: number): void {
+  for (const el of railEl.querySelectorAll(".dek-thumb")) {
+    const current = Number(el.getAttribute("data-slide-index")) === slideIndex;
+    el.classList.toggle("is-current", current);
+    if (current) {
+      el.setAttribute("aria-current", "page");
+      el.scrollIntoView({ block: "nearest" });
+    } else {
+      el.removeAttribute("aria-current");
+    }
+  }
+}
+
+/** Arrow keys on a thumbnail pick the slide next to it, and focus follows. */
+function bindThumbKeys(
+  railEl: HTMLElement,
+  slides: PresenterSlide[],
+  onPick: (slideIndex: number) => void,
+): void {
+  railEl.addEventListener("keydown", (event) => {
+    const step = thumbStep(event.key);
+    const thumb = event.target;
+    if (!step || !(thumb instanceof HTMLElement) || !thumb.classList.contains("dek-thumb")) {
+      return;
+    }
+    event.preventDefault();
+    event.stopPropagation();
+    const nextIndex = Number(thumb.getAttribute("data-slide-index")) + step;
+    if (!slides[nextIndex]) {
+      return;
+    }
+    onPick(nextIndex);
+    railEl
+      .querySelector<HTMLElement>(`[data-slide-index="${nextIndex}"]`)
+      ?.focus({ preventScroll: true });
+  });
+}
+
+function bindResizeKeys(handle: HTMLElement, onResize: () => void): void {
+  handle.addEventListener("keydown", (event) => {
+    const step = resizeStep(event.key);
+    if (!step) {
+      return;
+    }
+    // The arrows resize the rail here; they must not also move the deck.
+    event.preventDefault();
+    event.stopPropagation();
+    const now = Number(handle.getAttribute("aria-valuenow"));
+    persist(RAIL_WIDTH_KEY, String(setWidth(handle, now + step)));
+    onResize();
+  });
+}
+
+/** The rail follows the pointer while it drags, and remembers the width where it lets go. */
+function bindResizeDrag(handle: HTMLElement, onResize: () => void): void {
+  handle.addEventListener("pointerdown", (event) => {
+    event.preventDefault();
+    try {
+      handle.setPointerCapture(event.pointerId);
+    } catch {
+      // synthetic events may not support capture
+    }
+    handle.setAttribute("data-dragging", "");
+    let width = setWidth(handle, event.clientX);
+    const move = (ev: PointerEvent): void => {
+      width = setWidth(handle, ev.clientX);
+      onResize();
+    };
+    const up = (): void => {
+      handle.removeEventListener("pointermove", move);
+      handle.removeEventListener("pointerup", up);
+      handle.removeEventListener("pointercancel", up);
+      handle.removeAttribute("data-dragging");
+      persist(RAIL_WIDTH_KEY, String(width));
+    };
+    handle.addEventListener("pointermove", move);
+    handle.addEventListener("pointerup", up);
+    handle.addEventListener("pointercancel", up);
+  });
+}
+
+/**
+ * Owns the slide rail: its thumbnails, its width, and whether it shows. Arrow keys on a thumbnail
+ * pick the slide next to it; `onResize` hears each width change, since the deck fits around it.
+ */
+export function createRailView(options: {
+  slides: PresenterSlide[];
+  stage: Stage;
+  onPick: (slideIndex: number) => void;
+  onResize: () => void;
+}): RailView {
+  const railEl = document.getElementById(PAGE_ID.rail);
+  const resizeEl = document.getElementById(PAGE_ID.railResize);
+
+  if (railEl) {
+    setWidth(resizeEl, readStoredRailWidth(pageStorage()));
+    // What was remembered; the deck is fitted once everything is built.
+    document.body.classList.toggle("is-rail-hidden", !readStoredRailVisible(pageStorage()));
+    bindThumbKeys(railEl, options.slides, options.onPick);
+    if (resizeEl) {
+      bindResizeKeys(resizeEl, options.onResize);
+      bindResizeDrag(resizeEl, options.onResize);
+    }
+  }
+
+  return {
+    available: () => railEl !== null,
+    isOpen: () => !document.body.classList.contains("is-rail-hidden"),
+    setOpen(open) {
+      document.body.classList.toggle("is-rail-hidden", !open);
+      persist(RAIL_VISIBLE_KEY, open ? "1" : "0");
+      options.onResize();
+    },
+    fill() {
+      if (railEl) {
+        fillThumbs(railEl, options.slides, options.stage);
+      }
+    },
+    fit() {
+      if (railEl) {
+        fitThumbs(railEl);
+      }
+    },
+    markCurrent(slideIndex) {
+      if (railEl) {
+        markCurrent(railEl, slideIndex);
+      }
+    },
+  };
+}

package/src/runtime/rail.ts

@@ -0,0 +1,52 @@
+import { RAIL_WIDTH_DEFAULT, RAIL_WIDTH_MAX, RAIL_WIDTH_MIN } from "../core/rail-width.ts";
+import { isLetterKey } from "./step.ts";
+
+export const RAIL_WIDTH_KEY = "dek.railWidth";
+export const RAIL_VISIBLE_KEY = "dek.railVisible";
+
+export function isRailToggleKey(event: Parameters<typeof isLetterKey>[0]): boolean {
+  return isLetterKey(event, "s");
+}
+
+/** How far one arrow key press moves the rail's resize handle. */
+export const RAIL_WIDTH_STEP = 16;
+
+/**
+ * The page's localStorage, or undefined where reading it throws: a file opened with storage
+ * blocked, or a sandboxed frame. The rail remembers less there; the deck still runs.
+ */
+export function pageStorage(): Storage | undefined {
+  try {
+    return window.localStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+export function clampRailWidth(px: number): number {
+  if (!Number.isFinite(px)) {
+    return RAIL_WIDTH_DEFAULT;
+  }
+  return Math.max(RAIL_WIDTH_MIN, Math.min(RAIL_WIDTH_MAX, Math.round(px)));
+}
+
+export function readStoredRailWidth(
+  storage: { getItem(key: string): string | null } | undefined,
+): number {
+  try {
+    const raw = storage?.getItem(RAIL_WIDTH_KEY);
+    return raw ? clampRailWidth(Number(raw)) : RAIL_WIDTH_DEFAULT;
+  } catch {
+    return RAIL_WIDTH_DEFAULT;
+  }
+}
+
+export function readStoredRailVisible(
+  storage: { getItem(key: string): string | null } | undefined,
+): boolean {
+  try {
+    return storage?.getItem(RAIL_VISIBLE_KEY) !== "0";
+  } catch {
+    return true;
+  }
+}

package/src/runtime/rehearse.ts

@@ -0,0 +1,264 @@
+import { comparePositions, positionsEqual } from "../core/position.ts";
+import type { Position } from "../core/step.ts";
+import { playbackSchedule, type ScheduledGo, type Timeline } from "../core/timeline.ts";
+import type { RequestOrigin } from "./deck-control.ts";
+import type { GoOrigin } from "./navigator.ts";
+import { deckUrl } from "./routes.ts";
+
+export type RehearseDriver = {
+  play: () => void;
+  pause: () => void;
+  /** Move the clock to `position`; the caller moves the deck. */
+  seek: (position: Position) => void;
+  stop: () => void;
+  playing: () => boolean;
+  elapsed: () => number;
+};
+
+/** The latest entry whose time has come by `at` ms. */
+export function lastDue(schedule: ScheduledGo[], at: number): ScheduledGo | undefined {
+  return schedule.findLast((entry) => entry.at <= at);
+}
+
+/** The entry for `position`, or the last one before it when the timeline skips that stop. */
+export function entryFor(schedule: ScheduledGo[], position: Position): ScheduledGo | undefined {
+  return (
+    schedule.find((entry) => positionsEqual(entry.position, position)) ??
+    schedule.findLast((entry) => comparePositions(entry.position, position) < 0)
+  );
+}
+
+/**
+ * The rehearsal clock: it walks the deck through `schedule` as time passes. Only the clock's own
+ * moves go through `go`; a seek answers a move someone else already made.
+ */
+export function createRehearseDriver(options: {
+  schedule: ScheduledGo[];
+  go: (position: Position) => void | Promise<void>;
+  now?: () => number;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (id: unknown) => void;
+  onPlay?: () => void;
+  onPause?: () => void;
+  onSeek?: (ms: number) => void;
+}): RehearseDriver {
+  const now = options.now ?? (() => Date.now());
+  const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer =
+    options.clearTimer ?? ((id) => clearTimeout(id as ReturnType<typeof setTimeout>));
+  const timers = new Set<unknown>();
+  let playing = false;
+  let origin = 0;
+  let pausedElapsed = 0;
+  /** The entry the deck stands on as far as the clock knows. */
+  let shown: ScheduledGo | undefined;
+
+  const elapsed = (): number => (playing ? now() - origin : pausedElapsed);
+
+  const clear = (): void => {
+    for (const id of timers) {
+      clearTimer(id);
+    }
+    timers.clear();
+  };
+
+  const arm = (): void => {
+    clear();
+    const t = elapsed();
+    for (const event of options.schedule) {
+      const wait = event.at - t;
+      if (wait <= 0) {
+        continue;
+      }
+      const id = setTimer(() => {
+        timers.delete(id);
+        shown = event;
+        void options.go(event.position);
+      }, wait);
+      timers.add(id);
+    }
+  };
+
+  return {
+    play() {
+      if (playing) {
+        return;
+      }
+      playing = true;
+      origin = now() - pausedElapsed;
+      options.onPlay?.();
+      const due = lastDue(options.schedule, pausedElapsed);
+      if (due && due !== shown) {
+        shown = due;
+        void options.go(due.position);
+      }
+      arm();
+    },
+    pause() {
+      if (!playing) {
+        return;
+      }
+      pausedElapsed = elapsed();
+      playing = false;
+      options.onPause?.();
+      clear();
+    },
+    seek(position) {
+      pausedElapsed = entryFor(options.schedule, position)?.at ?? 0;
+      shown = lastDue(options.schedule, pausedElapsed);
+      options.onSeek?.(pausedElapsed);
+      if (playing) {
+        origin = now() - pausedElapsed;
+        arm();
+      }
+    },
+    stop() {
+      playing = false;
+      pausedElapsed = 0;
+      shown = undefined;
+      clear();
+    },
+    playing: () => playing,
+    elapsed,
+  };
+}
+
+/** The slice of an audio element the rehearsal uses. */
+export type RehearseAudio = {
+  currentTime: number;
+  play(): Promise<void> | void;
+  pause(): void;
+};
+
+/** A loaded rehearsal: when each stop comes, and the voice track if there is one. */
+export type Rehearsal = { schedule: ScheduledGo[]; audio?: RehearseAudio };
+
+export type RehearseController = {
+  /** Whether a rehearsal is loaded and owns the keys. */
+  ready(): boolean;
+  /** Load the timeline, or load it again after it changed, and play from where the deck is. */
+  load(): Promise<void>;
+  toggle(): void;
+  /** Move the deck and the clock to `position`, asked for on this page or by a peer. */
+  move(position: Position, origin: RequestOrigin): void;
+};
+
+type RehearseState =
+  | { kind: "off" }
+  | { kind: "loading" }
+  | { kind: "ready"; driver: RehearseDriver; audio?: RehearseAudio };
+
+/** A clock for `rehearsal`; with a voice track, the track keeps the time and follows the clock. */
+function rehearsalDriver(
+  { schedule, audio }: Rehearsal,
+  go: (position: Position) => void | Promise<void>,
+): RehearseDriver {
+  return createRehearseDriver({
+    schedule,
+    go,
+    ...(audio ? { now: () => audio.currentTime * 1000 } : {}),
+    onPlay: () => {
+      void audio?.play();
+    },
+    onPause: () => {
+      audio?.pause();
+    },
+    onSeek: (ms) => {
+      if (audio) {
+        audio.currentTime = ms / 1000;
+      }
+    },
+  });
+}
+
+/**
+ * Owns the rehearsal: one state at a time, and the voice track with it. A reload stops the old
+ * clock and silences its track before anything new plays.
+ */
+export function createRehearseController(options: {
+  load: () => Promise<Rehearsal | undefined>;
+  /** Move the deck; the clock's own moves come as "rehearse". */
+  go: (position: Position, origin: GoOrigin) => void | Promise<void>;
+  /** Where the deck is headed, so a reload plays on from there. */
+  current: () => Position;
+}): RehearseController {
+  let state: RehearseState = { kind: "off" };
+  let generation = 0;
+
+  const stopCurrent = (): void => {
+    if (state.kind === "ready") {
+      state.driver.stop();
+      state.audio?.pause();
+    }
+  };
+
+  return {
+    ready: () => state.kind === "ready",
+    async load() {
+      generation += 1;
+      const mine = generation;
+      stopCurrent();
+      state = { kind: "loading" };
+      let loaded: Rehearsal | undefined;
+      try {
+        loaded = await options.load();
+      } catch (error) {
+        if (mine === generation) {
+          state = { kind: "off" };
+        }
+        throw error;
+      }
+      // A newer load started while this one waited; it owns the state now.
+      if (mine !== generation) {
+        return;
+      }
+      if (!loaded) {
+        state = { kind: "off" };
+        return;
+      }
+      const { audio } = loaded;
+      const driver = rehearsalDriver(loaded, (position) => options.go(position, "rehearse"));
+      state = audio ? { kind: "ready", driver, audio } : { kind: "ready", driver };
+      // Set the clock first: playing from zero would send the deck to the first slide.
+      driver.seek(options.current());
+      driver.play();
+    },
+    toggle() {
+      if (state.kind !== "ready") {
+        return;
+      }
+      if (state.driver.playing()) {
+        state.driver.pause();
+      } else {
+        state.driver.play();
+      }
+    },
+    move(position, origin) {
+      if (state.kind !== "ready") {
+        return;
+      }
+      state.driver.seek(position);
+      void options.go(position, origin);
+    },
+  };
+}
+
+/** Fetch the deck's timeline and, when the server has one, its voice track. */
+export async function fetchRehearsal(
+  pathname: string,
+  deps: {
+    fetch: (input: string, init?: { method: string }) => Promise<Response>;
+    audio: (src: string) => RehearseAudio;
+  },
+): Promise<Rehearsal | undefined> {
+  const timelinePath = deckUrl(pathname, { kind: "voice", file: "timeline.json" });
+  const audioPath = deckUrl(pathname, { kind: "voice", file: "audio.wav" });
+  const response = await deps.fetch(timelinePath);
+  if (!response.ok) {
+    return undefined;
+  }
+  const timeline = (await response.json()) as Timeline;
+  const audioHead = await deps.fetch(audioPath, { method: "HEAD" });
+  const schedule = playbackSchedule(timeline);
+  return audioHead.ok ? { schedule, audio: deps.audio(audioPath) } : { schedule };
+}

package/src/runtime/routes.ts

@@ -0,0 +1,142 @@
+/**
+ * The dev server's URL scheme, shared by the server that matches paths and the page that builds
+ * them. Everything a deck serves sits under `/decks/:name`, or at the root of a server scoped to
+ * that deck; `DeckRoute` is what follows that prefix.
+ */
+export type VoiceFile = "timeline.json" | "audio.wav";
+
+export type DeckRoute =
+  | { kind: "player" }
+  | { kind: "presenter" }
+  /** The position socket. */
+  | { kind: "socket" }
+  /** The live event stream. */
+  | { kind: "events" }
+  | { kind: "theme" }
+  | { kind: "slide"; slug: string }
+  | { kind: "voice"; file: VoiceFile }
+  /** `dekc current` and `dekc goto`. */
+  | { kind: "current" }
+  | { kind: "goto" }
+  /** The beats the presenter marked to rewrite: listed, and one marked or unmarked. */
+  | { kind: "marks" }
+  /** A file under the deck's `assets/`, decoded. */
+  | { kind: "asset"; path: string };
+
+type Fixed = Exclude<DeckRoute, { kind: "slide" | "voice" | "asset" }>["kind"];
+
+const FIXED: Record<Fixed, string> = {
+  player: "/",
+  presenter: "/presenter",
+  socket: "/ws",
+  events: "/events",
+  theme: "/theme",
+  current: "/current",
+  goto: "/goto",
+  marks: "/marks",
+};
+
+/** The path of `route` below its deck's prefix. */
+export function formatDeckRoute(route: DeckRoute): string {
+  switch (route.kind) {
+    case "slide":
+      return `/slide/${encodeURIComponent(route.slug)}`;
+    case "voice":
+      return `/voice/${route.file}`;
+    case "asset":
+      return `/assets/${route.path.split("/").map(encodeURIComponent).join("/")}`;
+    default:
+      return FIXED[route.kind];
+  }
+}
+
+/** The route `rest` names below a deck's prefix; a fixed path may end in a slash. */
+export function parseDeckRoute(rest: string): DeckRoute | undefined {
+  const bare = rest.length > 1 && rest.endsWith("/") ? rest.slice(0, -1) : rest || "/";
+  for (const [kind, path] of Object.entries(FIXED) as Array<[Fixed, string]>) {
+    if (bare === path) {
+      return { kind };
+    }
+  }
+  try {
+    const slug = rest.match(/^\/slide\/([^/]+)\/?$/)?.[1];
+    if (slug) {
+      return { kind: "slide", slug: decodeURIComponent(slug) };
+    }
+    const file = rest.match(/^\/voice\/(timeline\.json|audio\.wav)$/)?.[1];
+    if (file) {
+      return { kind: "voice", file: file as VoiceFile };
+    }
+    const asset = rest.match(/^\/assets\/(.+)$/)?.[1];
+    if (asset) {
+      return { kind: "asset", path: decodeURIComponent(asset) };
+    }
+  } catch {
+    // Malformed percent-encoding names nothing.
+  }
+  return undefined;
+}
+
+/** Where `route` is on a server that serves every deck, for the deck named `deckName`. */
+export function deckRoutePath(deckName: string, route: DeckRoute): string {
+  return `/decks/${encodeURIComponent(deckName)}${formatDeckRoute(route)}`;
+}
+
+/**
+ * `localPath` under the deck the page at `pathname` belongs to. `liveReloadScript` embeds this
+ * function's source, so it must stay self-contained.
+ */
+export function withDeckPrefix(pathname: string, localPath: string): string {
+  const deck = pathname.match(/^\/decks\/([^/]+)/)?.[1];
+  return deck ? `/decks/${deck}${localPath}` : localPath;
+}
+
+/** Where `route` is for the page at `pathname`. */
+export function deckUrl(pathname: string, route: DeckRoute): string {
+  return withDeckPrefix(pathname, formatDeckRoute(route));
+}
+
+/** Inverse of `withDeckPrefix`: `/decks/:name/rest` or a scoped local path, the name decoded. */
+export function splitDeckPath(
+  pathname: string,
+  scopedDeckName?: string,
+): { deckName: string; rest: string } | undefined {
+  const prefixed = pathname.match(/^\/decks\/([^/]+)(\/.*)?$/);
+  if (prefixed?.[1]) {
+    const deckName = decodeSegment(prefixed[1]);
+    // A server scoped to one deck shares that deck, not the rest of the project.
+    if (deckName === undefined || (scopedDeckName !== undefined && deckName !== scopedDeckName)) {
+      return undefined;
+    }
+    return { deckName, rest: prefixed[2] ?? "/" };
+  }
+  if (!scopedDeckName) {
+    return undefined;
+  }
+  return { deckName: scopedDeckName, rest: pathname };
+}
+
+function decodeSegment(segment: string): string | undefined {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The query a live channel carries for the presenter's token, or nothing on an audience page.
+ * `liveReloadScript` embeds this function's source, so it must stay self-contained.
+ */
+export function liveTokenQuery(token: string | undefined): string {
+  return token ? `?token=${encodeURIComponent(token)}` : "";
+}
+
+/**
+ * The BroadcastChannel a deck's windows share. Built files share one origin under `file://`,
+ * so the name carries the deck and its slides: an audience view and a presenter view of one
+ * deck follow each other, and two decks open side by side do not.
+ */
+export function deckChannelName(deck: string | undefined, slugs: readonly string[]): string {
+  return `dek:${deck ?? ""}:${slugs.join(",")}`;
+}