@hajimism/dek 0.3.3 → 0.5.0

package/src/core/visual.ts

@@ -4,7 +4,6 @@ import { EDGES, type Edge } from "./overflow.ts";
 import { renderPdfHtml } from "./pdf.ts";
 import {
   askPlaywright,
-  type ContrastOrigin,
   type FillFinding,
   type PageAction,
   type PagesResponse,
@@ -83,7 +82,7 @@ async function visualDeck(
     return { diagnostics: [], fills: [] };
   }
 
-  const actions: PageAction[] = ["overflow", "contrast", "fill"];
+  const actions: PageAction[] = ["overflow", "contrast", "fill", "breaks", "alignment"];
   const viewport = logicalSize(deck.deck.ratio);
   const cache = visualCache(deck.dir, { viewport, actions });
   const keyed = pages.map((page) => {
@@ -137,6 +136,8 @@ async function visualDeck(
         contrasts: all.flatMap((page) => page.contrasts),
         drawErrors: all.flatMap((page) => page.drawErrors),
         collisions: all.flatMap((page) => page.collisions ?? []),
+        lineBreaks: all.flatMap((page) => page.lineBreaks ?? []),
+        misalignments: all.flatMap((page) => page.misalignments ?? []),
       },
       deck.dir,
     ),
@@ -147,13 +148,20 @@ async function visualDeck(
   };
 }
 
-const NOTHING_FOUND: PageFindings = {
-  overflows: [],
-  contrasts: [],
-  drawErrors: [],
-  collisions: [],
-  fills: [],
-};
+/** A page's findings before any is found, each list its own to push to. */
+function noFindings(): PageFindings {
+  return {
+    overflows: [],
+    contrasts: [],
+    drawErrors: [],
+    collisions: [],
+    fills: [],
+    lineBreaks: [],
+    misalignments: [],
+  };
+}
+
+const NOTHING_FOUND: PageFindings = noFindings();
 
 /** A page's findings name its slide and step, which no two pages of one run share. */
 function pageId(page: { slug: string; step: string }): string {
@@ -165,13 +173,7 @@ function findingsByPage(response: PagesResponse): Map<string, PageFindings> {
   const pages = new Map<string, PageFindings>();
   const of = (finding: { slug: string; step: string }): PageFindings => {
     const id = pageId(finding);
-    const found = pages.get(id) ?? {
-      overflows: [],
-      contrasts: [],
-      drawErrors: [],
-      collisions: [],
-      fills: [],
-    };
+    const found = pages.get(id) ?? noFindings();
     pages.set(id, found);
     return found;
   };
@@ -190,6 +192,12 @@ function findingsByPage(response: PagesResponse): Map<string, PageFindings> {
   for (const finding of response.fills ?? []) {
     of(finding).fills.push(finding);
   }
+  for (const finding of response.lineBreaks ?? []) {
+    of(finding).lineBreaks.push(finding);
+  }
+  for (const finding of response.misalignments ?? []) {
+    of(finding).misalignments.push(finding);
+  }
   return pages;
 }
 
@@ -306,9 +314,14 @@ function groupBySteps<T extends { step: string }>(items: T[], key: (item: T) =>
 /**
  * Where to fix low contrast. Text the theme alone draws too faint is fixed once in theme.css
  * for every slide that uses the pair; a slide that fixed it in its own CSS would leave the rest.
+ * Text only the slide's CSS shows was never measured on the theme alone, so both are named.
  */
-function contrastHint(origin: ContrastOrigin | undefined, threshold: number, slug: string): string {
+function contrastHint(sample: ContrastSample, threshold: number): string {
+  const { origin, slug } = sample;
   const own = `slides/${slug}.css`;
+  if (sample.onlyWithSlideCss) {
+    return `without ${own} it does not show, so dek cannot tell whether theme.css alone draws it below ${threshold}:1: fix the pair in ${own}, or in theme.css if the colors are the theme's`;
+  }
   switch (origin) {
     case "theme":
       return `theme.css alone draws it below ${threshold}:1: fix the pair in theme.css, where one change reaches every slide that uses it`;
@@ -324,8 +337,17 @@ function contrastHint(origin: ContrastOrigin | undefined, threshold: number, slu
   }
 }
 
-/** The file to change: the one the origin names, or the slide itself when it is not known. */
-function contrastPath(origin: ContrastOrigin | undefined, slug: string, paths: DeckPaths): string {
+/**
+ * The file to change: the one the origin names, or the slide itself when it is not known. Text
+ * only the slide's CSS shows goes to that CSS, which the hint names first.
+ */
+function contrastPath(
+  { origin, slug, onlyWithSlideCss }: ContrastSample,
+  paths: DeckPaths,
+): string {
+  if (onlyWithSlideCss) {
+    return paths.slide(slug, ".css");
+  }
   switch (origin) {
     case "theme":
       return paths.theme;
@@ -352,9 +374,139 @@ function visualDiagnostics(response: PagesResponse, deckDir: string): Diagnostic
     ...groupBySteps(response.collisions ?? [], collisionKey).map((group) =>
       collisionDiagnostic(group, paths),
     ),
+    ...groupBySteps(response.lineBreaks ?? [], lineBreakKey).map((group) =>
+      lineBreakDiagnostic(group, paths),
+    ),
+    ...groupBySteps(response.misalignments ?? [], misalignmentKey).map((group) =>
+      misalignmentDiagnostic(group, paths),
+    ),
   ];
 }
 
+type MisalignmentSample = NonNullable<PagesResponse["misalignments"]>[number];
+
+function misalignmentKey(m: MisalignmentSample): string {
+  return [m.slug, m.box, m.text ?? "", m.other, m.otherText ?? "", m.edge, m.of].join("\0");
+}
+
+/** How the message names an edge two items share. */
+const EDGE_NAMES: Record<MisalignmentSample["edge"], string> = {
+  top: "tops",
+  middle: "middles",
+  bottom: "bottoms",
+  left: "left edges",
+  center: "centers",
+  right: "right edges",
+};
+
+/**
+ * Two items that nearly line up and do not. The fix depends on the edge: a start lines up with
+ * the same space before it, an end with one size, a middle with one way of centering, and text in
+ * cards that line up with one padding.
+ */
+function misalignmentDiagnostic(
+  { first, items, steps }: StepGroup<MisalignmentSample>,
+  paths: DeckPaths,
+): Diagnostic {
+  // By the most they miss at any step, so the fix covers the worst beat.
+  const by = Math.max(...items.map((item) => item.by));
+  const pair = `${describeTarget(first.box, first.text)}and ${describeTarget(first.other, first.otherText).trimEnd()}`;
+  const where =
+    first.of === "text"
+      ? `almost start their text ${first.edge === "left" ? "at one left edge" : "on one line"}`
+      : `almost line up at their ${EDGE_NAMES[first.edge]}`;
+  const css = `slides/${first.slug}.css`;
+  const both = `${first.box} and ${first.other}`;
+  const why = "an edge a few pixels off reads as a mistake, not a choice";
+  const hint =
+    first.of === "text"
+      ? `give ${both} the same padding in ${css}, so their text starts on one line`
+      : first.edge === "top" || first.edge === "left"
+        ? `line ${first.box} up with ${first.other} in ${css}, with the same margin, padding, or alignment: ${why}`
+        : first.edge === "bottom" || first.edge === "right"
+          ? `give ${both} one ${first.edge === "bottom" ? "height" : "width"} in ${css}, with align-items: stretch or the same size: ${why}`
+          : `center ${both} on one line in ${css}, with align-items: center or the same margins: ${why}`;
+  return diag("DEK036", {
+    message: `${pair} ${where}, ${by}px apart, ${atSteps(steps)}`,
+    path: paths.slide(first.slug, ".html"),
+    slug: first.slug,
+    hint,
+    data: {
+      box: first.box,
+      ...(first.text ? { text: first.text } : {}),
+      other: first.other,
+      ...(first.otherText ? { otherText: first.otherText } : {}),
+      edge: first.edge,
+      of: first.of,
+      by,
+      steps,
+    },
+  });
+}
+
+type LineBreakSample = NonNullable<PagesResponse["lineBreaks"]>[number];
+
+function lineBreakKey(b: LineBreakSample): string {
+  return [b.slug, b.box, b.text ?? "", b.kind, ...b.lines].join("\0");
+}
+
+/** Where a line ends: the end of one line and the start of the next, as far as either reads. */
+function breakAt(lines: string[], phrased: string[]): string {
+  const differs = lines.findIndex((line, at) => line !== phrased[at]);
+  const at = Math.max(0, Math.min(differs, lines.length - 2));
+  const end = [...(lines[at] ?? "")];
+  const start = [...(lines[at + 1] ?? "")];
+  const half = SNIPPET_CHARS / 2;
+  const before = end.length > half ? `…${end.slice(-half).join("")}` : end.join("");
+  const after = start.length > half ? `${start.slice(0, half).join("")}…` : start.join("");
+  return `${before} / ${after}`;
+}
+
+/**
+ * A line break the audience trips over. One inside a phrase is fixed where Japanese is told to
+ * break by phrase: on `.slide` in theme.css, for every slide, unless a rule takes it away from
+ * this text. A remnant on a last line is the text's own to fix, or the theme's text-wrap.
+ */
+function lineBreakDiagnostic(
+  { first, steps }: StepGroup<LineBreakSample>,
+  paths: DeckPaths,
+): Diagnostic {
+  const target = describeTarget(first.box, first.text);
+  const css = `slides/${first.slug}.css`;
+  const yourself = "break the line yourself with <br>";
+  const common = {
+    slug: first.slug,
+    data: {
+      kind: first.kind,
+      box: first.box,
+      ...(first.text ? { text: first.text } : {}),
+      lines: first.lines,
+      ...(first.kind === "split" ? { phrased: first.phrased } : { tail: first.tail }),
+      steps,
+    },
+  };
+  if (first.kind === "split") {
+    const theme = first.wordBreak !== "auto-phrase";
+    return diag("DEK035", {
+      message: `${target}breaks a line inside a phrase, at "${breakAt(first.lines, first.phrased)}", ${atSteps(steps)}`,
+      path: theme ? paths.theme : paths.slide(first.slug, ".html"),
+      hint: theme
+        ? `add word-break: auto-phrase to .slide in theme.css, so Japanese breaks between phrases on every slide; or ${yourself} where its sense breaks`
+        : `a rule gives it word-break: normal where .slide breaks by phrase: remove it from ${css} or theme.css, or ${yourself} where its sense breaks`,
+      ...common,
+    });
+  }
+  const evened = first.textWrap === "pretty" || first.textWrap === "balance";
+  return diag("DEK035", {
+    message: `${target}leaves "${first.tail}" alone on its last line ${atSteps(steps)}`,
+    path: paths.slide(first.slug, ".html"),
+    hint: evened
+      ? `reword it so its last line holds more, or ${yourself} earlier`
+      : `even out its lines with text-wrap: pretty, or balance for a heading, in ${css} or for every slide in theme.css; or reword it, or ${yourself}`,
+    ...common,
+  });
+}
+
 type CollisionSample = NonNullable<PagesResponse["collisions"]>[number];
 
 function collisionKey(c: CollisionSample): string {
@@ -444,9 +596,15 @@ function shownRatio(sample: ContrastSample): number {
 }
 
 function contrastKey(c: ContrastSample): string {
-  return [c.slug, c.box, c.text ?? "", shownRatio(c), contrastThreshold(c), c.origin ?? ""].join(
-    "\0",
-  );
+  return [
+    c.slug,
+    c.box,
+    c.text ?? "",
+    shownRatio(c),
+    contrastThreshold(c),
+    c.origin ?? "",
+    c.onlyWithSlideCss ?? "",
+  ].join("\0");
 }
 
 function overflowWhere(amounts: Partial<Record<Edge, number>>): string {
@@ -542,9 +700,9 @@ function contrastDiagnostic(
   const colors = fg && bg ? ` (${fg} on ${bg})` : "";
   return diag("DEK031", {
     message: `${describeTarget(first.box, first.text)}has contrast ${ratio}${colors}, below ${threshold}:1${size} ${atSteps(steps)}`,
-    path: contrastPath(first.origin, first.slug, paths),
+    path: contrastPath(first, paths),
     slug: first.slug,
-    hint: contrastHint(first.origin, threshold, first.slug),
+    hint: contrastHint(first, threshold),
     data: {
       box: first.box,
       ...(first.text ? { text: first.text } : {}),

package/src/core/voice.ts

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { z } from "zod";
 import type { VoiceDict } from "./cue.ts";
 import { deckPaths } from "./deck-paths.ts";
 import { DekError } from "./error.ts";
+import { compareCodeUnits } from "./order.ts";
 import { cacheDir, deckProjectRoot } from "./path.ts";
 import { readDeckFile } from "./resolve.ts";
 import { writeInside } from "./safe-fs.ts";
@@ -184,7 +185,7 @@ export function loadVoiceDict(deckDir: string): VoiceDict {
 export function writeVoiceDict(deckDir: string, dict: VoiceDict): string {
   const path = deckPaths(deckDir).voiceDict;
   const body = Object.entries(dict)
-    .sort(([a], [b]) => a.localeCompare(b))
+    .sort(([a], [b]) => compareCodeUnits(a, b))
     .map(([key, entry]) => {
       const accent = entry.accent !== undefined ? `\naccent = ${entry.accent}` : "";
       return `[${escapeTomlKey(key)}]\nkana = ${JSON.stringify(entry.kana)}${accent}\n`;
@@ -269,10 +270,8 @@ export function parseTimelineJson(text: string, path?: string): Timeline {
 
 export function loadCachedTimeline(deckDir: string): Timeline | undefined {
   const path = voiceCacheFile(deckDir, "timeline.json");
-  if (!existsSync(path)) {
-    return undefined;
-  }
-  return parseTimelineJson(readFileSync(path, "utf8"), path);
+  const source = readDeckFile(deckDir, path);
+  return source === undefined ? undefined : parseTimelineJson(source, path);
 }
 
 export function tryLoadCachedTimeline(deckDir: string): Timeline | undefined {

package/src/core/zod.ts

@@ -1,5 +1,6 @@
 import type { z } from "zod";
 import { DekError } from "./error.ts";
+import { isPlainWord } from "./escape.ts";
 
 const REFERENCE = "https://hajimism.github.io/dek/reference/config.html";
 
@@ -21,10 +22,17 @@ export function parseFailure(error: unknown): string {
   );
 }
 
+/**
+ * Each issue as `path: message`. A key in the path is the file's text, which a cloned project or
+ * a pack brings along, so one that is no plain word shows as `<key>`: repeated, it could close a
+ * code span or start a line of its own.
+ */
 export function formatZodIssues(error: z.ZodError): string {
   return error.issues
     .map((issue) => {
-      const path = issue.path.join(".");
+      const path = issue.path
+        .map((key) => (isPlainWord(String(key)) ? String(key) : "<key>"))
+        .join(".");
       // "expected string, received undefined" says less than "required".
       const message =
         issue.code === "invalid_type" && /received undefined$/.test(issue.message)

package/src/server/auth.ts

@@ -78,6 +78,27 @@ function forbidden(reason: string): Response {
   return new Response(`Forbidden: ${reason}\n`, { status: 403 });
 }
 
+/**
+ * What every answer tells the browser: take its type as given, hand it to no other origin's
+ * page, and show it in no other origin's frame. Another site can still make the browser ask, but
+ * gets nothing to play, apply as a stylesheet, tell apart by whether it loaded, or frame. The
+ * frame rule goes on every answer, not only pages: the voice or a listing opened in a frame is
+ * a page too.
+ */
+const SAME_ORIGIN_ONLY = {
+  "x-content-type-options": "nosniff",
+  "cross-origin-resource-policy": "same-origin",
+  "content-security-policy": "frame-ancestors 'self'",
+} as const;
+
+/** `response` with SAME_ORIGIN_ONLY set; the server passes every answer through it. */
+export function keepToOwnOrigin(response: Response): Response {
+  for (const [name, value] of Object.entries(SAME_ORIGIN_ONLY)) {
+    response.headers.set(name, value);
+  }
+  return response;
+}
+
 /**
  * Who may read a response. The audience sees the slides as they are shown; the presenter also
  * sees what they are made from, and may move the deck.

package/src/server/dev.ts

@@ -1,10 +1,12 @@
 import { join } from "node:path";
 import { DekError } from "../core/error.ts";
 import type { PlaywrightRunner } from "../core/playwright.ts";
-import { locateDeck, type Project, resolveProject } from "../core/resolve.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 {
   clearance,
+  keepToOwnOrigin,
   mayRead,
   pairingResponse,
   ROUTE_EXPOSURE,
@@ -13,7 +15,12 @@ import {
 } from "./auth.ts";
 import type { EventFeed } from "./hub.ts";
 import { generateRemotePassword, lanUrls } from "./lan.ts";
-import { assertNoDevServer, removeDevServerLock, writeDevServerLock } from "./lock.ts";
+import {
+  assertNoDevServer,
+  devServerUrl,
+  removeDevServerLock,
+  writeDevServerLock,
+} from "./lock.ts";
 import { createDevPages } from "./pages.ts";
 import { createPairings, type Pairings } from "./pairing.ts";
 import { createProjectWatch } from "./project-watch.ts";
@@ -63,7 +70,12 @@ type Access = {
 type ServedRoutes = Omit<RouteContext, "upgrade">;
 
 export async function startDevServer(options: DevServerOptions): Promise<DevServer> {
-  const project = resolveProject(options.cwd);
+  // A ref is read where it is, never served: the server syncs into what it serves, and runs its
+  // slides' scripts in the browser at its own origin.
+  const project = requireProject(options.cwd);
+  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);
@@ -113,7 +125,7 @@ export async function startDevServer(options: DevServerOptions): Promise<DevServ
   }
 
   const port = server.port ?? 0;
-  const url = `http://127.0.0.1:${port}/`;
+  const url = devServerUrl(port);
   const remoteUrls = [...new Set([url, ...(access.remote ? lanUrls(port) : [])])];
   try {
     writeDevServerLock(project.root, url, access.password, scopedDeckName);
@@ -188,10 +200,17 @@ function listen(port: number | undefined, access: Access, routes: ServedRoutes)
     port: port ?? 0,
     // Never Bun's development error page: it shows the source and absolute paths to anyone.
     development: false,
-    fetch: (req, server) => answer(req, server, access, routes),
+    // Every answer dek writes leaves through one of these two, so none goes without
+    // keepToOwnOrigin. Bun answers a few requests itself before either runs: one its parser
+    // refuses (a bad request line, no Host, a body or headers too large) and an upgrade it
+    // cannot take; none of those has a body a page could use.
+    fetch: async (req, server) => {
+      const response = await answer(req, server, access, routes);
+      return response && keepToOwnOrigin(response);
+    },
     error(error) {
       console.error(error);
-      return new Response("Internal Server Error\n", { status: 500 });
+      return keepToOwnOrigin(new Response("Internal Server Error\n", { status: 500 }));
     },
     websocket: roomSockets(routes.rooms),
   });
@@ -222,7 +241,7 @@ function answer(req: Request, server: Bun.Server<WsData>, access: Access, routes
 }
 
 /** Each socket joins its deck's room; only a presenter's socket may move it or point in it. */
-function roomSockets(rooms: RouteContext["rooms"]): Bun.WebSocketHandler<WsData> {
+export function roomSockets(rooms: RouteContext["rooms"]): Bun.WebSocketHandler<WsData> {
   return {
     // A position or a point is a few dozen bytes; anything near this is neither.
     maxPayloadLength: 4 * 1024,

package/src/server/lock.ts

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { DekError } from "../core/error.ts";
-import { writeInside } from "../core/safe-fs.ts";
+import { readSourceIfExists, removeInside, writeInside } from "../core/safe-fs.ts";
 
 export type DevServerLock = {
   url: string;
@@ -15,7 +15,14 @@ function serverLockPath(root: string): string {
   return join(root, ".dek", "server.json");
 }
 
+/**
+ * Whether a process with this pid runs. Only a positive whole number names one process: 0 and a
+ * negative pid signal a whole group, which `kill` reports as alive.
+ */
 export function isPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
   try {
     process.kill(pid, 0);
     return true;
@@ -24,16 +31,52 @@ export function isPidAlive(pid: number): boolean {
   }
 }
 
+/** The hosts a dev server's URL in its lock names: it writes this machine's loopback address. */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]"]);
+
+/** The URL a dev server on `port` writes in its lock, as `URL` spells it: port 80 takes none. */
+export function devServerUrl(port: number): string {
+  return new URL(`http://127.0.0.1:${port}/`).href;
+}
+
+/**
+ * The lock's URL in the form the dev server writes it, `http://<loopback>:<port>/`, or nothing
+ * for any other. A server.json a repository brings along is its text, and the URL goes into
+ * hints and into the requests `dekc goto` sends. Port 80 is read with or without `:80`.
+ */
+function serverUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return undefined;
+  }
+  const served =
+    url.protocol === "http:" &&
+    LOOPBACK_HOSTS.has(url.hostname) &&
+    url.pathname === "/" &&
+    url.search === "" &&
+    url.hash === "" &&
+    url.username === "" &&
+    url.password === "";
+  const written = url.port === "" ? [url.href, `http://${url.hostname}:80/`] : [url.href];
+  return served && written.includes(value) ? url.href : undefined;
+}
+
 export function readDevServerLock(root: string): DevServerLock | undefined {
   const path = serverLockPath(root);
   if (!existsSync(path)) {
     return undefined;
   }
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8")) as DevServerLock;
-    if (typeof parsed.url === "string" && typeof parsed.pid === "number") {
+    const parsed = JSON.parse(readSourceIfExists(path, root) ?? "") as DevServerLock;
+    const url = serverUrl(parsed.url);
+    if (url !== undefined && typeof parsed.pid === "number") {
       return {
-        url: parsed.url,
+        url,
         pid: parsed.pid,
         ...(typeof parsed.password === "string" ? { password: parsed.password } : {}),
         ...(typeof parsed.deck === "string" ? { deck: parsed.deck } : {}),
@@ -90,8 +133,8 @@ export function removeDevServerLock(root: string): void {
     return;
   }
   try {
-    unlinkSync(serverLockPath(root));
+    removeInside(serverLockPath(root), root);
   } catch {
-    /* already gone */
+    /* a lock left behind names a process that is gone, which the next server sees */
   }
 }

package/src/server/routes.ts

@@ -8,7 +8,9 @@ import { escapeAttr, escapeHtml } from "../core/escape.ts";
 import { deckSlides, htmlShell, slidePlace, stampSlide } from "../core/html.ts";
 import { decodePosition } from "../core/live-protocol.ts";
 import { markedPositions, toggleMark } from "../core/marks.ts";
+import { deckProjectRoot } from "../core/path.ts";
 import type { Project, ProjectDeck } from "../core/resolve.ts";
+import { followInside } from "../core/safe-fs.ts";
 import { voiceCacheFile } from "../core/voice.ts";
 import { deckRoutePath, parseDeckRoute, splitDeckPath, type VoiceFile } from "../runtime/routes.ts";
 import { EVENT_EXPOSURE, type Exposure, mayRead, type Route } from "./auth.ts";
@@ -149,7 +151,8 @@ export function routeRequest(req: Request, ctx: RouteContext): Routed {
 const MISSING: Routed = { route: "missing", respond: notFound };
 
 function voiceResponse(deck: ProjectDeck | undefined, file: VoiceFile): Response {
-  const path = deck && voiceCacheFile(deck.dir, file);
+  // A link out of the project is no voice of the deck's, and is not served.
+  const path = deck && followInside(voiceCacheFile(deck.dir, file), deckProjectRoot(deck.dir));
   if (!path || !existsSync(path)) {
     return notFound();
   }
@@ -291,7 +294,9 @@ function jsonNotFound(deckName: string): Response {
 function safeDeckAsset(deckDir: string, relative: string): string | undefined {
   const root = join(deckDir, "assets");
   const found = fileInside(join(root, relative), root);
-  return found.kind === "file" ? found.path : undefined;
+  // assets/ may itself be a link, and then everything under what it points to is "inside" it:
+  // what is served must also be in the project, as every file dek reads is.
+  return found.kind === "file" ? followInside(found.path, deckProjectRoot(deckDir)) : undefined;
 }
 
 function jsonResponse(body: unknown, status = 200): Response {

package/src/server/serial.ts

@@ -1,3 +1,9 @@
+/**
+ * Runs `run` one at a time: a call while it runs queues one more run after it, however many
+ * calls come. Each caller's `run` reports its own failures, as diagnostics or a line on stderr;
+ * one that still throws is a bug, logged to the dev server's stderr as Bun.serve's error handler
+ * logs one, and the queued run still runs.
+ */
 export function createSerialTask(run: () => Promise<void>): () => void {
   let running = false;
   let queued = false;
@@ -13,8 +19,8 @@ export function createSerialTask(run: () => Promise<void>): () => void {
           queued = false;
           try {
             await run();
-          } catch {
-            /* keep draining the trailing run */
+          } catch (error) {
+            console.error(error);
           }
         } while (queued);
       } finally {

package/src/theme/default.css

@@ -20,6 +20,9 @@
   background: var(--bg);
   color: var(--fg);
   font-family: var(--font-body);
+  /* Japanese breaks between phrases, and no paragraph ends on a word left alone. */
+  word-break: auto-phrase;
+  text-wrap: pretty;
 }
 
 .slide .slide-title {
@@ -27,6 +30,7 @@
   font-family: var(--font-title);
   font-size: var(--size-title);
   line-height: 1.2;
+  text-wrap: balance;
 }
 
 /* @layout title

package/src/video/bake.ts

@@ -9,7 +9,7 @@ import {
   type ResolvedDeck,
   requireSection,
 } from "../core/resolve.ts";
-import { dropLinks, outputDir, outputPath, replaceFile } from "../core/safe-fs.ts";
+import { dropLinks, outputDir, outputPath, replaceFile, requireInside } from "../core/safe-fs.ts";
 import { logicalSize } from "../core/size.ts";
 import { sliceTimeline, slideTimeRange, type Timeline } from "../core/timeline.ts";
 import { videoDocument } from "../core/video-document.ts";
@@ -69,7 +69,11 @@ async function bakeProjectDeck(
       hint: "run `dekc voice`",
     });
   }
-  let timeline = { ...loaded, audio: resolveTimelineAudio(loaded, timelinePath) };
+  // ffmpeg opens the audio itself, so it is resolved here: a link out of the project is an error.
+  let timeline = {
+    ...loaded,
+    audio: requireInside(resolveTimelineAudio(loaded, timelinePath), project.root),
+  };
   const fps = options.fps ?? 30;
   const size = logicalSize(deck.deck.ratio);
   const html = videoDocument({ project, deck }, await playerScript());