@hajimism/dek 0.1.0

package/src/cli/usage.ts

@@ -0,0 +1,198 @@
+import pkg from "../../package.json";
+import { DekError } from "../core/error.ts";
+import { suggest } from "../core/suggest.ts";
+import {
+  allSpecs,
+  COMMANDS,
+  type CommandName,
+  commandFlags,
+  formOf,
+  type Group,
+  isTypedCommand,
+  subcommandsOf,
+  usageLines,
+} from "./commands.ts";
+import { CLI_SCHEMA_URL } from "./contract.ts";
+import { type CommandLine, FLAGS, type FlagName, flagValue } from "./flags.ts";
+
+const GROUP_TITLES: Record<Group, string> = {
+  Development: "Development",
+  Project: "Project",
+  Refs: "Refs (other people's decks to read as models; read-only)",
+  Slide: "Slide",
+  Output: "Output",
+  Help: "Help",
+};
+
+/** A call and what it does, on one line when the call is short, else the text under it. */
+function overviewLine([call, text]: readonly [string, string]): string {
+  const column = 20;
+  return call.length < column
+    ? `  ${call.padEnd(column)}${text}`
+    : `  ${call}\n${" ".repeat(column + 2)}${text}`;
+}
+
+/** The commands that read a ref where they read a deck, as their specs say. */
+function refReaders(): string[] {
+  return allSpecs()
+    .filter(([, spec]) => spec.refs === true)
+    .map(([name]) => name);
+}
+
+/** `dekc help`: every command by group, in the order COMMANDS lists them. */
+export function helpText(): string {
+  const groups = new Map<Group, string[]>();
+  for (const [, spec] of allSpecs()) {
+    const lines = groups.get(spec.group) ?? [];
+    lines.push(...spec.overview.map(overviewLine));
+    groups.set(spec.group, lines);
+  }
+  groups
+    .get("Refs")
+    ?.push(
+      overviewLine([`dekc ${refReaders().join("|")} <ref> ...`, "read a ref as you would a deck"]),
+    );
+  const body = [...groups].map(([group, lines]) => [GROUP_TITLES[group], ...lines].join("\n"));
+  return `dek — a build system for talks
+
+${body.join("\n\n")}
+
+Commands that print a result accept --json. dek and dekc rehearse stay running.
+Pass a deck name or --deck <name> to target a deck from the project root.
+Flags are checked per command: an unknown flag is an error, not ignored.
+dekc <command> --help  one command's usage and flags; dekc --version prints the version
+dekc help --agent      compact command reference for agents
+`;
+}
+
+/** `dekc help --agent`: one terse line or two per command. */
+export function agentHelpText(): string {
+  const lines = allSpecs().flatMap(([name, spec]) =>
+    name === "ref"
+      ? [
+          ...spec.agent,
+          `Refs are read-only decks to learn from: ${refReaders().join(", ")} take owner/repo/deck as the deck.`,
+        ]
+      : spec.agent,
+  );
+  return `dek — agent interface
+Result commands accept --json. dekc / rehearse do not (long-running). Diagnostics: dekc lint --format sarif.
+Each command's --json shape: ${CLI_SCHEMA_URL}
+Each diagnostic has severity (error | warning) and data; only errors exit 1.
+Scope: project root = all decks; deck dir = that deck; NAME or --deck NAME.
+
+${lines.join("\n")}
+
+Errors include hint with the next command to run.
+`;
+}
+
+const DOCS_URL = "https://hajimism.github.io/dek/reference/cli.html";
+
+/** `dekc help <command>`: its usage, what it does, and every flag it takes. */
+export function commandHelp(command: CommandName): string {
+  const flags: FlagName[] = [...commandFlags(command), "json", "help"];
+  const label = (flag: FlagName): string => {
+    if (flag === "help") {
+      return "--help, -h";
+    }
+    const value = flagValue(flag);
+    return value ? `--${flag} ${value}` : `--${flag}`;
+  };
+  const width = Math.max(...flags.map((flag) => label(flag).length)) + 3;
+  const [first, ...more] = usageLines(command);
+  return [
+    `usage: ${first}`,
+    ...more.map((line) => `       ${line}`),
+    "",
+    COMMANDS[command].summary,
+    "",
+    "flags",
+    ...flags.map((flag) => `  ${label(flag).padEnd(width)}${FLAGS[flag].text}`),
+    "",
+    DOCS_URL,
+  ].join("\n");
+}
+
+export type HelpRequest =
+  | { kind: "version" }
+  | { kind: "help"; topic?: CommandName; agent: boolean };
+
+/**
+ * Whether argv asks for help or the version instead of running a command.
+ * `dekc help <word>` names a command, so a word that is none fails as `dekc <word>` would.
+ */
+export function helpRequest(line: CommandLine): HelpRequest | undefined {
+  if (line.values.version === true) {
+    return { kind: "version" };
+  }
+  const asked = line.command === "help" || line.values.help === true;
+  if (!asked) {
+    return undefined;
+  }
+  const word = line.command === "help" ? line.positionals[1] : line.command;
+  const agent = line.values.agent === true;
+  if (line.command !== "help") {
+    return isTypedCommand(word) ? { kind: "help", topic: word, agent } : { kind: "help", agent };
+  }
+  const extra = line.positionals[2];
+  if (extra !== undefined) {
+    throw usageError("help", `unexpected argument "${extra}" for dekc help`);
+  }
+  if (word === undefined || word === "help") {
+    return { kind: "help", agent };
+  }
+  // `serve` is no word to type, yet it is the topic for the bare `dekc [deck]`.
+  if (isTypedCommand(word) || word === "serve") {
+    return { kind: "help", topic: word, agent };
+  }
+  throw unknownCommandError(word, []);
+}
+
+export function versionText(): string {
+  return `dekc ${pkg.version}`;
+}
+
+/** A word the user typed that is neither a command nor a deck, with the likeliest fix. */
+export function unknownCommandError(word: string, decks: string[]): DekError {
+  if (word === "serve") {
+    return new DekError("unknown command: serve", {
+      hint: "the dev server is the bare `dekc [deck]`: drop `serve`",
+    });
+  }
+  const commands = allSpecs()
+    .map(([name]) => name)
+    .filter(isTypedCommand);
+  const guess = suggest(word, [...commands, ...decks]);
+  return new DekError(`unknown command: ${word}`, {
+    hint: guess ? `did you mean \`dekc ${guess}\`?` : "run `dekc help` to see the commands",
+  });
+}
+
+/**
+ * A command line that does not fit the spec, with the usage the spec gives: a subcommand's
+ * own, or the command's, narrowed to the lines that contain `match` when given.
+ */
+export function usageError(
+  command: CommandName,
+  message: string,
+  options: { subcommand?: string; match?: string } = {},
+): DekError {
+  const lines = formOf(command, options.subcommand).usage.filter(
+    (line) => options.match === undefined || line.includes(options.match),
+  );
+  return new DekError(message, {
+    hint: `usage: ${lines.join(" | ")}; run \`dekc help ${command}\``,
+  });
+}
+
+/** A word where a command takes a subcommand, with the likeliest one. */
+export function unknownSubcommandError(command: CommandName, word: string): DekError {
+  const subs = Object.keys(subcommandsOf(COMMANDS[command]));
+  const guess = suggest(word, subs);
+  return new DekError(`unknown subcommand "${word}" for dekc ${command}`, {
+    hint: guess
+      ? `did you mean \`dekc ${command} ${guess}\`?`
+      : `dekc ${command} takes ${subs.join(", ")}; run \`dekc help ${command}\``,
+  });
+}

package/src/cli/video.ts

@@ -0,0 +1,17 @@
+import { bakeVideo } from "../video/bake.ts";
+import type { DeckTarget } from "./scope.ts";
+
+export type VideoCliResult = {
+  out: string;
+  vtt?: string;
+  chapters?: string;
+  credits?: string;
+};
+
+/** `fps` is checked on the command line: a positive number, 30 when left out. */
+export async function videoCommand(
+  target: DeckTarget,
+  options: { slug?: string; fps?: number; rootDist?: boolean } = {},
+): Promise<VideoCliResult> {
+  return bakeVideo(target, options);
+}

package/src/cli/voice.ts

@@ -0,0 +1,113 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DekError } from "../core/error.ts";
+import { deckProjectRoot } from "../core/path.ts";
+import { isCachedFile, writeInside } from "../core/safe-fs.ts";
+import { loadVoiceDict, loadVoiceSettings, voiceCacheFile, writeVoiceDict } from "../core/voice.ts";
+import {
+  engineBaseUrl,
+  fetchAudioQuery,
+  fetchSpeakers,
+  fetchSynthesis,
+  resolveStyleId,
+  withEngine,
+} from "../voice/engine.ts";
+import { synthDeck } from "../voice/synth.ts";
+import type { DeckTarget } from "./scope.ts";
+
+export type VoiceCliResult =
+  | {
+      action: "synth";
+      synthesized: number;
+      cached: number;
+      timelinePath: string;
+      audioPath: string;
+    }
+  | { action: "speakers"; speakers: Array<{ name: string; styles: string[] }> }
+  | { action: "say"; text: string; path: string }
+  | { action: "dict"; path: string; key: string; kana: string }
+  | { action: "pin"; timelinePath: string; audioPath: string };
+
+/** `dekc voice`: synthesize the sentences that changed. */
+export async function synthVoice(target: DeckTarget): Promise<VoiceCliResult> {
+  return { action: "synth", ...(await synthDeck(target)) };
+}
+
+export async function listSpeakers({ deck }: DeckTarget): Promise<VoiceCliResult> {
+  const settings = loadVoiceSettings(deck.dir);
+  const baseUrl = engineBaseUrl(settings.engine);
+  const speakers = await withEngine(settings.engine, baseUrl, () => fetchSpeakers(baseUrl));
+  return {
+    action: "speakers",
+    speakers: speakers.map((speaker) => ({
+      name: speaker.name,
+      styles: speaker.styles.map((style) => style.name),
+    })),
+  };
+}
+
+/** Speak one sentence in the deck's voice, and keep the audio at .cache/voice/say.wav. */
+export async function sayVoice({ deck }: DeckTarget, text: string): Promise<VoiceCliResult> {
+  const settings = loadVoiceSettings(deck.dir);
+  const baseUrl = engineBaseUrl(settings.engine);
+  const speakers = await withEngine(settings.engine, baseUrl, () => fetchSpeakers(baseUrl));
+  const styleId = resolveStyleId(speakers, settings.speaker);
+  const query = await fetchAudioQuery(baseUrl, text, styleId);
+  query.speedScale = settings.speed;
+  const wav = await fetchSynthesis(baseUrl, query, styleId);
+  const path = voiceCacheFile(deck.dir, "say.wav");
+  writeInside(path, wav, deckProjectRoot(deck.dir));
+  await playWav(path);
+  return { action: "say", text, path };
+}
+
+/** Add a reading to voice/dict.toml; `accent` is checked on the command line. */
+export function addReading(
+  { deck }: DeckTarget,
+  entry: { word: string; kana: string; accent?: number },
+): VoiceCliResult {
+  const dict = loadVoiceDict(deck.dir);
+  dict[entry.word] = {
+    kana: entry.kana,
+    ...(entry.accent !== undefined ? { accent: entry.accent } : {}),
+  };
+  const path = writeVoiceDict(deck.dir, dict);
+  return { action: "dict", path, key: entry.word, kana: entry.kana };
+}
+
+/** Copy the synthesized audio and timeline into voice/pin/, which is committed. */
+export function pinVoice({ deck }: DeckTarget): VoiceCliResult {
+  const timelinePath = voiceCacheFile(deck.dir, "timeline.json");
+  const audioPath = voiceCacheFile(deck.dir, "audio.wav");
+  // What is pinned is committed; only what `dekc voice` wrote, never a link planted in the cache.
+  if (!isCachedFile(timelinePath) || !isCachedFile(audioPath)) {
+    throw new DekError("Timeline not found", {
+      path: timelinePath,
+      hint: "run `dekc voice`",
+    });
+  }
+  const root = deckProjectRoot(deck.dir);
+  const pinDir = join(deck.dir, "voice", "pin");
+  const pinTimeline = join(pinDir, "timeline.json");
+  const pinAudio = join(pinDir, "master.wav");
+  writeInside(pinTimeline, readFileSync(timelinePath), root);
+  writeInside(pinAudio, readFileSync(audioPath), root);
+  return { action: "pin", timelinePath: pinTimeline, audioPath: pinAudio };
+}
+
+async function playWav(path: string): Promise<void> {
+  if (process.env.DEK_VOICE_PLAY === "0") {
+    return;
+  }
+  const bin =
+    process.platform === "darwin" ? "afplay" : process.platform === "win32" ? "" : "aplay";
+  if (!bin) {
+    return;
+  }
+  await new Promise<void>((resolve) => {
+    const child = spawn(bin, [path], { stdio: "ignore" });
+    child.on("exit", () => resolve());
+    child.on("error", () => resolve());
+  });
+}

package/src/cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { main } from "./cli/main.ts";
+
+await main(Bun.argv.slice(2), process.cwd());

package/src/core/assets.ts

@@ -0,0 +1,239 @@
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { extname, relative, resolve, sep } from "node:path";
+import { parseCss } from "./css.ts";
+import {
+  type CssEditor,
+  minifyCss,
+  replaceUrls,
+  rewriteCss,
+  scopeToSlide,
+  shareTokensWithTransitions,
+} from "./css-transform.ts";
+import { deckPaths } from "./deck-paths.ts";
+import { isInside } from "./path.ts";
+import { listSlideFiles, readDeckFile } from "./resolve.ts";
+import { attributeUrls } from "./url-attributes.ts";
+
+/** Where one reference from a slide or a stylesheet points. */
+export type AssetRef =
+  /** Nothing to resolve: empty, a fragment, a data: URI, or another scheme. */
+  | { kind: "skip" }
+  | { kind: "remote" }
+  /** A local path that leaves the deck directory. */
+  | { kind: "escape" }
+  /** A local path inside the deck that names no file. */
+  | { kind: "missing" }
+  | { kind: "file"; path: string; deckPath: string };
+
+/** A network address: `http:` or `https:` with or without its slashes, or protocol-relative. */
+const REMOTE_RE = /^(?:https?:|\/\/)/i;
+/** A file on the machine that opens the deck, which no copy of the deck carries along. */
+const FILE_RE = /^file:/i;
+const SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+
+/**
+ * Resolves a reference the one way lint, show, and the build agree on: the
+ * deck root first, which is where the dev server and the build look for
+ * `assets/`, then next to the file that names it, so `../assets/x` from
+ * slides/ still resolves. A query string or fragment is not part of the path.
+ */
+export function classifyAssetRef(
+  raw: string,
+  options: { deckDir: string; from: string },
+): AssetRef {
+  const value = raw.trim().split(/[?#]/)[0] ?? "";
+  if (!value) {
+    return { kind: "skip" };
+  }
+  if (REMOTE_RE.test(value)) {
+    return { kind: "remote" };
+  }
+  if (FILE_RE.test(value)) {
+    return { kind: "escape" };
+  }
+  if (SCHEME_RE.test(value)) {
+    return { kind: "skip" };
+  }
+  const found = [resolve(options.deckDir, value), resolve(options.from, value)]
+    .filter((path) => isInside(path, options.deckDir))
+    .map((path) => fileInside(path, options.deckDir));
+  const file = found.find((ref) => ref.kind === "file");
+  if (file) {
+    return { ...file, deckPath: relative(options.deckDir, file.path).split(sep).join("/") };
+  }
+  // A link out of the deck outranks a path that names nothing: the author wrote a file that is there.
+  return found.length > 0 && found.every((ref) => ref.kind === "missing")
+    ? { kind: "missing" }
+    : { kind: "escape" };
+}
+
+/**
+ * Where `path` stands against `root`, judged by where it really lives: a symlink under `root`
+ * that leads out of it escapes, like `../` does, so neither the build nor the dev server reads
+ * a file the deck does not hold. The path itself comes back as written.
+ */
+export function fileInside(
+  path: string,
+  root: string,
+): { kind: "escape" } | { kind: "missing" } | { kind: "file"; path: string } {
+  if (!isInside(path, root)) {
+    return { kind: "escape" };
+  }
+  let real: string;
+  try {
+    real = realpathSync(path);
+  } catch {
+    return { kind: "missing" };
+  }
+  if (!isInside(real, realpathSync(root))) {
+    return { kind: "escape" };
+  }
+  return statSync(real).isFile() ? { kind: "file", path } : { kind: "missing" };
+}
+
+/** True when a reference is written as `assets/...` from the deck root, or is not a local path at all. */
+export function isCanonicalAssetPath(raw: string): boolean {
+  const value = raw.trim();
+  if (!value || value.startsWith("#") || SCHEME_RE.test(value) || REMOTE_RE.test(value)) {
+    return true;
+  }
+  return value.startsWith("assets/");
+}
+
+/**
+ * Slide markup with each local resource replaced by a data: URI, so the build stands alone; `from`
+ * is the directory the markup lives in.
+ */
+export function inlineAssets(
+  html: string,
+  deckDir: string,
+  from = deckPaths(deckDir).slides,
+): string {
+  const output = new HTMLRewriter().on("*", assetInliner(deckDir, from)).transform(html);
+  if (typeof output !== "string") {
+    throw new Error("HTMLRewriter.transform expected a string");
+  }
+  return output;
+}
+
+/**
+ * The rewriter handler `inlineAssets` runs, for a pass that rewrites more than URLs. The URLs are
+ * the ones lint checks, read by the same parser: every candidate of a `srcset` keeps its
+ * descriptors, links and text stay as written.
+ */
+export function assetInliner(
+  deckDir: string,
+  from = deckPaths(deckDir).slides,
+): HTMLRewriterTypes.HTMLRewriterElementContentHandlers {
+  return {
+    element(el) {
+      const tag = el.tagName.toLowerCase();
+      for (const [name, value] of [...el.attributes]) {
+        const named = attributeUrls(tag, name.toLowerCase(), value);
+        if (named?.use !== "resource") {
+          continue;
+        }
+        const inlined = named.urls.reduceRight((rewritten, { url, offset }) => {
+          const uri = inlinedUri(url, deckDir, from);
+          return uri === undefined
+            ? rewritten
+            : rewritten.slice(0, offset) + uri + rewritten.slice(offset + url.length);
+        }, value);
+        if (inlined !== value) {
+          el.setAttribute(name, inlined);
+        }
+      }
+    },
+  };
+}
+
+/** Each local `url()` replaced by a data: URI; `from` is the directory the stylesheet lives in. */
+export function inlineCssUrls(deckDir: string, from = deckDir): CssEditor {
+  return replaceUrls((url) => inlinedUri(url, deckDir, from));
+}
+
+/** The data: URI a local reference inlines to, keeping its fragment; none when it names no deck file. */
+function inlinedUri(url: string, deckDir: string, from: string): string | undefined {
+  const ref = classifyAssetRef(url, { deckDir, from });
+  if (ref.kind !== "file") {
+    return undefined;
+  }
+  const hash = url.indexOf("#");
+  return `data:${mimeOf(ref.path)};base64,${readFileSync(ref.path).toString("base64")}${hash === -1 ? "" : url.slice(hash)}`;
+}
+
+/** The deck's stylesheets apart: theme.css, and each slide's own CSS scoped to that slide. */
+export type DeckStyles = { theme: string; slides: Map<string, string> };
+
+/**
+ * The deck's stylesheets, each read once and rewritten in one pass; a slide with no CSS of its
+ * own has no entry. A standalone page also gets its files as data: URIs.
+ */
+export function readDeckStyles(deckDir: string, standalone: boolean): DeckStyles {
+  const paths = deckPaths(deckDir);
+  const theme = rewriteCss(
+    parseCss(readDeckFile(deckDir, paths.theme) ?? ""),
+    shareTokensWithTransitions,
+    ...(standalone ? [inlineCssUrls(deckDir)] : []),
+  );
+  const slides = new Map<string, string>();
+  for (const slide of listSlideFiles(deckDir, ".css")) {
+    const css = rewriteCss(
+      parseCss(readDeckFile(deckDir, slide.path) ?? ""),
+      scopeToSlide(slide.slug),
+      ...(standalone ? [inlineCssUrls(deckDir, paths.slides)] : []),
+    );
+    if (css) {
+      slides.set(slide.slug, css);
+    }
+  }
+  return { theme, slides };
+}
+
+/**
+ * The deck's stylesheet: theme.css, then each slide's own CSS scoped to that slide. A standalone
+ * page also gets its files as data: URIs, minified.
+ */
+export function readTheme(deckDir: string, standalone: boolean): string {
+  const { theme, slides } = readDeckStyles(deckDir, standalone);
+  const css = [theme, ...slides.values()].filter(Boolean).join("\n");
+  return standalone ? minifyCss(css) : css;
+}
+
+/** Media types by extension, for what a slide or a stylesheet commonly embeds. */
+const MIME_TYPES: Readonly<Record<string, string>> = {
+  ".apng": "image/apng",
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".m4v": "video/mp4",
+  ".mov": "video/quicktime",
+  ".mp4": "video/mp4",
+  ".ogv": "video/ogg",
+  ".webm": "video/webm",
+  ".aac": "audio/aac",
+  ".flac": "audio/flac",
+  ".m4a": "audio/mp4",
+  ".mp3": "audio/mpeg",
+  ".oga": "audio/ogg",
+  ".ogg": "audio/ogg",
+  ".opus": "audio/ogg",
+  ".wav": "audio/wav",
+  ".eot": "application/vnd.ms-fontobject",
+  ".otf": "font/otf",
+  ".ttf": "font/ttf",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".vtt": "text/vtt",
+  ".css": "text/css",
+};
+
+function mimeOf(filePath: string): string {
+  return MIME_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}

package/src/core/build.ts

@@ -0,0 +1,77 @@
+import { copyFileSync } from "node:fs";
+import { basename } from "node:path";
+import { loadConfig } from "./config.ts";
+import { renderDeckDocument } from "./document.ts";
+import { type DistOptions, distFile } from "./path.ts";
+import type { PlaywrightRunner } from "./playwright.ts";
+import { asResolvedDeck, type ResolvedDeck } from "./resolve.ts";
+import { outputPath, removeInside, writeInside } from "./safe-fs.ts";
+import { coverShot } from "./shot/still.ts";
+import { logicalSize } from "./size.ts";
+
+export type BuildResult = { outPath: string } & (
+  | {
+      /** dist/<deck>.png, the link preview image. */
+      image: string;
+    }
+  | {
+      /** Why there is no preview image: no public URL to point og:image at, or no Playwright. */
+      imageSkipped: "no-url" | "no-playwright";
+    }
+);
+
+export type BuildOptions = DistOptions & {
+  playerScript: string;
+  /** Where dist/ is served from, ending in a slash; overrides `url` in dek.toml. */
+  url?: string;
+  /** For anyone with the link: the presenter view carries only what is said aloud. */
+  public?: boolean;
+  runner?: PlaywrightRunner;
+};
+
+export async function buildDeck(dir: string, options: BuildOptions): Promise<BuildResult>;
+export async function buildDeck(source: ResolvedDeck, options: BuildOptions): Promise<BuildResult>;
+export async function buildDeck(
+  input: string | ResolvedDeck,
+  options: BuildOptions,
+): Promise<BuildResult> {
+  const { project, deck } = asResolvedDeck(input);
+  const config = loadConfig(project.configPath);
+  const outPath = distFile(project, deck, "html", options);
+  const imagePath = distFile(project, deck, "png", options);
+  const baseUrl = options.url ?? config.url;
+  const shot = baseUrl ? await coverShot(deck, options.runner) : undefined;
+
+  if (shot) {
+    copyFileSync(shot, outputPath(imagePath, project.root));
+  } else {
+    // An image from an earlier build would outlive the tag that pointed at it.
+    removeInside(imagePath, project.root);
+  }
+  const html = renderDeckDocument(deck, {
+    config,
+    playerScript: options.playerScript,
+    target: {
+      kind: "build",
+      ...(options.public ? { public: true } : {}),
+      ...(baseUrl
+        ? {
+            publicUrl: new URL(encodeURIComponent(basename(outPath)), baseUrl).href,
+            ...(shot
+              ? {
+                  previewImage: {
+                    url: new URL(encodeURIComponent(basename(imagePath)), baseUrl).href,
+                    ...logicalSize(deck.deck.ratio),
+                  },
+                }
+              : {}),
+          }
+        : {}),
+    },
+  });
+  writeInside(outPath, html, project.root);
+  if (shot) {
+    return { outPath, image: imagePath };
+  }
+  return { outPath, imageSkipped: baseUrl ? "no-playwright" : "no-url" };
+}

package/src/core/bundled-theme.ts

@@ -0,0 +1,15 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseCss, publishedTokens } from "./css.ts";
+
+const bundledThemePath = join(import.meta.dir, "..", "theme", "default.css");
+
+/** The theme dek ships, which `dekc init` writes and every required token is set in. */
+export function bundledTheme(): string {
+  return readFileSync(bundledThemePath, "utf8");
+}
+
+/** The value dek's own theme gives a token, for a hint that can be written as is. */
+export function bundledTokenValue(name: string): string | undefined {
+  return publishedTokens(parseCss(bundledTheme())).find((token) => token.name === name)?.value;
+}