@hajimism/dek 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hajime Nakagawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,75 @@
+# dek
+
+**発表のビルドシステム。** 喋ることを書けば、あとは dek が組み立て、測り、届ける。
+
+[ドキュメント](https://hajimism.github.io/dek/ja/) · [English README](./README.md)
+
+dek は、ビルドシステムがコードを扱うように発表を扱う CLI です。ソースは Markdown で書くトークの台本で、`##` の見出しひとつが 1 枚の HTML スライドになります。同じソースから、尺を見積もり、どのスライドも lint して描画を測り、1 ファイルの HTML、PDF、読み上げ付きの動画をビルドします。プロジェクトが複数のデッキを持つので、テーマも規約も前回のトークから次のトークへ引き継がれます。AI エージェントと一緒に作ることを、最初から前提に設計しています。
+
+## なぜ dek か
+
+**スライドは喋るためにあります。** 主流のツールはどれも空の箱から始まり、埋めれば埋めるほど資料は立派になり、本番で喋り切るのは難しくなる。dek は反対側から始めます。何を、どの順で、どれだけの尺で喋るか。そのうえで、画面に何が出ているべきか。台本が親で、スライドはそこから派生します。
+
+**トークは一度きりではありません。** dek のプロジェクトは複数のデッキを入れる場所です。規約はプロジェクトのもの、見た目は前回のデッキの続きから、台本とスライドはデッキごと。
+
+**エージェントには小さなファイルが要ります。** 1 スライドは約 40 行の HTML ファイルひとつ。必要なら CSS とスクリプトを横に置けます。編集対象は小さく、差分は読め、壊れてもその 1 枚で済みます。
+
+**エージェントは自分の描画結果を見られません。** dek はスライドを描画し、はみ出し、コントラスト、欠けた画像を機械可読な診断として返します。エージェントが自分の出力を確かめ、自分で直せます。
+
+三原則と Slidev との比較は [dek の設計思想](https://hajimism.github.io/dek/ja/guide/why.html) にあります。
+
+## クイックスタート
+
+[Bun](https://bun.sh) 1.4 以上。
+
+```bash
+bunx @hajimism/dek init my-talks --deck 2026-04-vite
+cd my-talks
+bun add -d @hajimism/dek
+cd decks/2026-04-vite
+```
+
+`init` は終わりに同じ手順を表示します。プロジェクトを作るのは最初の一度だけです。dek をプロジェクトの開発依存に入れたあとは `bunx dekc` で動きます。残るのは 3 手で、ライブ発表ならこれがすべてです。
+
+> [!WARNING]
+> パッケージは `@hajimism/dek` で、入るコマンドは `dek` ではなく `dekc` です。npm の `dek` は無関係の別パッケージで、`bunx dek` はそれをダウンロードして実行します。プロジェクトの中では `bunx dekc` がそこに入れた dek を動かします。プロジェクトの外では `bunx @hajimism/dek` を使ってください。
+
+```bash
+$EDITOR script.md   # 1. 喋ることを書く。時間をかけるのはここ
+bunx dekc           # 2. 開発サーバ。骨格スライドが生え、保存のたびに描画と lint
+bunx dekc build     # 3. dist/2026-04-vite.html — トーク全体がこの 1 ファイル
+```
+
+台本を書いて `dekc` を叩けば、HTML を一行も書かずに同梱テーマで発表できます。
+
+続きは [はじめる](https://hajimism.github.io/dek/ja/guide/getting-started.html)へ。通しで 1 本作るなら [チュートリアル](https://hajimism.github.io/dek/ja/guide/tutorial.html)。コマンドの一覧は [CLI リファレンス](https://hajimism.github.io/dek/ja/reference/cli.html)にあります。
+
+## サンプル
+
+`sample/` は Playwright、rumdl、声まで入れたフル構成のプロジェクトで、3 つのデッキが入っています。どれも dek 自身が題材で、配布資料としても読める約 12 分の解説 `why-dek`、ターミナルで発表を作ってみせる 3 分のライトニングトーク `lightning`、スライドを AI エージェントに任せる 6 分のトーク `with-agents` です。手順は [sample/README.ja.md](sample/README.ja.md)。
+
+```bash
+cd sample
+bun install
+bun run setup          # Playwright 用の Chromium
+bun run dev            # または bun run lint:visual / bun run build
+```
+
+## 開発
+
+```bash
+bun install
+bunx playwright install chromium   # 最初に一度。実ブラウザを動かすテストに使う
+bun test --watch
+bun run typecheck
+bun run check             # Biome の format + lint
+bun run docs:dev          # VitePress
+```
+
+CI では `biome ci`、`typecheck`、全テスト（ブラウザを使うものは Chromium で）、`docs:build` を走らせます。
+
+ドキュメントサイトは GitHub Actions 経由で GitHub Pages に出します。初回だけ、リポジトリの設定で **Pages → Source** を **GitHub Actions** にしてください。
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,75 @@
+# dek
+
+**A build system for talks.** Write what you will say; dek builds, measures, and ships the rest.
+
+[Documentation](https://hajimism.github.io/dek/) · [日本語 README](./README.ja.md)
+
+dek treats a talk the way a build system treats code. The source is your talk script, in Markdown; every `##` heading becomes one HTML slide, and from the same source dek estimates the timing, lints and measures every slide, and builds a single HTML file, a PDF, and a narrated video. A project holds many decks, so the theme and conventions carry forward from one talk to the next. It is designed from the start to be worked on together with AI agents.
+
+## Why
+
+**Slides exist so that you can talk.** Every mainstream tool starts with an empty box and asks you to fill it, and the deck grows more polished as the talk grows harder to deliver. dek starts from the other end: what you will say, in what order, for how long, and only then what should be on screen. The script is the parent. Slides are derived from it.
+
+**A talk is not a one-off.** A dek project holds many decks. Conventions belong to the project, the look carries forward from your last deck, and every deck owns its script and slides.
+
+**Agents need small files.** One slide is one HTML file of about forty lines, with an optional stylesheet and script beside it. The edit target is small, the diff is readable, and a broken edit breaks one slide.
+
+**Agents cannot see what they render.** dek renders each slide and reports overflow, contrast, and missing images as machine-readable diagnostics, so an agent can check and fix its own output.
+
+The three principles and the comparison with Slidev are in [Why dek](https://hajimism.github.io/dek/guide/why.html).
+
+## Quick start
+
+[Bun](https://bun.sh) 1.4 or later.
+
+```bash
+bunx @hajimism/dek init my-talks --deck 2026-04-vite
+cd my-talks
+bun add -d @hajimism/dek
+cd decks/2026-04-vite
+```
+
+`init` prints these same steps as it finishes. You create the project once. Once dek is a dev dependency of the project, `bunx dekc` runs it. Three commands remain, and for a live talk that is all there is.
+
+> [!WARNING]
+> The package is `@hajimism/dek`; the command it installs is `dekc`, not `dek`. `dek` on npm is an unrelated package, and `bunx dek` downloads and runs it. Inside a project, `bunx dekc` runs the dek installed there; outside one, use `bunx @hajimism/dek`.
+
+```bash
+$EDITOR script.md   # 1. write what you will say — spend your time here
+bunx dekc           # 2. dev server: skeleton slides, live reload, lint on save
+bunx dekc build     # 3. dist/2026-04-vite.html — the whole talk in one file
+```
+
+Write the script, run `dekc`, and you can present with the bundled theme without writing a line of HTML.
+
+Continue with [Getting Started](https://hajimism.github.io/dek/guide/getting-started.html), or build a real deck end to end in the [Tutorial](https://hajimism.github.io/dek/guide/tutorial.html). Every command is listed in the [CLI reference](https://hajimism.github.io/dek/reference/cli.html).
+
+## Sample
+
+`sample/` is a full project with Playwright, rumdl, and voice, holding three decks about dek itself: `why-dek`, a twelve-minute explainer built to read as a handout; `lightning`, a three-minute lightning talk that builds a talk in a terminal; and `with-agents`, a six-minute talk about handing slides to an AI agent. See [sample/README.md](sample/README.md).
+
+```bash
+cd sample
+bun install
+bun run setup          # Chromium for Playwright
+bun run dev            # or bun run lint:visual / bun run build
+```
+
+## Development
+
+```bash
+bun install
+bunx playwright install chromium   # once, for the tests that drive a real browser
+bun test --watch
+bun run typecheck
+bun run check             # Biome format + lint
+bun run docs:dev          # VitePress
+```
+
+CI runs `biome ci`, `typecheck`, the full test suite (the browser tests in Chromium), and `docs:build`.
+
+The documentation site deploys to GitHub Pages through Actions. Once, in the repository settings, set **Pages → Source** to **GitHub Actions**.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@hajimism/dek",
+  "version": "0.1.0",
+  "description": "A build system for talks.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "dekc": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "README.ja.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hajimism/dek.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hajimism/dek/issues"
+  },
+  "homepage": "https://hajimism.github.io/dek/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "keywords": [
+    "slides",
+    "presentation",
+    "talk",
+    "build",
+    "cli",
+    "html"
+  ],
+  "scripts": {
+    "test": "bun test --parallel=4",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit",
+    "knip": "knip",
+    "schema": "bun scripts/cli-schema.ts",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "check": "biome check --write .",
+    "docs:dev": "vitepress dev docs",
+    "docs:samples": "cd sample && bun ../src/cli.ts build --root-dist && mkdir -p ../docs/public/samples && cp dist/*.html dist/*.png ../docs/public/samples/",
+    "docs:build": "bun run docs:samples && vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.14",
+    "@happy-dom/global-registrator": "20.14.5",
+    "@types/bun": "^1.4.2",
+    "happy-dom": "20.14.5",
+    "knip": "6.38.0",
+    "playwright": "^1.63.0",
+    "typescript": "^7.0.2",
+    "vitepress": "^1.6.4"
+  }
+}

package/src/cli/address.ts

@@ -0,0 +1,53 @@
+import { existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isInside } from "../core/path.ts";
+import { COMMANDS } from "./commands.ts";
+
+/** A deck a hint is about: the name a command takes, and the directory that makes it implicit. */
+export type HintDeck = { name: string; dir: string };
+
+/**
+ * A hint's commands as they run from `cwd`. Hints are written as if run inside the deck they are
+ * about, where a command finds its deck by itself. Run anywhere else, a command that takes a deck
+ * needs its name: as the first word outside every deck, and as `--deck` inside another deck,
+ * where a first word names something in that deck instead. A command that already names a deck,
+ * or takes none, is left as written.
+ */
+export function addressHint(hint: string, deck: HintDeck | undefined, cwd: string): string {
+  if (deck === undefined || isInside(cwd, deck.dir)) {
+    return hint;
+  }
+  const naming = deckAround(cwd) === undefined ? deck.name : `--deck ${deck.name}`;
+  return hint.replace(COMMAND_RE, (whole, command: string, rest: string) => {
+    if (!DECK_COMMANDS.has(command) || namesDeck(rest, deck.name)) {
+      return whole;
+    }
+    return `\`dekc ${command} ${naming}${rest}\``;
+  });
+}
+
+/** A backquoted command: `dekc`, a command word, and what follows it up to the closing quote. */
+const COMMAND_RE = /`dekc ([a-z]+)((?: [^`]*)?)`/g;
+
+const DECK_COMMANDS = new Set(
+  Object.entries(COMMANDS).flatMap(([name, spec]) => ("scope" in spec && spec.scope ? [name] : [])),
+);
+
+function namesDeck(rest: string, name: string): boolean {
+  const [first] = rest.trim().split(/\s+/);
+  return first === name || first?.includes("/") === true || /(?:^| )--deck(?: |$)/.test(rest);
+}
+
+/**
+ * The deck `path` lies in: the directory under a project's `decks/`, found from the path alone.
+ * A source path dek reports is absolute, so no project needs to be resolved to address it.
+ */
+export function deckAround(path: string): HintDeck | undefined {
+  for (let dir = path; dirname(dir) !== dir; dir = dirname(dir)) {
+    const parent = dirname(dir);
+    if (basename(parent) === "decks" && existsSync(join(dirname(parent), "dek.toml"))) {
+      return { name: basename(dir), dir };
+    }
+  }
+  return undefined;
+}

package/src/cli/build.ts

@@ -0,0 +1,85 @@
+import { buildDeck } from "../core/build.ts";
+import type { Diagnostic } from "../core/diagnostic.ts";
+import { DekError } from "../core/error.ts";
+import { lintDeck, lintProject } from "../core/lint.ts";
+import { parsePublicUrl } from "../core/ogp.ts";
+import { PLAYWRIGHT_INSTALL, type PlaywrightRunner } from "../core/playwright.ts";
+import { playerScript } from "../runtime/player.ts";
+import { type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
+import type { DecksTarget } from "./scope.ts";
+
+/**
+ * A build never fails on lint: at the venue, a deck that shows is better than
+ * none. What dek's own rules say comes back with it, so nobody ships it unaware;
+ * rumdl's Markdown style is `dekc lint`'s alone, since it never stops a deck showing.
+ */
+export type BuildCliResult = {
+  /** One file per deck built, a single deck included, so the shape never depends on the scope. */
+  outs: string[];
+  /** dist/<deck>.png for each deck that got a link preview image. */
+  images: string[];
+  diagnostics: Diagnostic[];
+  /** Why some deck has no preview image, said once per reason. */
+  skipped?: SkippedCheck[];
+};
+
+const PREVIEW_SKIPPED = {
+  "no-url": {
+    check: "preview",
+    reason: "url is not set",
+    hint: "set url in dek.toml, or pass --url, to the URL dist/ is served from",
+  },
+  "no-playwright": {
+    check: "preview",
+    reason: "Playwright is not installed",
+    hint: PLAYWRIGHT_INSTALL,
+  },
+} as const satisfies Record<string, SkippedCheck>;
+
+export async function buildCommand(
+  { project, decks }: DecksTarget,
+  options: { rootDist?: boolean; url?: string; public?: boolean; runner?: PlaywrightRunner } = {},
+): Promise<BuildCliResult> {
+  const url = options.url === undefined ? undefined : parsePublicUrl(options.url);
+  if (options.url !== undefined && url === undefined) {
+    throw new DekError(`invalid --url "${options.url}"`, {
+      hint: "pass the absolute http(s) URL dist/ is served from, like --url https://example.com/talks/",
+    });
+  }
+  const script = await playerScript();
+  const results = await Promise.all(
+    decks.map((entry) =>
+      buildDeck(
+        { project, deck: entry },
+        {
+          playerScript: script,
+          rootDist: options.rootDist,
+          ...(url ? { url } : {}),
+          ...(options.public ? { public: true } : {}),
+          ...(options.runner ? { runner: options.runner } : {}),
+        },
+      ),
+    ),
+  );
+  const diagnostics = [
+    ...lintProject(project),
+    ...decks.flatMap((entry) => lintDeck({ project, deck: entry })),
+  ];
+  const skipped = new Set(
+    results.flatMap((result) =>
+      "imageSkipped" in result ? [PREVIEW_SKIPPED[result.imageSkipped]] : [],
+    ),
+  );
+  return {
+    outs: results.map((result) => result.outPath),
+    images: results.flatMap((result) => ("image" in result ? [result.image] : [])),
+    diagnostics,
+    ...skippedChecks([
+      ...skipped,
+      visualSkipped("dekc lint --visual", {
+        reason: "overflow and contrast are measured only by `dekc lint --visual`",
+        ...(options.runner ? { runner: options.runner } : {}),
+      }),
+    ]),
+  };
+}

package/src/cli/check.ts

@@ -0,0 +1,97 @@
+import type { Diagnostic } from "../core/diagnostic.ts";
+import { DekError } from "../core/error.ts";
+import type { Fill } from "../core/fill.ts";
+import { lintDeck } from "../core/lint.ts";
+import { type PlaywrightRunner, playwrightMissingError } from "../core/playwright.ts";
+import { runVisualDeck } from "../core/visual.ts";
+import { hasVoice, loadCachedTimeline, VOICE_SETUP_HINT } from "../core/voice.ts";
+import { type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
+import { type DeckTarget, requireSection } from "./scope.ts";
+
+type VoiceCheckBeat = {
+  beatIndex: number;
+  durationMs: number;
+  empty: boolean;
+  sentences: Array<{ text: string; kana: string; start: number; end: number }>;
+};
+
+export type CheckCliResult = {
+  slug: string;
+  diagnostics: Diagnostic[];
+  /** Checks that did not run, each with why and how to run it, so an empty list is not a pass. */
+  skipped?: SkippedCheck[];
+  shot?: string;
+  /** How much of the frame the slide fills at `step`, its last beat; absent when not measured. */
+  fill?: Fill & { step: string };
+  voice?: { beats: VoiceCheckBeat[] };
+};
+
+export async function checkCommand(
+  { project, deck }: DeckTarget,
+  options: { slug: string; shot?: boolean; voice?: boolean; runner?: PlaywrightRunner },
+): Promise<CheckCliResult> {
+  const { slug } = options;
+  requireSection(deck, slug);
+
+  const diagnostics = lintDeck({ project, deck }, { slug });
+  const visual = await runVisualDeck(
+    { project, deck },
+    {
+      slug,
+      screenshot: options.shot === true,
+      ...(options.runner ? { runner: options.runner } : {}),
+    },
+  );
+  if (visual) {
+    diagnostics.push(...visual.diagnostics);
+  } else if (options.shot) {
+    throw playwrightMissingError();
+  }
+
+  const shot = visual?.screenshotPath;
+  const { slug: _slide, ...fill } = visual?.fills.find((found) => found.slug === slug) ?? {};
+
+  const skipped: SkippedCheck[] = visual
+    ? []
+    : [visualSkipped(`dekc check ${slug}`, { reason: "Playwright is not installed" })];
+
+  // A live-only deck is done without voice, so asking for it skips the check rather than failing,
+  // the way a missing Playwright skips visual.
+  let voice: CheckCliResult["voice"];
+  if (options.voice && !hasVoice(deck.dir)) {
+    skipped.push({
+      check: "voice",
+      reason: "the deck has no voice/voice.toml",
+      hint: VOICE_SETUP_HINT,
+    });
+  } else if (options.voice) {
+    const { synthDeck } = await import("../voice/synth.ts");
+    await synthDeck({ project, deck });
+    const timeline = loadCachedTimeline(deck.dir);
+    if (!timeline) {
+      throw new DekError("Timeline not found", {
+        hint: "run `dekc voice`",
+      });
+    }
+    const slideIndex = deck.deck.sections.findIndex((entry) => entry.slug === slug);
+    voice = {
+      beats: timeline.beats
+        .filter((beat) => beat.position.slideIndex === slideIndex)
+        .map((beat) => ({
+          beatIndex: beat.position.beatIndex,
+          durationMs: beat.end - beat.start,
+          empty: beat.sentences.length === 0,
+          sentences: beat.sentences,
+        })),
+    };
+  }
+
+  return {
+    slug,
+    diagnostics,
+    ...skippedChecks(skipped),
+    ...(shot ? { shot } : {}),
+    ...("step" in fill ? { fill } : {}),
+    ...(voice ? { voice } : {}),
+  };
+}