@hajimism/dek 0.3.3 → 0.5.0

package/src/core/pptx.ts

@@ -1,9 +1,11 @@
+// biome-ignore lint/style/noRestrictedImports: mkdtempSync and rmSync, for a folder of the shots' own in the system's temp folder, removed after.
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { type DistOptions, distFile } from "./path.ts";
 import { type PlaywrightRunner, requirePlaywright } from "./playwright.ts";
-import { pptxPackage } from "./pptx-package.ts";
+import { mapPictures, type PptxLayer, pptxPackage } from "./pptx-package.ts";
+import { deckTheme } from "./pptx-theme.ts";
 import { presenterSlides } from "./presenter.ts";
 import { asResolvedDeck, type ResolvedDeck } from "./resolve.ts";
 import { writeInside } from "./safe-fs.ts";
@@ -11,7 +13,16 @@ import { logicalSize } from "./size.ts";
 import { lastStop } from "./step.ts";
 import { loadSlideSources, renderSlideHtml } from "./still-page.ts";
 
-export type PptxResult = { outPath: string };
+export type PptxResult = {
+  outPath: string;
+  /**
+   * What was laid over the pictures: how many shapes, lines included, and pictures, and the
+   * slugs of the slides that kept everything in their picture.
+   */
+  lifted: PptxLifted;
+};
+
+export type PptxLifted = { shapes: number; pictures: number; untouched: string[] };
 
 export type PptxOptions = DistOptions & {
   /** For anyone who has the file: the notes leave out the stage directions and comments. */
@@ -20,9 +31,10 @@ export type PptxOptions = DistOptions & {
 };
 
 /**
- * The deck as a PowerPoint file: each slide at its last beat, as the PDF prints it, drawn as a
- * picture with its text laid over it in text boxes a recipient can edit, and its script in the
- * notes. A slide script that cannot run stops it, as it stops the PDF.
+ * The deck as a PowerPoint file: each slide at its last beat, as the PDF prints it, its plain
+ * boxes, pictures, and text as PowerPoint's own over a picture of the rest, in the deck's theme
+ * (ADRs 20 to 22), and its script in the notes. A slide script that cannot run stops it, as it
+ * stops the PDF.
  */
 export async function pptxDeck(dir: string, options?: PptxOptions): Promise<PptxResult>;
 export async function pptxDeck(source: ResolvedDeck, options?: PptxOptions): Promise<PptxResult>;
@@ -56,20 +68,56 @@ export async function pptxDeck(
       options.runner,
     );
     const scripts = presenterSlides(deck, options.public ? "audience" : "speaker");
+    // The deck's tokens are PowerPoint's theme, as most slides have them.
+    const theme = deckTheme(answer.slides.flatMap((slide) => (slide.theme ? [slide.theme] : [])));
     const bytes = pptxPackage({
       title: deck.deck.title,
       lang: deck.deck.lang,
       size,
+      theme,
       slides: answer.slides.map((slide, index) => ({
-        picture: readFileSync(join(shots, `${index + 1}.png`)),
+        ...(slide.picture === false
+          ? {}
+          : { picture: readFileSync(join(shots, `${index + 1}.png`)) }),
+        ...(slide.background ? { background: slide.background } : {}),
         description: slide.description || (sections[index]?.title ?? slide.slug),
-        texts: slide.boxes,
+        layers: mapPictures(slide.layers, ({ png, svg, ...picture }) => ({
+          ...picture,
+          png: readFileSync(png),
+          ...(svg === undefined ? {} : { svg }),
+        })),
         notes: scripts[index]?.script ?? "",
       })),
     });
     writeInside(outPath, bytes, project.root);
+    const lifted: PptxLifted = { shapes: 0, pictures: 0, untouched: [] };
+    for (const slide of answer.slides) {
+      const counts = countLifted(slide.layers);
+      lifted.shapes += counts.shapes;
+      lifted.pictures += counts.pictures;
+      if (counts.shapes + counts.pictures === 0) {
+        lifted.untouched.push(slide.slug);
+      }
+    }
+    return { outPath, lifted };
   } finally {
     rmSync(shots, { recursive: true, force: true });
   }
-  return { outPath };
+}
+
+function countLifted<I>(layers: PptxLayer<I>[]): { shapes: number; pictures: number } {
+  let shapes = 0;
+  let pictures = 0;
+  for (const layer of layers) {
+    if (layer.kind === "shape") {
+      const inner = countLifted(layer.layers);
+      shapes += 1 + inner.shapes;
+      pictures += inner.pictures;
+    } else if (layer.kind === "rule") {
+      shapes += 1;
+    } else if (layer.kind === "picture") {
+      pictures += 1;
+    }
+  }
+  return { shapes, pictures };
 }

package/src/core/prose.ts

@@ -14,3 +14,26 @@ function joined(items: string[], conjunction: string): string {
   }
   return `${items.slice(0, -1).join(", ")}, ${conjunction} ${items.at(-1)}`;
 }
+
+/**
+ * Names from someone else's files as a hint lists them: those `shows` passes, then how many others
+ * there are, in the words of `others`. An other could hold anything, and an agent takes a hint as
+ * dek's own words.
+ */
+export function listShown(
+  names: string[],
+  shows: (name: string) => boolean,
+  others: (count: number) => string,
+): string {
+  const shown = names.filter(shows);
+  const left = names.length - shown.length;
+  if (left === 0) {
+    return shown.join(", ");
+  }
+  return shown.length === 0 ? others(left) : `${shown.join(", ")}, and ${others(left)}`;
+}
+
+/** How many names a list leaves out because they are no plain word: see `listShown`. */
+export function unprinted(count: number): string {
+  return `${count} whose ${count === 1 ? "name" : "names"} dek does not print`;
+}

package/src/core/pseudo-text.ts

@@ -14,17 +14,34 @@ type DomNode = {
  * `<host>::<pseudo>`. The page exposes no box for a pseudo-element, and Chromium, which lays it
  * out, does: through the DevTools protocol. One that is not laid out has no box and is left out.
  */
-export async function pseudoTextBoxes(page: Page): Promise<Map<string, Box>> {
+export function pseudoTextBoxes(page: Page): Promise<Map<string, Box>> {
+  return pseudoElementBoxes(page, PSEUDO_TEXT_HOST, "content", ["before", "after"]);
+}
+
+/**
+ * The `content` or `border` box, in the viewport, of each pseudo-element of the `types` given
+ * of every element marked with `attr`, keyed `<the attribute's value>::<pseudo>`.
+ */
+export async function pseudoElementBoxes(
+  page: Page,
+  attr: string,
+  model: "content" | "border",
+  types: ReadonlyArray<"before" | "after" | "marker">,
+): Promise<Map<string, Box>> {
   const cdp = await page.context().newCDPSession(page);
   try {
     const { root } = (await cdp.send("DOM.getDocument", { depth: -1 })) as { root: DomNode };
     const boxes = new Map<string, Box>();
     for (const node of walk(root)) {
-      const host = attribute(node, PSEUDO_TEXT_HOST);
+      const host = attribute(node, attr);
       for (const pseudo of host === undefined ? [] : (node.pseudoElements ?? [])) {
-        const box = await contentBox(cdp, pseudo.nodeId);
-        if (box && (pseudo.pseudoType === "before" || pseudo.pseudoType === "after")) {
-          boxes.set(`${host}::${pseudo.pseudoType}`, box);
+        const type = types.find((each) => each === pseudo.pseudoType);
+        if (type === undefined) {
+          continue;
+        }
+        const box = await boxOf(cdp, pseudo.nodeId, model);
+        if (box) {
+          boxes.set(`${host}::${type}`, box);
         }
       }
     }
@@ -48,13 +65,18 @@ function attribute(node: DomNode, name: string): string | undefined {
   return at >= 0 && at % 2 === 0 ? attributes[at + 1] : undefined;
 }
 
-async function contentBox(cdp: CDPSession, nodeId: number): Promise<Box | undefined> {
+async function boxOf(
+  cdp: CDPSession,
+  nodeId: number,
+  model: "content" | "border",
+): Promise<Box | undefined> {
   try {
-    const { model } = (await cdp.send("DOM.getBoxModel", { nodeId })) as {
-      model: { content: number[] };
+    const { model: boxes } = (await cdp.send("DOM.getBoxModel", { nodeId })) as {
+      model: { content: number[]; border: number[] };
     };
-    const xs = model.content.filter((_, index) => index % 2 === 0);
-    const ys = model.content.filter((_, index) => index % 2 === 1);
+    const quad = boxes[model];
+    const xs = quad.filter((_, index) => index % 2 === 0);
+    const ys = quad.filter((_, index) => index % 2 === 1);
     return {
       left: Math.min(...xs),
       top: Math.min(...ys),

package/src/core/ref-name.ts

@@ -1,4 +1,5 @@
 import { DekError } from "./error.ts";
+import { holdsHidden } from "./foreign-text.ts";
 
 /**
  * A ref is someone else's deck, kept as a read-only snapshot to read as a
@@ -35,12 +36,24 @@ const PACK_OWNER = "file";
 
 const OWNER_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
 const REPO_RE = /^[A-Za-z0-9._-]+$/;
-const DECK_RE = /^[^/\\\s@]+$/;
+/**
+ * A ref's deck name: letters, marks, and digits of any script, dots, dashes, and underscores, not
+ * first a dash. It is chosen by whoever made the pack or the repository, and dek prints it in the
+ * commands it suggests and in AGENTS.md, inside a code span: no shell, code span, or command line
+ * reads anything in it.
+ */
+const DECK_RE = /^[\p{L}\p{M}\p{N}._][\p{L}\p{M}\p{N}._-]{0,63}$/u;
+
+/** Bytes a ref's deck name may take: its pack, `<deck>.tgz`, stays within a file name's 255. */
+const DECK_MAX_BYTES = 200;
 const SHA_RE = /^[0-9a-f]{40}$/;
 const DIGEST_RE = /^[0-9a-f]{64}$/;
 
-const REF_HINT =
-  "name a ref as owner/repo/deck, e.g. hajimism/dek/why-dek or hajimism/dek/why-dek@v1, or a pack's as file/<deck>";
+/** What a ref's deck name may hold, as a hint says it. */
+export const REF_DECK_NAME_RULE =
+  "a ref names its deck with up to 64 letters, digits, dots, dashes, and underscores, none a person cannot see, not first a dash, each accented letter one character (NFC)";
+
+const REF_HINT = `name a ref as owner/repo/deck, e.g. hajimism/dek/why-dek or hajimism/dek/why-dek@v1, or a pack's as file/<deck>; ${REF_DECK_NAME_RULE}`;
 
 /** Where a pack's ref keeps its pack, relative to the project root: committed, never ignored. */
 export function packFile(deck: string): string {
@@ -78,9 +91,23 @@ export function isPinFor(source: RefSource, pin: string): boolean {
   return source.kind === "file" ? DIGEST_RE.test(pin) : SHA_RE.test(pin);
 }
 
-/** True for a deck name a ref can carry: no slash, space, or @, and not . or .. */
+/**
+ * True for a deck name a ref can carry: see DECK_RE; not . or ..; composed (NFC), since a file
+ * system that ignores the form would give two spellings of one name one folder; and with no
+ * character a person cannot see. A pack's author chooses it, and dek prints it as the ref's name,
+ * as in AGENTS.md.
+ */
 export function isRefDeckName(deck: string | undefined): deck is string {
-  return deck !== undefined && DECK_RE.test(deck) && deck !== "." && deck !== "..";
+  return (
+    deck !== undefined &&
+    DECK_RE.test(deck) &&
+    deck === deck.normalize("NFC") &&
+    Buffer.byteLength(deck) <= DECK_MAX_BYTES &&
+    // DECK_RE takes no control character; a letter or a mark can still be one a person cannot see.
+    !holdsHidden(deck) &&
+    deck !== "." &&
+    deck !== ".."
+  );
 }
 
 export function parseRefSource(input: string): RefSource {
@@ -133,22 +160,39 @@ export function parseRefSource(input: string): RefSource {
  */
 function parseGithubUrl(input: string): GithubRefSource {
   const url = new URL(input);
-  const [owner = "", repo = "", kind, rev, ...rest] = url.pathname.split("/").filter(Boolean);
-  const decks = rest.indexOf("decks");
-  const deck = decks === -1 ? undefined : rest[decks + 1];
+  const [owner = "", repo = "", kind, rev, ...encoded] = url.pathname.split("/").filter(Boolean);
+  // The folders after the rev as the repository names them; GitHub's link encodes any but ASCII.
+  const rest = decodeSegments(encoded);
+  const decks = rest?.indexOf("decks") ?? -1;
+  const deck = decks === -1 ? undefined : rest?.[decks + 1];
   if (
     url.hostname !== "github.com" ||
     (kind !== "tree" && kind !== "blob") ||
     !rev ||
+    rest === undefined ||
     deck === undefined
   ) {
     throw new DekError(`"${input}" is not a link to a deck on GitHub`, {
       hint: "link to the deck's folder, e.g. https://github.com/hajimism/dek/tree/main/sample/decks/why-dek, or name it as owner/repo/deck",
     });
   }
+  if (!isRefDeckName(deck)) {
+    throw new DekError(`"${input}" is not a link to a deck a ref can name`, {
+      hint: REF_DECK_NAME_RULE,
+    });
+  }
   const source = parseRefSource(`${owner}/${repo.replace(/\.git$/, "")}/${deck}@${rev}`);
   if (source.kind !== "github") {
     throw new DekError(`"${input}" is not a link to a deck on GitHub`, { hint: REF_HINT });
   }
   return { ...source, path: rest.slice(0, decks + 2).join("/") };
 }
+
+/** Each segment of a link's path decoded, or nothing when one is not valid percent-encoding. */
+function decodeSegments(segments: string[]): string[] | undefined {
+  try {
+    return segments.map((segment) => decodeURIComponent(segment));
+  } catch {
+    return undefined;
+  }
+}