@hajimism/dek 0.2.1 → 0.2.2

package/src/core/html.ts

@@ -1,3 +1,4 @@
+import { cutText } from "./annotation-rows.ts";
 import { assetInliner } from "./assets.ts";
 import { deckPaths } from "./deck-paths.ts";
 import { escapeAttr, escapeHtml } from "./escape.ts";
@@ -233,8 +234,11 @@ export function stampSlide(html: string, stamp: SlideStamp): string {
   });
 }
 
-/** Where a start tag is written, and its classes as written; none when it has no `class`. */
-type TagSpot = LineColumn & { classes?: string };
+/**
+ * Where a start tag is written, its tag, its classes as written (none when it has no `class`),
+ * and the text inside it as written, whitespace collapsed.
+ */
+type TagSpot = LineColumn & { tag: string; classes?: string; text: string };
 
 /**
  * Where each start tag of `html` is written in the file it was taken from, in document order,
@@ -243,12 +247,30 @@ type TagSpot = LineColumn & { classes?: string };
  */
 function startTagSpots(html: string, source: SlideSource): TagSpot[] {
   const mark = uniqueMark(html);
-  const classes: Array<string | null> = [];
+  const tags: Array<{ tag: string; classes: string | null; text: string }> = [];
+  const open: number[] = [];
   const marked = rewriteHtml(html, (rewriter) => {
     rewriter.on("*", {
       element(el) {
         el.before(mark, { html: true });
-        classes.push(el.getAttribute("class"));
+        const index = tags.length;
+        tags.push({ tag: el.tagName.toLowerCase(), classes: el.getAttribute("class"), text: "" });
+        if (el.canHaveContent) {
+          open.push(index);
+          el.onEndTag(() => {
+            open.splice(open.lastIndexOf(index), 1);
+          });
+        }
+      },
+    });
+    rewriter.onDocument({
+      text(chunk) {
+        for (const index of open) {
+          const tag = tags[index];
+          if (tag) {
+            tag.text += chunk.text;
+          }
+        }
       },
     });
   });
@@ -259,13 +281,36 @@ function startTagSpots(html: string, source: SlideSource): TagSpot[] {
     .slice(0, -1)
     .map((before, index) => {
       offset += before.length;
-      const written = classes[index];
-      return written === null || written === undefined
-        ? spot(offset)
-        : { ...spot(offset), classes: written.split(/\s+/).filter(Boolean).join(" ") };
+      const { tag = "", classes = null, text = "" } = tags[index] ?? {};
+      const found = { ...spot(offset), tag, text: text.replace(/\s+/g, " ").trim() };
+      return classes === null
+        ? found
+        : { ...found, classes: classes.split(/\s+/).filter(Boolean).join(" ") };
     });
 }
 
+/**
+ * An element of a written slide as annotate mode names it, whatever a script adds to it: where
+ * its start tag is written, `<line>:<column>`, its tag and classes as written, as `div.chevron`,
+ * and its text as written, cut short. The slide itself has no text: all of the slide names
+ * nothing.
+ */
+export type WrittenElement = { source: string; name: string; text: string };
+
+/** Every element of the slide `slides/<slug>.html` writes, in document order; none for a skeleton. */
+export function writtenElements(slides: DeckSlides, slug: string): WrittenElement[] | undefined {
+  const html = slides.written(slug);
+  const source = slides.source(slug);
+  if (html === undefined || source === undefined) {
+    return undefined;
+  }
+  return startTagSpots(html, source).map((spot, index) => ({
+    source: `${spot.line}:${spot.column}`,
+    name: [spot.tag, ...(spot.classes ?? "").split(" ").filter(Boolean)].join("."),
+    text: index === 0 ? "" : cutText(spot.text),
+  }));
+}
+
 /**
  * Every slide of the deck in script order, as the player pages hold them. `sources` says where
  * each tag is written, for the dev server's pages.

package/src/core/lint/slide-html.ts

@@ -1,8 +1,9 @@
 import { type Diagnostic, diag } from "../diagnostic.ts";
-import type { HtmlAttribute, HtmlScan, SourceSpot } from "../html-scan.ts";
+import type { HtmlAttribute, HtmlScan, Picture, SourceSpot } from "../html-scan.ts";
 import type { Section } from "../schema.ts";
 import { beatAt, formatStepChoices, resolveStep, stepChoices } from "../step.ts";
 import { suggest } from "../suggest.ts";
+import { RUNTIME_CLASSES } from "../theme-facts.ts";
 import { isUrlAttribute } from "../url-attributes.ts";
 import { assetRefDiagnostics } from "./asset-refs.ts";
 import { RESERVED_MORPHS } from "./morph.ts";
@@ -52,6 +53,7 @@ export function lintSlideHtml(
     ...presentationDiagnostics(slide),
     ...emptyHeadingDiagnostics(slide),
     ...hiddenTextDiagnostics(slide),
+    ...pictureDiagnostics(slide),
     ...(options.classes
       ? unknownClassDiagnostics(slide, options.classes, options.hasScript === true)
       : []),
@@ -442,7 +444,85 @@ function hiddenTextDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[]
   });
 }
 
-/** DEK010: a class neither theme.css nor the slide's own stylesheet defines. */
+/**
+ * DEK034: a picture with nothing for a screen reader to say: an `<img>` without `alt`, an `<svg>`
+ * with no text and no name, or an element whose `role="img"` has no name. Each is either content,
+ * which wants words, or decoration, which says so: `alt=""` or `aria-hidden="true"`. An SVG with
+ * text of its own is read as it is, so the hint never sends a labeled figure to `aria-hidden`,
+ * where DEK029 would warn of it.
+ */
+function pictureDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[] {
+  return scan.pictures.flatMap((picture) => {
+    const found = unnamedPicture(picture);
+    return found
+      ? [
+          diag("DEK034", {
+            message: found.message,
+            path,
+            ...spotOf(picture.element),
+            slug: section.slug,
+            hint: found.hint,
+            data: found.data,
+          }),
+        ]
+      : [];
+  });
+}
+
+function unnamedPicture({
+  element,
+  text,
+  titled,
+}: Picture): { message: string; hint: string; data: Record<string, string> } | undefined {
+  const value = (name: string): string | undefined =>
+    element.attributes.find((attribute) => attribute.name === name)?.value;
+  const named = [value("aria-label"), value("aria-labelledby"), value("title")].some(
+    (name) => name !== undefined && name.trim() !== "",
+  );
+  const { tag } = element;
+  if (named || (tag === "img" && value("alt") !== undefined)) {
+    return undefined;
+  }
+  if ((value("role") ?? "").trim().toLowerCase().split(/\s+/)[0] === "img") {
+    if (titled) {
+      return undefined;
+    }
+    const data = { tag, role: "img" };
+    return text
+      ? {
+          message: `<${tag} role="img"> has no name, and role="img" keeps a screen reader from reading its text`,
+          hint: 'give it aria-label="…" saying what it shows, or remove role="img" so its text is read',
+          data,
+        }
+      : {
+          message: `<${tag} role="img"> has no name, so a screen reader cannot say what it shows`,
+          hint: 'give it aria-label="…" saying what it shows, or replace role="img" with aria-hidden="true" if it is decoration',
+          data,
+        };
+  }
+  if (tag === "img") {
+    const src = value("src");
+    return {
+      message: `<img${src === undefined ? "" : ` src="${src}"`}> has no alt, so a screen reader cannot say what it shows`,
+      hint: 'add alt="…" saying what the picture shows, or alt="" if it is decoration',
+      data: src === undefined ? { tag } : { tag, src },
+    };
+  }
+  if (text) {
+    return undefined;
+  }
+  return {
+    message: `<${tag}> has nothing to read and no name, so a screen reader skips what it shows`,
+    hint: 'give it role="img" and aria-label="…" saying what it shows, or aria-hidden="true" if it is decoration',
+    data: { tag },
+  };
+}
+
+/**
+ * DEK010: a class neither theme.css nor the slide's own stylesheet defines, or a state class the
+ * player sets, which markup that writes it would claim before the player does. `classes` holds
+ * neither.
+ */
 function unknownClassDiagnostics(
   { section, path, scan }: SlideHtml,
   classes: Set<string>,
@@ -468,6 +548,16 @@ function unknownClassDiagnostics(
     }
   }
   return [...unknown].map(([name, attribute]) => {
+    if (RUNTIME_CLASSES.has(name)) {
+      return diag("DEK010", {
+        message: `class "${name}" is a state the player sets at runtime, not a class for markup`,
+        path,
+        ...spotOf(attribute),
+        slug: section.slug,
+        hint: `remove "${name}" from the class attribute: the player puts is-current on the slide on screen and is-shown on each data-step element once its beat plays. To style that state, select it in theme.css or slides/${section.slug}.css, as .slide.is-current [data-step].is-shown`,
+        data: { class: name, state: true },
+      });
+    }
     const suggestion = suggest(name, known);
     return diag("DEK010", {
       message: `class "${name}" is not defined in theme.css`,

package/src/core/lint.ts

@@ -19,6 +19,7 @@ import { voiceDiagnostics } from "./lint/voice.ts";
 import { asResolvedDeck, type Project, type ProjectDeck } from "./resolve.ts";
 import type { Section } from "./schema.ts";
 import { evaluateSlideScripts, slideScriptsProblems } from "./slide-script-eval.ts";
+import { RUNTIME_CLASSES } from "./theme-facts.ts";
 
 export { unreadableScriptDiagnostics } from "./lint/script.ts";
 export { silentCueDiagnostics } from "./lint/voice.ts";
@@ -122,7 +123,13 @@ function slideDiagnostics(ctx: LintContext, section: Section): Diagnostic[] {
       deckDir: ctx.deck.dir,
       skeleton: source.skeleton,
       hasScript: script !== undefined,
-      classes: ctx.theme && new Set([...ctx.theme.classes, ...(sheet ? cssClassNames(sheet) : [])]),
+      classes:
+        ctx.theme &&
+        new Set(
+          [...ctx.theme.classes, ...(sheet ? cssClassNames(sheet) : [])].filter(
+            (name) => !RUNTIME_CLASSES.has(name),
+          ),
+        ),
       // A theme with no layouts at all has nothing to check a data-layout against.
       ...(ctx.theme && ctx.theme.layouts.length > 0
         ? {

package/src/core/live-protocol.ts

@@ -12,7 +12,9 @@ export type LiveEvent =
   | { type: "reload-theme" }
   | { type: "reload-script"; slugs: string[] }
   | { type: "diagnostics"; diagnostics: Diagnostic[] }
-  | { type: "timeline" };
+  | { type: "timeline" }
+  /** The deck's annotations changed; a page that shows them asks for them again. */
+  | { type: "annotations" };
 
 export type LiveEventType = LiveEvent["type"];
 
@@ -32,6 +34,7 @@ const FIELDS_OK: Record<LiveEventType, (event: Record<string, unknown>) => boole
   "reload-script": (event) => isStrings(event.slugs),
   diagnostics: (event) => Array.isArray(event.diagnostics),
   timeline: () => true,
+  annotations: () => true,
 };
 
 /** Whether a message read off the stream is one this build of the page understands. */

package/src/core/page.ts

@@ -33,6 +33,12 @@ export const PAGE_ID = {
   announce: "dek-announce",
 } as const;
 
+/**
+ * The event the player fires on `document` when the dev server says the deck's annotations
+ * changed, for annotate mode, which is compiled apart from the player, to ask for them again.
+ */
+export const ANNOTATIONS_CHANGED = "dek-annotations";
+
 export type PageMode = "player" | "presenter" | "video";
 
 /** The page's settings, written on <body> as `data-*` and read back once by the runtime. */

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

@@ -34,7 +34,10 @@ declare module "playwright" {
   };
   export type Browser = {
     newPage(options?: { viewport?: Viewport }): Promise<Page>;
-    newContext(options?: { viewport?: Viewport }): Promise<BrowserContext>;
+    newContext(options?: {
+      viewport?: Viewport;
+      deviceScaleFactor?: number;
+    }): Promise<BrowserContext>;
     close(): Promise<void>;
   };
   export const chromium: {

package/src/core/playwright-visual.ts

@@ -21,12 +21,15 @@ import type {
   PagesRequest,
   PagesResponse,
   PdfRequest,
+  PptxRequest,
+  PptxResponse,
   ResponseTo,
   VisualPage,
   VisualRequest,
 } from "./playwright.ts";
 import { captureMotion } from "./playwright-motion.ts";
 import { renderSheets } from "./playwright-sheet.ts";
+import { measurePptxTextsInPage, PPTX_OWNER_ATTR } from "./pptx-text.ts";
 import { pseudoTextBoxes } from "./pseudo-text.ts";
 import { motionSheets } from "./sheet.ts";
 import {
@@ -47,7 +50,11 @@ export async function runVisualRequest<R extends VisualRequest>(
   browser: Browser,
   request: R,
 ): Promise<ResponseTo<R>> {
-  const context = await browser.newContext({ viewport: request.viewport });
+  // A PPTX's pictures are shown full screen, so they are drawn at twice the slide's size.
+  const context = await browser.newContext({
+    viewport: request.viewport,
+    ...(request.kind === "pptx" ? { deviceScaleFactor: 2 } : {}),
+  });
   try {
     return (await answer(context, request)) as ResponseTo<R>;
   } finally {
@@ -65,6 +72,8 @@ function answer(context: BrowserContext, request: VisualRequest) {
       return shootMorph(context, request);
     case "motion":
       return shootMotion(context, request);
+    case "pptx":
+      return shootPptx(context, request);
     default: {
       const unknown: never = request;
       throw new Error(`unknown visual request ${JSON.stringify(unknown)}`);
@@ -86,6 +95,70 @@ async function printPdf(context: BrowserContext, request: PdfRequest): Promise<D
   return {};
 }
 
+/** Each slide's text measured and taken out, and the slide shot without it, page by page. */
+async function shootPptx(context: BrowserContext, request: PptxRequest): Promise<PptxResponse> {
+  const slides = await visitInPages(
+    request.pages,
+    () => context.newPage(),
+    async (page, pageReq) => {
+      await page.setContent(pageReq.html, { waitUntil: "load" });
+      await page.evaluate(() => document.fonts.ready.then(() => undefined));
+      const measured = await page.evaluate(measurePptxTextsInPage);
+      const fonts = await platformFonts(page);
+      await page.screenshot({ path: pageReq.screenshotPath, fullPage: false });
+      return {
+        slug: pageReq.slug,
+        description: measured.description,
+        boxes: measured.boxes.map((box) => ({
+          ...box,
+          runs: box.runs.map(({ owner, ...run }) => {
+            const font = fonts.get(owner);
+            return font === undefined ? run : { ...run, font };
+          }),
+        })),
+      };
+    },
+  );
+  return { slides };
+}
+
+/**
+ * The font Chromium drew each marked element's text with, by the element's number: the one that
+ * drew most of its glyphs, as the DevTools protocol reports it. A theme names a stack, or only
+ * `sans-serif`; this is the face that was found.
+ */
+async function platformFonts(page: Page): Promise<Map<number, string>> {
+  const fonts = new Map<number, string>();
+  const cdp = await page.context().newCDPSession(page);
+  try {
+    await cdp.send("DOM.enable");
+    await cdp.send("CSS.enable");
+    const { root } = (await cdp.send("DOM.getDocument", { depth: -1 })) as {
+      root: { nodeId: number };
+    };
+    const { nodeIds } = (await cdp.send("DOM.querySelectorAll", {
+      nodeId: root.nodeId,
+      selector: `[${PPTX_OWNER_ATTR}]`,
+    })) as { nodeIds: number[] };
+    for (const nodeId of nodeIds) {
+      const { attributes } = (await cdp.send("DOM.getAttributes", { nodeId })) as {
+        attributes: string[];
+      };
+      const owner = Number(attributes[attributes.indexOf(PPTX_OWNER_ATTR) + 1]);
+      const { fonts: used } = (await cdp.send("CSS.getPlatformFontsForNode", { nodeId })) as {
+        fonts: Array<{ familyName: string; glyphCount: number }>;
+      };
+      const main = [...used].sort((a, b) => b.glyphCount - a.glyphCount)[0];
+      if (main && Number.isInteger(owner)) {
+        fonts.set(owner, main.familyName);
+      }
+    }
+  } finally {
+    await cdp.detach();
+  }
+  return fonts;
+}
+
 /** The move between two slides, frozen at a moment and shot. */
 async function shootMorph(context: BrowserContext, request: MorphRequest): Promise<DoneResponse> {
   const page = await context.newPage();

package/src/core/playwright.ts

@@ -6,6 +6,7 @@ import { DekError } from "./error.ts";
 import type { Fill } from "./fill.ts";
 import { type Collision, EDGES, type Overflow } from "./overflow.ts";
 import { moduleFilePath } from "./path.ts";
+import type { PptxTextBox } from "./pptx-package.ts";
 import type { MotionBeat, SheetSpec } from "./sheet.ts";
 import { exitWorker, readWorkerRequest, runJsonWorker, workerCommand } from "./spawn.ts";
 import type { Position } from "./step.ts";
@@ -79,8 +80,23 @@ export type MotionRequest = {
   motion: MotionSpec;
 };
 
+/**
+ * Each slide's still page drawn for a PPTX, at twice its size: its text measured line by line,
+ * then the page shot without it, to `screenshotPath`.
+ */
+export type PptxRequest = {
+  kind: "pptx";
+  viewport: Viewport;
+  pages: Array<{ html: string; slug: string; screenshotPath: string }>;
+};
+
+/** Each page's text, in the order of the request's pages, with the font each run was drawn in. */
+export type PptxResponse = {
+  slides: Array<{ slug: string; description: string; boxes: PptxTextBox[] }>;
+};
+
 /** What the Playwright worker is asked; the kind says which payload comes with it. */
-export type VisualRequest = PagesRequest | PdfRequest | MorphRequest | MotionRequest;
+export type VisualRequest = PagesRequest | PdfRequest | MorphRequest | MotionRequest | PptxRequest;
 
 type OverflowFinding = Overflow & { slug: string; step: string };
 
@@ -151,6 +167,7 @@ type VisualResponses = {
   pdf: DoneResponse;
   morph: DoneResponse;
   motion: MotionResponse;
+  pptx: PptxResponse;
 };
 
 /** The answer to a request of `R`'s kind. */
@@ -297,6 +314,7 @@ const RESPONSE_PARSERS: {
   morph: () => ({}),
   motion: ({ motion, sheets }) =>
     isArrayOf(motion, isMotionBeat) && isArrayOf(sheets, isString) ? { motion, sheets } : null,
+  pptx: ({ slides }) => (isArrayOf(slides, isPptxSlide) ? { slides } : null),
 };
 
 /** The worker's JSON as the answer to a `kind` request, or null when it is not one. */
@@ -415,6 +433,38 @@ function isContrastFinding(value: unknown): value is ContrastFinding {
   );
 }
 
+function isPptxSlide(value: unknown): value is PptxResponse["slides"][number] {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const { slug, description, boxes } = value as Record<string, unknown>;
+  return isString(slug) && isString(description) && isArrayOf(boxes, isPptxBox);
+}
+
+function isPptxBox(value: unknown): value is PptxTextBox {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const box = value as Record<string, unknown>;
+  return (
+    ["x", "y", "width", "height", "lineHeight"].every((key) => isNumber(box[key])) &&
+    isArrayOf(box.runs, (run: unknown): run is PptxTextBox["runs"][number] => {
+      if (!run || typeof run !== "object") {
+        return false;
+      }
+      const { text, size, alpha, letterSpacing, color, font } = run as Record<string, unknown>;
+      return (
+        isString(text) &&
+        isNumber(size) &&
+        isNumber(alpha) &&
+        isNumber(letterSpacing) &&
+        isArrayOf(color, isNumber) &&
+        (font === undefined || isString(font))
+      );
+    })
+  );
+}
+
 function isMotionBeat(value: unknown): value is MotionBeat {
   if (!value || typeof value !== "object") {
     return false;