@hajimism/dek 0.3.3 → 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

@@ -35,12 +35,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, 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 +90,19 @@ 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 ..; 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 !== "..";
+  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 {
@@ -133,22 +155,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;
+  }
+}

package/src/core/ref.ts

@@ -1,12 +1,21 @@
-import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
 import { mkdir, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { z } from "zod";
 import { loadConfig } from "./config.ts";
 import { DekError } from "./error.ts";
-import { parseRefSource, type RefSource } from "./ref-name.ts";
-import { listSlides, resolveProject } from "./resolve.ts";
-import { outputDir } from "./safe-fs.ts";
+import { shellQuote } from "./escape.ts";
+import { listShown } from "./prose.ts";
+import {
+  isPlainRefName,
+  isRefDeckName,
+  packFile,
+  parseRefSource,
+  REF_DECK_NAME_RULE,
+  type RefSource,
+} from "./ref-name.ts";
+import { listSlides, type Project, resolveProject } from "./resolve.ts";
+import { followInside, outputDir } from "./safe-fs.ts";
 
 export {
   isPinnedRev,
@@ -24,6 +33,49 @@ function isLink(path: string): boolean {
   }
 }
 
+/** The first link on the way from `<root>/<top>` down to `path`, both included, if any. */
+function linkUnder(root: string, top: "refs" | "packs", path: string): string | undefined {
+  let at = join(root, top);
+  for (const segment of ["", ...relative(at, path).split(sep)]) {
+    at = join(at, segment);
+    if (isLink(at)) {
+      return at;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Refuses a link on the way to the snapshot at `dir`. refs/ is dek's own folder, which a cloned
+ * project can still commit: a link there, even one that stays in the project, would aim a
+ * snapshot's swap and its delete at what it points to, such as a deck under decks/.
+ */
+export function refuseLinkUnderRefs(root: string, dir: string): void {
+  const link = linkUnder(root, "refs", dir);
+  if (link !== undefined) {
+    const rel = relative(root, link);
+    throw new DekError(`${rel} is a symlink; dek follows no link under refs/`, {
+      path: link,
+      hint: `remove ${rel}: refs/ holds only the snapshots \`dekc ref\` writes, and the next read of a pinned ref fetches it again`,
+    });
+  }
+}
+
+/**
+ * Refuses a link at packs/, or at the copy of `deck`'s pack kept there. dek writes and removes
+ * that copy by name, so through a link it would overwrite, or delete, what the link points to.
+ */
+export function refuseLinkUnderPacks(root: string, deck: string): void {
+  const link = linkUnder(root, "packs", join(root, packFile(deck)));
+  if (link !== undefined) {
+    const rel = relative(root, link);
+    throw new DekError(`${rel} is a symlink; dek follows no link under packs/`, {
+      path: link,
+      hint: `remove ${rel}, then run \`dekc ref <file>.tgz\` with the pack you were sent: packs/ holds the copies it keeps, as plain files`,
+    });
+  }
+}
+
 /** Written into each snapshot; its presence is what makes a directory a ref. */
 export const REF_MARKER = ".ref.json";
 
@@ -44,8 +96,10 @@ export function refDir(root: string, name: string): string {
 
 /** The marker of a snapshot, or nothing when it is missing or not one dek wrote. */
 export function readRefMeta(dir: string): RefMeta | undefined {
-  const path = join(dir, REF_MARKER);
-  if (!existsSync(path)) {
+  const marker = join(dir, REF_MARKER);
+  // dek writes the marker as a plain file; a link out of the snapshot is none of its.
+  const path = existsSync(marker) ? followInside(marker, dir) : undefined;
+  if (path === undefined) {
     return undefined;
   }
   try {
@@ -56,6 +110,87 @@ export function readRefMeta(dir: string): RefMeta | undefined {
   }
 }
 
+/**
+ * The snapshot `dir` is in, and the ref it holds: the outermost folder from `dir` up that is one
+ * dek wrote. A ref may carry a dek.toml, and a marker, of its own in its deck's assets; neither
+ * hides the snapshot around them or names it. A marker anywhere else makes nothing a ref.
+ */
+function refAround(dir: string): { dir: string; name: string } | undefined {
+  let found: { dir: string; name: string } | undefined;
+  for (let at = resolve(dir); ; at = dirname(at)) {
+    const name = snapshotName(at);
+    if (name !== undefined) {
+      found = { dir: at, name };
+    }
+    if (dirname(at) === at) {
+      return found;
+    }
+  }
+}
+
+/**
+ * The ref `dir` holds, when it is a snapshot as dek writes one: a dek.toml beside a marker that
+ * names a ref, at that ref's own place under a project's refs/.
+ */
+function snapshotName(dir: string): string | undefined {
+  if (!isThere(join(dir, "dek.toml"))) {
+    return undefined;
+  }
+  const name = readRefMeta(dir)?.name;
+  if (name === undefined || !isPlainRefName(name)) {
+    return undefined;
+  }
+  // The same folder, not the same spelling: a disk that ignores case, or a link at refs/, gives
+  // the path to a snapshot another spelling than its name.
+  const place = refDir("", name);
+  const project = resolve(dir, ...place.split(sep).map(() => ".."));
+  return isSameFolder(join(project, place), dir) ? name : undefined;
+}
+
+function isSameFolder(a: string, b: string): boolean {
+  try {
+    const [one, other] = [statSync(a), statSync(b)];
+    return one.dev === other.dev && one.ino === other.ino;
+  } catch {
+    return false;
+  }
+}
+
+function isThere(path: string): boolean {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Refuses `dir` when it is inside a ref: no command, the dev server's included, runs or writes there. */
+export function refuseInsideRef(dir: string): void {
+  const ref = refAround(dir);
+  if (ref !== undefined) {
+    throw new DekError("this directory is inside a ref; refs are read-only", {
+      path: ref.dir,
+      hint: `run dek from your own project instead: \`dekc show ${ref.name} <slug>\``,
+    });
+  }
+}
+
+/** The project around `cwd`, which is the user's own: never one inside a ref. */
+export function requireProject(cwd: string): Project {
+  const project = resolveProject(cwd);
+  refuseInsideRef(project.root);
+  return project;
+}
+
+/** What a command that writes says when it is handed a ref by name. */
+export function refReadOnlyError(name: string): DekError {
+  const ref = shellQuote(name);
+  return new DekError(`"${name}" is a ref; refs are read-only`, {
+    hint: `start a deck on its theme with \`dekc new <name> --theme-from ${ref}\`, or read it with \`dekc show ${ref} <slug>\` and write what you need in your own deck's theme`,
+  });
+}
+
 export const LICENSE_NAMES = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"];
 
 /** The snapshot's license file, relative to the snapshot, when the source had one. */
@@ -81,7 +216,11 @@ export function refState(project: { root: string; configPath: string }, name: st
     name,
     ...(pinned !== undefined ? { pinned } : {}),
     dir,
-    fetched: pinned !== undefined && readRefMeta(dir)?.rev === pinned,
+    // Never through a link under refs/: one is fetched again, which refuses the link.
+    fetched:
+      pinned !== undefined &&
+      linkUnder(project.root, "refs", dir) === undefined &&
+      readRefMeta(dir)?.rev === pinned,
   };
 }
 
@@ -185,7 +324,16 @@ function repoDecks(files: RepoFiles): Array<{ name: string; prefix: string }> {
   });
 }
 
-/** The name of the one deck a pack holds; a pack of none, or of more, is refused. */
+/** Deck names as a hint lists them: only those a ref can carry. */
+function listDecks(names: string[]): string {
+  return listShown(
+    names,
+    isRefDeckName,
+    (count) => `${count} whose ${count === 1 ? "name" : "names"} a ref cannot carry`,
+  );
+}
+
+/** The name of the one deck a pack holds; a pack of none, of more, or of one no ref can name is refused. */
 export function deckOfPack(files: RepoFiles): string {
   const names = [...new Set(repoDecks(files).map((deck) => deck.name))].sort();
   const [name, ...others] = names;
@@ -195,10 +343,15 @@ export function deckOfPack(files: RepoFiles): string {
     });
   }
   if (others.length > 0) {
-    throw new DekError(`the pack holds more than one deck: ${names.join(", ")}`, {
+    throw new DekError(`the pack holds more than one deck: ${listDecks(names)}`, {
       hint: `a pack is one deck; ${PACK_HINT}`,
     });
   }
+  if (!isRefDeckName(name)) {
+    throw new DekError("the pack's deck has a name a ref cannot carry", {
+      hint: `${REF_DECK_NAME_RULE}; ask its author to rename the deck's folder and pack it again`,
+    });
+  }
   return name;
 }
 
@@ -218,14 +371,19 @@ export function findDeckInRepo(files: RepoFiles, source: RefSource): string {
     throw new DekError(`${repo} has no deck "${source.deck}"`, {
       hint:
         names.length > 0
-          ? `decks in ${repo}: ${names.join(", ")}`
+          ? `decks in ${repo}: ${listDecks(names)}`
           : `${repo} holds no dek project (decks/<name>/script.md beside a dek.toml)`,
     });
   }
   if (others.length > 0) {
     const paths = matches.map((deck) => `${deck.prefix}decks/${deck.name}`).sort();
+    const listed = listShown(
+      paths,
+      (path) => path.split("/").every(isRefDeckName),
+      (count) => `${count} whose ${count === 1 ? "path" : "paths"} a hint cannot show`,
+    );
     throw new DekError(`${repo} has more than one deck named "${source.deck}"`, {
-      hint: `pass the GitHub link to the one you mean; they are at ${paths.join(", ")}`,
+      hint: `pass the GitHub link to the one you mean; they are at ${listed}`,
     });
   }
   return match.prefix;
@@ -319,13 +477,11 @@ export async function writeSnapshot(
   pin: string,
   snapshot: Snapshot,
 ): Promise<{ dir: string; license: string | null; path: string }> {
-  // refs/ is dek's; a link on the way would aim the swap below, and its delete, elsewhere.
   const refsDir = join(root, "refs");
   const dir = refDir(root, name);
+  // A link on the way would aim the swap below, and its delete, at what it points to.
+  refuseLinkUnderRefs(root, dir);
   outputDir(dirname(dir), root);
-  if (isLink(dir)) {
-    await rm(dir);
-  }
   const suffix = `${process.pid}-${Date.now().toString(36)}`;
   const temp = join(refsDir, `.tmp-${suffix}`);
   const old = join(refsDir, `.old-${suffix}`);

package/src/core/resolve.ts

@@ -1,10 +1,10 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import { deckPaths } from "./deck-paths.ts";
 import { DekError } from "./error.ts";
 import { walkUp } from "./optional.ts";
 import { parseScript } from "./parse.ts";
-import { deckProjectRoot } from "./path.ts";
+import { deckProjectRoot, isInside } from "./path.ts";
 import { readSourceIfExists, requireInside } from "./safe-fs.ts";
 import type { Deck, Section } from "./schema.ts";
 import { suggest } from "./suggest.ts";
@@ -14,6 +14,11 @@ export type ProjectDeck = {
   dir: string;
   scriptPath: string;
   deck: Deck;
+  /**
+   * Set on a ref's deck: the folder that stands for its `.cache`, in the project that reads it,
+   * and that project's root. A snapshot is never written once `dekc ref` wrote it.
+   */
+  cache?: { dir: string; root: string };
 };
 
 export type Project = {
@@ -28,11 +33,6 @@ export type ResolvedDeck = {
   deck: ProjectDeck;
 };
 
-/** The file's text, or nothing when there is no such file. */
-export function readTextIfExists(path: string): string | undefined {
-  return existsSync(path) ? readFileSync(path, "utf8") : undefined;
-}
-
 /**
  * A file of the deck's, or nothing when there is none. It may be a symlink to elsewhere in the
  * project, but not out of it: what a deck reads, a build publishes.
@@ -150,14 +150,25 @@ function loadDecks(root: string): {
   if (!existsSync(decksDir)) {
     return { decks: [], failed: [] };
   }
-  if (!statSync(decksDir).isDirectory()) {
+  // A link out of the project would list, serve, and watch the folders of wherever it leads. It
+  // may lead elsewhere in the project, but not into a hidden folder; a folder has no kind to keep.
+  const realRoot = realpathSync(root);
+  const realDecks = realpathSync(decksDir);
+  const rel = relative(realRoot, realDecks);
+  if (!isInside(realDecks, realRoot) || rel.split(sep).some((part) => part.startsWith("."))) {
+    throw new DekError("decks leads outside the project", {
+      path: decksDir,
+      hint: "dek follows decks/ only to a folder inside the project and outside hidden folders; move the decks into the project instead",
+    });
+  }
+  if (!statSync(realDecks).isDirectory()) {
     throw new DekError("decks is not a directory", { path: decksDir });
   }
 
   const decks: ProjectDeck[] = [];
   const failed: Project["failed"] = [];
 
-  for (const entry of readdirSync(decksDir, { withFileTypes: true })
+  for (const entry of readdirSync(realDecks, { withFileTypes: true })
     .filter((item) => item.isDirectory())
     .sort((a, b) => a.name.localeCompare(b.name))) {
     const loaded = readDeck(root, entry.name);

package/src/core/shot/morph.ts

@@ -62,7 +62,7 @@ export async function shotMorph(
   const step = stepKey(fromSection.beats, from.beatIndex);
 
   const html = videoDocument(resolved, options.playerScript);
-  const entry = morphEntry(deck.dir, options.from, options.to, at, html);
+  const entry = morphEntry(deck, options.from, options.to, at, html);
   if (!entry.cached) {
     await requirePlaywright(
       {

package/src/core/shot/motion.ts

@@ -2,7 +2,6 @@ import { readFileSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
 import pkg from "../../../package.json";
 import { DekError } from "../error.ts";
-import { deckProjectRoot } from "../path.ts";
 import { type PlaywrightRunner, requirePlaywright } from "../playwright.ts";
 import { deckStops, retreat } from "../position.ts";
 import { asResolvedDeck, type ResolvedDeck, requireSection } from "../resolve.ts";
@@ -103,7 +102,7 @@ export async function shotMotion(
   const key = `${JSON.stringify([pkg.version, SHEET_LAYOUT_VERSION, MOTION_FRACTIONS, plan.from, beats, title])}\0${html}`;
   // Each step keeps its own entry, so runs of different steps neither evict nor race each other.
   const capture = options.step === undefined ? [section.slug] : [section.slug, String(first)];
-  const bundle = bundleEntry(deck.dir, "motion", capture, key);
+  const bundle = bundleEntry(deck, "motion", capture, key);
   const manifest = join(bundle.dir, "motion.json");
   const cached = readMotionManifest(manifest, bundle.dir);
   if (cached) {
@@ -112,7 +111,7 @@ export async function shotMotion(
   }
   // Chromium writes the frames and sheets by name, so no link may stand where one goes.
   dropLinks(bundle.dir);
-  dropLinks(outputDir(join(bundle.dir, "frames"), deckProjectRoot(deck.dir)));
+  dropLinks(outputDir(join(bundle.dir, "frames"), bundle.root));
 
   const response = await requirePlaywright(
     {

package/src/core/shot/still.ts

@@ -84,7 +84,7 @@ export async function shotSheet(
   }));
   // The tiles' paths hash what they show, so the key changes whenever a tile does.
   const bundle = bundleEntry(
-    deck.dir,
+    deck,
     "sheets",
     [],
     JSON.stringify([SHEET_LAYOUT_VERSION, deck.deck.title, cells]),
@@ -136,7 +136,7 @@ export function still(
   step: string = stepKey(section.beats, beatIndex),
 ): Still {
   const html = renderSlideHtml(sources, section.slug, beatIndex);
-  const entry = stillEntry(deck.dir, section, beatIndex, html);
+  const entry = stillEntry(deck, section, beatIndex, html);
   return { html, slug: section.slug, step, screenshotPath: entry.path, entry };
 }