@hajimism/dek 0.5.0 → 0.6.0

package/src/runtime/plugins.ts

@@ -0,0 +1,236 @@
+/// <reference lib="dom" />
+
+import { PAGE_ID } from "../core/page.ts";
+import type { Position } from "../core/step.ts";
+import type { DekPage, PageApi, PageMount, PagePosition } from "../plugin-api.ts";
+import { isLetterKey, isTextEntry } from "./step.ts";
+
+/**
+ * Page API 1 (ADR 33): `window.dek.plugin`, which a plugin's page calls once it runs, after the
+ * player. Each plugin gets a layer over every slide, in the slide's own pixels, kept in `#deck`
+ * beside the slides so that it scales and moves with them, and is captured with them in a view
+ * transition, while a slide's own markup, which lint checked, is never touched.
+ */
+
+/** What the page carries for each plugin: its declared keys and its data files. */
+type PluginConfig = Record<
+  string,
+  { keys: string[]; data: Record<string, { text: string; version: string }> }
+>;
+
+export type PluginHost = {
+  /** Show the layers of the slide at `pos`; runs inside each move, as the stage draws it. */
+  render(pos: Position): void;
+  /** The deck settled at `pos`: every plugin hears where it stands. */
+  settled(pos: Position): void;
+};
+
+type Registered = {
+  name: string;
+  change: Array<(position: PagePosition) => void>;
+  mount: Array<(mount: PageMount) => void>;
+  layers: Map<string, HTMLElement>;
+};
+
+const LAYER_CLASS = "dek-plugin-layer";
+const PAGE_API = 1;
+
+export function createPluginHost(options: {
+  deck: string;
+  slides: Array<{ slug: string; title: string; beats: unknown[] }>;
+  position: () => Position;
+}): PluginHost {
+  // The plugins' block comes after the player in the page, so it is read when a plugin asks.
+  let config: PluginConfig | undefined;
+  const registered: Registered[] = [];
+  const keys = new Map<string, { plugin: string; listener: () => void }>();
+
+  const at = (pos: Position): PagePosition => ({
+    slug: options.slides[pos.slideIndex]?.slug ?? "",
+    index: pos.slideIndex,
+    beat: pos.beatIndex,
+  });
+
+  /** Runs a plugin's code; what it throws is the plugin's, and the player goes on. */
+  const guard = (name: string, run: () => void): void => {
+    try {
+      run();
+    } catch (error) {
+      console.error(`dek: plugin ${name} threw`, error);
+    }
+  };
+
+  const slideEl = (slug: string): HTMLElement | null =>
+    document.querySelector<HTMLElement>(
+      `#${PAGE_ID.deck} > .slide[data-slug="${CSS.escape(slug)}"]`,
+    );
+
+  /** The plugin's layer over `slug`, made on first use, after the slides in `#deck`. */
+  const layerOf = (plugin: Registered, slug: string): HTMLElement => {
+    let host = plugin.layers.get(slug);
+    if (!host) {
+      host = document.createElement("div");
+      host.className = LAYER_CLASS;
+      host.dataset.plugin = plugin.name;
+      host.dataset.slug = slug;
+      host.setAttribute("aria-hidden", "true");
+      // The layer is the slide's box; only what a plugin draws in it takes the pointer.
+      host.style.cssText = "position:absolute;inset:0;pointer-events:none;display:none";
+      host.attachShadow({ mode: "open" });
+      document.getElementById(PAGE_ID.deck)?.append(host);
+      plugin.layers.set(slug, host);
+    }
+    return host;
+  };
+
+  const mount = (plugin: Registered, slug: string): void => {
+    const root = slideEl(slug);
+    const layer = layerOf(plugin, slug).shadowRoot;
+    if (!root || !layer) {
+      return;
+    }
+    layer.replaceChildren();
+    for (const listener of plugin.mount) {
+      guard(plugin.name, () => listener({ slug, root, layer, view: "stage" }));
+    }
+  };
+
+  const render = (pos: Position): void => {
+    const slug = options.slides[pos.slideIndex]?.slug;
+    for (const plugin of registered) {
+      for (const [layerSlug, host] of plugin.layers) {
+        host.style.display = layerSlug === slug ? "block" : "none";
+      }
+    }
+  };
+
+  const settled = (pos: Position): void => {
+    for (const plugin of registered) {
+      for (const listener of plugin.change) {
+        guard(plugin.name, () => listener(at(pos)));
+      }
+    }
+  };
+
+  const dek: DekPage = {
+    plugin(name, pluginOptions, setup) {
+      if (pluginOptions?.api !== PAGE_API) {
+        console.error(
+          `dek: plugin ${name} asks for page API ${String(pluginOptions?.api)}; this dek gives ${PAGE_API}`,
+        );
+        return;
+      }
+      config ??= readConfig();
+      const declared = config[name];
+      if (!declared || registered.some((plugin) => plugin.name === name)) {
+        console.error(`dek: plugin ${name} is not one this page carries`);
+        return;
+      }
+      const plugin: Registered = { name, change: [], mount: [], layers: new Map() };
+      const api: PageApi = {
+        deck: { name: options.deck },
+        slides: options.slides.map(({ slug, title }) => ({ slug, title })),
+        current: () => at(options.position()),
+        on(event: "change" | "mount", listener: (value: never) => void) {
+          if (event === "change" || event === "mount") {
+            plugin[event].push(listener as never);
+          }
+        },
+        shown: (element) => element.closest("[data-step]:not(.is-shown)") === null,
+        data: (path) => declared.data[path] ?? null,
+        key(letter, listener) {
+          if (!declared.keys.includes(letter) || keys.has(letter)) {
+            return false;
+          }
+          keys.set(letter, { plugin: name, listener });
+          return true;
+        },
+      };
+      let ok = true;
+      try {
+        setup(api);
+      } catch (error) {
+        ok = false;
+        console.error(`dek: plugin ${name} threw`, error);
+      }
+      if (!ok) {
+        for (const [letter, bound] of keys) {
+          if (bound.plugin === name) {
+            keys.delete(letter);
+          }
+        }
+        return;
+      }
+      registered.push(plugin);
+      for (const { slug } of options.slides) {
+        mount(plugin, slug);
+      }
+      render(options.position());
+      for (const listener of plugin.change) {
+        guard(name, () => listener(at(options.position())));
+      }
+    },
+  };
+  window.dek = dek;
+
+  document.addEventListener("keydown", (event) => {
+    if (isTextEntry(event.target)) {
+      return;
+    }
+    for (const [letter, bound] of keys) {
+      if (isLetterKey(event, letter)) {
+        event.preventDefault();
+        guard(bound.plugin, bound.listener);
+        return;
+      }
+    }
+  });
+
+  // A live reload swaps a slide for a new element: its layers start over on the new one.
+  const deckEl = document.getElementById(PAGE_ID.deck);
+  if (deckEl && typeof MutationObserver !== "undefined") {
+    new MutationObserver((records) => {
+      const replaced = new Set<string>();
+      for (const record of records) {
+        for (const node of record.addedNodes) {
+          if (
+            node instanceof HTMLElement &&
+            node.classList.contains("slide") &&
+            node.dataset.slug
+          ) {
+            replaced.add(node.dataset.slug);
+          }
+        }
+      }
+      if (replaced.size === 0) {
+        return;
+      }
+      for (const plugin of registered) {
+        for (const slug of replaced) {
+          mount(plugin, slug);
+        }
+      }
+      render(options.position());
+      settled(options.position());
+    }).observe(deckEl, { childList: true });
+  }
+
+  // A printed deck is the slides alone.
+  const style = document.createElement("style");
+  style.textContent = `@media print { .${LAYER_CLASS} { display: none !important; } }`;
+  document.head.append(style);
+
+  return { render, settled };
+}
+
+function readConfig(): PluginConfig {
+  const text = document.getElementById(PAGE_ID.plugins)?.textContent;
+  if (!text) {
+    return {};
+  }
+  try {
+    return JSON.parse(text) as PluginConfig;
+  } catch {
+    return {};
+  }
+}

package/src/runtime/start.ts

@@ -9,6 +9,7 @@ import type { CreateDevLine } from "./dev-line.ts";
 import { bindInput } from "./input.ts";
 import { createLaserView, type LaserView } from "./laser-view.ts";
 import { createNavigator } from "./navigator.ts";
+import { createPluginHost } from "./plugins.ts";
 import { createPresenterView } from "./presenter-view.ts";
 import { createRailView } from "./rail-view.ts";
 import { deckChannelName } from "./routes.ts";
@@ -41,6 +42,7 @@ export function startPlayer(createDevLine?: CreateDevLine): void {
     presenter.render(pos);
     rail.markCurrent(pos.slideIndex);
     marks?.render(pos);
+    plugins.render(pos);
   }
 
   /**
@@ -92,13 +94,26 @@ export function startPlayer(createDevLine?: CreateDevLine): void {
         stage.showMove(from, to);
       }
     },
-    afterMove: presenter.startClock,
+    afterMove: () => {
+      presenter.startClock();
+      // A move that another is queued behind has not settled; the last one says where it stands.
+      if (positionsEqual(nav.target(), nav.position())) {
+        plugins.settled(nav.position());
+      }
+    },
     route: (next) => control.request(next, "remote"),
     ...(laser ? { onPointer: laser.receive } : {}),
   });
 
   const marks = dev?.marks;
 
+  // Plugins' pages run after the player and call window.dek.plugin, which this defines.
+  const plugins = createPluginHost({
+    deck: page.deck,
+    slides,
+    position: () => nav.position(),
+  });
+
   const rail = createRailView({
     slides,
     stage,

package/src/runtime/window.ts

@@ -1,4 +1,5 @@
 import type { Position } from "../core/step.ts";
+import type { DekPage } from "../plugin-api.ts";
 
 /** How capture tools seek the current slide's script, the way they seek Web Animations. */
 export type DekMotionHandle = {
@@ -17,6 +18,8 @@ declare global {
     dekGo?: (next: Position | null | undefined) => Promise<void>;
     dekMotion?: DekMotionHandle;
     dekLive?: (raw: unknown) => Promise<void>;
+    /** Page API 1, for plugins' pages (ADR 33). */
+    dek?: DekPage;
     /** 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. */

package/src/server/deck-snapshot.ts

@@ -1,7 +1,9 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative, sep } from "node:path";
 import { deckPaths } from "../core/deck-paths.ts";
 import type { LiveEvent } from "../core/live-protocol.ts";
+import { deckProjectRoot } from "../core/path.ts";
+import { deckData, pinnedPlugins } from "../core/plugin-host.ts";
 import { listSlideFiles, type SlideSidecar } from "../core/resolve.ts";
 
 /** Modification times by name; a file that is gone is left out. */
@@ -19,6 +21,11 @@ export type DeckSnapshot = {
   javascript: Mtimes;
   /** `voice/voice.toml`, `voice/dict.toml`, and `voice/pin/*`. */
   voice: Mtimes;
+  /**
+   * Each pinned plugin's lock, and each data file it declares in this deck, keyed by the path
+   * from the project's root: what the page's plugin layer is made from (ADR 33).
+   */
+  plugins: Mtimes;
 };
 
 /** Which slides to lint: one slug, or the whole deck when it is left out. */
@@ -43,9 +50,29 @@ export function takeSnapshot(deckDir: string): DeckSnapshot {
     scripts: slideMtimes(deckDir, ".ts"),
     javascript: slideMtimes(deckDir, ".js"),
     voice: voiceMtimes(paths.voice),
+    plugins: pluginMtimes(deckDir),
   };
 }
 
+function pluginMtimes(deckDir: string): Mtimes {
+  const root = deckProjectRoot(deckDir);
+  const times: Mtimes = {};
+  const note = (path: string) => {
+    const time = mtime(path);
+    if (time !== 0) {
+      times[relative(root, path).split(sep).join("/")] = time;
+    }
+  };
+  // A dek.toml mid-edit names no plugin; the next scan sees them again.
+  for (const { name, manifest } of pinnedPlugins(root)) {
+    note(join(root, "plugins", name, "plugin.json"));
+    for (const { path } of manifest ? deckData(manifest) : []) {
+      note(join(deckDir, path));
+    }
+  }
+  return times;
+}
+
 /**
  * What changed from `prev` to `next`, as the events a page hears and the work that follows.
  * Any change counts, an older mtime too: a file restored from a copy is still an edit.
@@ -88,6 +115,10 @@ export function diffSnapshot(prev: DeckSnapshot, next: DeckSnapshot): DeckChange
       }
     }
   }
+  // A plugin's page reads its data once, as the page loads, so a change reloads the page.
+  if (!sync && changedKeys(prev.plugins, next.plugins).length > 0) {
+    events.push({ type: "reload-script", slugs: [] });
+  }
   const synth = sync || changedKeys(prev.voice, next.voice).length > 0;
   return { sync, events, ...(diagnose ? { diagnose } : {}), synth };
 }

package/src/server/dev.ts

@@ -3,7 +3,12 @@ import { DekError } from "../core/error.ts";
 import type { PlaywrightRunner } from "../core/playwright.ts";
 import { isRefName, refReadOnlyError, requireProject } from "../core/ref.ts";
 import { locateDeck, type Project } from "../core/resolve.ts";
-import { annotateScript, livePlayerScript, liveReloadScript } from "../runtime/player.ts";
+import {
+  annotateScript,
+  livePlayerScript,
+  liveReloadScript,
+  pluginPageScripts,
+} from "../runtime/player.ts";
 import {
   clearance,
   keepToOwnOrigin,
@@ -76,14 +81,15 @@ export async function startDevServer(options: DevServerOptions): Promise<DevServ
   if (options.deck !== undefined && isRefName(options.deck)) {
     throw refReadOnlyError(options.deck);
   }
-  // Before the port and the watchers; writing the lock checks again, for a server that raced us.
-  assertNoDevServer(project.root);
   const { scopedDeckName, deckDir } = serverScope(project, options);
+  // Before the port and the watchers; writing the lock checks again, for a server that raced us.
+  assertNoDevServer(project.root, scopedDeckName);
   const access = accessFor(options);
   const embed = {
     playerScript: await livePlayerScript(),
     liveReloadScript: liveReloadScript(),
     annotateScript: await annotateScript(),
+    pluginScripts: await pluginPageScripts(),
   };
 
   const pages = createDevPages({

package/src/server/lock.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { DekError } from "../core/error.ts";
+import { isDeckName } from "../core/path.ts";
 import { readSourceIfExists, removeInside, writeInside } from "../core/safe-fs.ts";
 
 export type DevServerLock = {
@@ -88,30 +89,59 @@ export function readDevServerLock(root: string): DevServerLock | undefined {
   return undefined;
 }
 
-/** The URL of each root a server in this process holds, which two racing servers both see. */
-const claimedRoots = new Map<string, string>();
+/** The server each root a server in this process holds, which two racing servers both see. */
+const claimedRoots = new Map<string, Omit<DevServerLock, "password">>();
 
-/** Throw when a live server, in this process or another, already holds `root`. */
-export function assertNoDevServer(root: string): void {
+/**
+ * Throw when a live server, in this process or another, already holds `root`. `deck` is the one
+ * deck the server about to start would serve, none for the whole project.
+ */
+export function assertNoDevServer(root: string, deck?: string): void {
   const existing = readDevServerLock(root);
   const running =
-    claimedRoots.get(root) ?? (existing && isPidAlive(existing.pid) ? existing.url : undefined);
+    claimedRoots.get(root) ?? (existing && isPidAlive(existing.pid) ? existing : undefined);
   if (running !== undefined) {
-    throw new DekError(`dev server already running at ${running}`, {
+    throw new DekError(`dev server already running at ${running.url}`, {
       path: serverLockPath(root),
-      hint: `open ${running}`,
+      hint: runningServerHint(root, running, deck),
     });
   }
 }
 
+/**
+ * Where the running server shows what was asked for, or, when it serves one other deck only, how
+ * to get one that serves both: `dekc` started inside a deck's folder serves that deck alone.
+ */
+function runningServerHint(
+  root: string,
+  running: Omit<DevServerLock, "password">,
+  deck: string | undefined,
+): string {
+  if (running.deck === deck) {
+    return `open ${running.url}`;
+  }
+  if (running.deck === undefined && deck !== undefined) {
+    return `open ${running.url}decks/${encodeURIComponent(deck)}/`;
+  }
+  // The lock is a file a repository could bring along: name only a deck this project has.
+  const named =
+    running.deck !== undefined &&
+    isDeckName(running.deck) &&
+    existsSync(join(root, "decks", running.deck, "script.md"))
+      ? `decks/${running.deck}`
+      : "one deck";
+  const wanted = deck === undefined ? "the whole project" : `decks/${deck}`;
+  return `it serves only ${named}; to serve ${wanted}, stop it (pid ${running.pid}) and run \`dekc\` at the project root, which serves every deck`;
+}
+
 export function writeDevServerLock(
   root: string,
   url: string,
   password?: string,
   deck?: string,
 ): void {
-  assertNoDevServer(root);
-  claimedRoots.set(root, url);
+  assertNoDevServer(root, deck);
+  claimedRoots.set(root, { url, pid: process.pid, ...(deck ? { deck } : {}) });
   try {
     // A fresh file renamed into place, so it may hold the --remote password: its owner's only.
     writeInside(

package/src/server/pages.ts

@@ -1,4 +1,5 @@
 import { renderDeckHtml } from "../core/document.ts";
+import { pluginPages } from "../core/plugin-host.ts";
 import type { Project } from "../core/resolve.ts";
 import { errorPage, htmlResponse, renderIndexHtml } from "./routes.ts";
 
@@ -13,7 +14,13 @@ export type DevPages = {
 
 /** The pages a dev server renders, each kept until `clear`. */
 export function createDevPages(options: {
-  embed: { playerScript: string; liveReloadScript: string; annotateScript: string };
+  embed: {
+    playerScript: string;
+    liveReloadScript: string;
+    annotateScript: string;
+    /** The pages of the plugins dek ships, compiled, by name. */
+    pluginScripts?: Record<string, string>;
+  };
   remote: boolean;
   /** Embedded on the presenter page, so its stream and moves are let through. */
   password: string | undefined;
@@ -39,6 +46,7 @@ export function createDevPages(options: {
           cached(`${dir}:${mode}`, () =>
             renderDeckHtml(dir, {
               playerScript: embed.playerScript,
+              plugins: pluginPages(options.project().root, dir, embed.pluginScripts ?? {}),
               target: {
                 kind: "dev",
                 mode,

package/tsconfig.json

@@ -22,5 +22,5 @@
     "noUnusedParameters": false,
     "noPropertyAccessFromIndexSignature": false
   },
-  "include": ["src", "tests"]
+  "include": ["src", "tests", "evals"]
 }