@hajimism/dek 0.3.2 → 0.4.0

package/src/core/pptx.ts

@@ -3,7 +3,8 @@ 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 +12,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 +30,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 +67,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

@@ -2,11 +2,13 @@ import { DekError } from "./error.ts";
 
 /**
  * A ref is someone else's deck, kept as a read-only snapshot to read as a
- * model. dek.toml `[refs]` pins each one to a commit; the snapshot under
- * `refs/owner/repo/deck` is only a copy of that commit and can be fetched again.
+ * model. dek.toml `[refs]` pins each one: a deck on GitHub to a commit, a pack
+ * to a digest of its files. The snapshot under `refs/` is only a copy of what
+ * the pin names, fetched or unpacked again whenever it is missing.
  * This module only names refs; `ref.ts` fetches and stores them.
  */
-export type RefSource = {
+export type GithubRefSource = {
+  kind: "github";
   /** `owner/repo/deck`, the key in dek.toml `[refs]`. */
   name: string;
   owner: string;
@@ -18,13 +20,44 @@ export type RefSource = {
   path?: string;
 };
 
+/** A deck handed over as a file by `dekc pack`, committed as `packs/<deck>.tgz`. */
+export type FileRefSource = {
+  kind: "file";
+  /** `file/<deck>`, the key in dek.toml `[refs]`. */
+  name: string;
+  deck: string;
+};
+
+export type RefSource = GithubRefSource | FileRefSource;
+
+/** The first segment of a pack's ref name; no GitHub owner may take it, so refs/ never overlaps. */
+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";
+/** 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, 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 {
+  return `packs/${deck}.tgz`;
+}
 
 /** True for `owner/repo/deck[@rev]` or a GitHub link, which a deck name never is. */
 export function isRefName(arg: string): boolean {
@@ -34,14 +67,15 @@ export function isRefName(arg: string): boolean {
   if (arg.startsWith(".") || arg.startsWith("/") || arg.startsWith("~")) {
     return false;
   }
-  return arg.split("@")[0]?.split("/").length === 3;
+  const segments = arg.split("@")[0]?.split("/") ?? [];
+  return segments.length === 3 || (segments.length === 2 && segments[0] === PACK_OWNER);
 }
 
-/** A valid `owner/repo/deck` with no rev: the form dek.toml `[refs]` keys take. */
+/** A valid `owner/repo/deck` with no rev, or a pack's `file/<deck>`: the form dek.toml `[refs]` keys take. */
 export function isPlainRefName(name: string): boolean {
   try {
     const source = parseRefSource(name);
-    return source.rev === undefined && source.name === name;
+    return (source.kind === "file" || source.rev === undefined) && source.name === name;
   } catch {
     return false;
   }
@@ -51,6 +85,26 @@ export function isPinnedRev(rev: string): boolean {
   return SHA_RE.test(rev);
 }
 
+/** True when `pin` has the form a ref of this kind is pinned with: a commit, or a pack's digest. */
+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: see DECK_RE; not . or ..; and composed (NFC), since a
+ * file system that ignores the form would give two spellings of one name one folder.
+ */
+export function isRefDeckName(deck: string | undefined): deck is string {
+  return (
+    deck !== undefined &&
+    DECK_RE.test(deck) &&
+    deck === deck.normalize("NFC") &&
+    Buffer.byteLength(deck) <= DECK_MAX_BYTES &&
+    deck !== "." &&
+    deck !== ".."
+  );
+}
+
 export function parseRefSource(input: string): RefSource {
   const trimmed = input.trim();
   if (/^https?:\/\//i.test(trimmed)) {
@@ -60,6 +114,17 @@ export function parseRefSource(input: string): RefSource {
   const path = at === -1 ? trimmed : trimmed.slice(0, at);
   const rev = at === -1 ? undefined : trimmed.slice(at + 1);
   const [owner, repo, deck, ...extra] = path.split("/");
+  if (owner === PACK_OWNER && deck === undefined) {
+    if (rev !== undefined || !isRefDeckName(repo)) {
+      throw new DekError(`"${input}" is not a ref name`, { hint: REF_HINT });
+    }
+    return { kind: "file", name: `${PACK_OWNER}/${repo}`, deck: repo };
+  }
+  if (owner?.toLowerCase() === PACK_OWNER && deck !== undefined) {
+    throw new DekError(`"${input}" is not a ref name`, {
+      hint: "file is kept for packs, so no GitHub owner of that name can be pinned; name a pack's ref as file/<deck>",
+    });
+  }
   const valid =
     extra.length === 0 &&
     owner !== undefined &&
@@ -68,15 +133,13 @@ export function parseRefSource(input: string): RefSource {
     REPO_RE.test(repo) &&
     repo !== "." &&
     repo !== ".." &&
-    deck !== undefined &&
-    DECK_RE.test(deck) &&
-    deck !== "." &&
-    deck !== ".." &&
+    isRefDeckName(deck) &&
     (rev === undefined || /^[^\s@]+$/.test(rev));
   if (!valid) {
     throw new DekError(`"${input}" is not a ref name`, { hint: REF_HINT });
   }
   return {
+    kind: "github",
     name: `${owner}/${repo}/${deck}`,
     owner,
     repo,
@@ -90,21 +153,41 @@ export function parseRefSource(input: string): RefSource {
  * link people copy from a browser. A branch name with a slash cannot be told
  * apart from the path, so such a branch goes after `@` instead.
  */
-function parseGithubUrl(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;
+  }
+}