create-slide-deck 0.1.0

package/dist/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import readline from "node:readline";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function ask(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+function replaceInFile(filePath, replacements) {
+    if (!fs.existsSync(filePath))
+        return;
+    let content = fs.readFileSync(filePath, "utf-8");
+    for (const [search, replace] of Object.entries(replacements)) {
+        content = content.replaceAll(search, replace);
+    }
+    fs.writeFileSync(filePath, content);
+}
+function* walkFiles(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            yield* walkFiles(full);
+        }
+        else {
+            yield full;
+        }
+    }
+}
+async function main() {
+    console.log();
+    console.log("  create-slide-deck");
+    console.log("  Scaffold a Reveal.js + React + TypeScript slide deck");
+    console.log();
+    let projectName = process.argv[2];
+    if (!projectName) {
+        projectName = await ask("  Project name: ");
+    }
+    if (!projectName) {
+        console.error("  Error: project name is required.");
+        process.exit(1);
+    }
+    const targetDir = path.resolve(process.cwd(), projectName);
+    if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+        console.error(`  Error: directory "${projectName}" already exists and is not empty.`);
+        process.exit(1);
+    }
+    console.log();
+    console.log("  Templates:");
+    console.log("    1) minimal  — empty deck with one cover slide");
+    console.log("    2) full     — includes 28-page demo showcase for reference");
+    console.log();
+    let choice = await ask("  Choose template (1/2) [1]: ");
+    choice = choice || "1";
+    const templateName = choice === "2" ? "template-full" : "template-minimal";
+    // Templates are siblings of the compiled dist/ output
+    const templateDir = path.join(__dirname, "..", templateName);
+    if (!fs.existsSync(templateDir)) {
+        console.error(`  Error: template "${templateName}" not found.`);
+        process.exit(1);
+    }
+    const deckName = projectName
+        .replace(/[^a-zA-Z0-9-_]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .toLowerCase();
+    console.log();
+    console.log(`  Scaffolding project in ${targetDir}...`);
+    copyDir(templateDir, targetDir);
+    const replacements = {
+        "{{PROJECT_NAME}}": projectName,
+        "{{DECK_NAME}}": deckName,
+    };
+    replaceInFile(path.join(targetDir, "package.json"), replacements);
+    replaceInFile(path.join(targetDir, "vite.config.ts"), replacements);
+    const placeholderDeck = path.join(targetDir, "src", "reveal", "decks", "my-deck");
+    const actualDeck = path.join(targetDir, "src", "reveal", "decks", deckName);
+    if (fs.existsSync(placeholderDeck) && placeholderDeck !== actualDeck) {
+        fs.renameSync(placeholderDeck, actualDeck);
+    }
+    const deckDir = fs.existsSync(actualDeck) ? actualDeck : placeholderDeck;
+    if (fs.existsSync(deckDir)) {
+        for (const file of walkFiles(deckDir)) {
+            replaceInFile(file, replacements);
+        }
+    }
+    console.log();
+    console.log("  Done! Next steps:");
+    console.log();
+    console.log(`    cd ${projectName}`);
+    console.log("    npm install");
+    console.log("    npm run dev");
+    console.log();
+    console.log(`  Open http://localhost:8766/${deckName}/ to see your deck.`);
+    console.log();
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "create-slide-deck",
+  "version": "0.1.0",
+  "description": "Scaffold a Reveal.js slide deck with React components and TypeScript",
+  "type": "module",
+  "bin": {
+    "create-slide-deck": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "template-minimal",
+    "template-full"
+  ],
+  "keywords": [
+    "create",
+    "scaffold",
+    "reveal.js",
+    "slides",
+    "presentation",
+    "react",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lincyaw/slide-deck"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "typescript": "^5.9.3"
+  }
+}

package/template-full/README.md

@@ -0,0 +1,99 @@
+# Slide Template Workspace
+
+这个仓库现在采用 reveal.js-first 的 slide-as-code 工作流：slide 源码放在 `src/reveal/`，共享素材放在 `assets/`，浏览器/PDF 输出放在 `examples/`。
+
+## Quick Map
+
+| Path | Role |
+| --- | --- |
+| `SKILL.md` | 模板的主要视觉规范、版式规则和执行约束。 |
+| `docs/ppt-implementation-spec.md` | Reveal.js-first 的实现规范：Block、Layer、动画、UI/图表库接入方式。 |
+| `src/reveal/` | reveal.js HTML/PDF 输出链路，承载 HTML、SVG、D3 和 JS 动画 slide。 |
+| `src/reveal/decks/` | 每套 deck 的源码、讲稿 notes、节点位置和 reveal 顺序。 |
+| `src/reveal/shared/` | 共享 slide primitives：Block 渲染、设计 token、布局、图标、连接线、图表。 |
+| `examples/microservice-rca/fse26-paper-talk/reveal-summary/` | 当前 FSE26 RCA paper talk 的可浏览 HTML 输出。 |
+| `assets/icons/` | 全项目共享的软件工程图标库，构建时会内联到 slide。 |
+| `assets/` | 共享素材根目录；deck 专属素材优先放在对应 deck 目录下。 |
+
+## Build Commands
+
+```bash
+npm run build:reveal:fse26-rca
+npm run pdf:reveal:fse26-rca
+```
+
+`src/reveal/` 先生成 HTML，再通过 Playwright/Chrome 打印成 PDF。当前 FSE26 deck 是原生 reveal.js HTML，页面由 HTML、CSS、内联 SVG 图标、SVG 图表、D3 连接线和 animejs fragment 动画组成。实现上采用通用 Block 模型，通过 mount block + MountRegistry 可接入 React、ECharts、Cytoscape、Web Components 或任意 JS 库。
+
+## Mount System
+
+Mount block 允许在 slide 中嵌入需要 JS 初始化的交互式组件。运行时由 `MountRegistry` 统一管理生命周期。
+
+### 使用方式
+
+在 slide 定义中使用 `mountBlock`：
+
+```js
+import { mountBlock } from "../../shared/index.mjs";
+
+// React 组件
+mountBlock({
+  mount: { library: "react", exportName: "MyChart", props: { data: [1, 2, 3] } },
+  x: 100, y: 200, w: 500, h: 300,
+})
+
+// animejs 自定义动画
+mountBlock({
+  mount: { library: "anim", props: { translateX: [0, 200], duration: 800, ease: "outQuad" } },
+  html: '<div class="animated-box">Hello</div>',
+  x: 100, y: 200, w: 300, h: 200,
+})
+```
+
+在 build 脚本中通过 `scripts` 传入 mount adapter 和组件脚本：
+
+```js
+import { writeRevealDeck, mountAdapterPaths } from "./reveal-html.mjs";
+
+await writeRevealDeck({
+  rootDir,
+  outPath,
+  title: "My Deck",
+  slides,
+  scripts: [
+    // React (从 CDN 或 node_modules 加载)
+    "https://unpkg.com/react@18/umd/react.production.min.js",
+    "https://unpkg.com/react-dom@18/umd/react-dom.production.min.js",
+    // Mount adapters
+    ...mountAdapterPaths(rootDir, ["react", "anim"]).map(p => rel(outDir, p)),
+    // 自定义组件（注册到 window.SlideComponents）
+    "components.js",
+  ],
+});
+```
+
+### 自定义 Mount Adapter
+
+```js
+// my-adapter.js (browser-side)
+MountRegistry.register("echarts", function (el, ctx) {
+  var chart = echarts.init(el);
+  chart.setOption(ctx.props);
+  return function () { chart.dispose(); };
+});
+```
+
+### 内置 Adapter
+
+| Adapter | 文件 | 用途 |
+| --- | --- | --- |
+| `react` | `src/reveal/mounts/react-mount.js` | 渲染 `window.SlideComponents[exportName]` 为 React 组件 |
+| `anim` | `src/reveal/mounts/anim-mount.js` | 对 block 内元素执行 animejs 动画 |
+
+## Conventions
+
+- Slide 页面内可见文字保持英文。
+- 新增模板规则优先写入 `SKILL.md`。
+- 新增 slide 内容必须优先遵守 `SKILL.md` 的 icon-led progressive storytelling：减少方块化文字模块，避免纯文字页，把长段说明转成图标、证据对象、连接线和可逐步 reveal 的对象组。
+- 新增 deck 源码放到 `src/reveal/decks/<deck-id>/`，可浏览输出放到对应 `examples/<deck-name>/`。
+- 图标优先从 `assets/icons/lucide_core/` 选择，不够时再用 `tabler_extended/` 或 `simpleicons_tech/`。
+- 共享层只放通用 Block、布局、动画和渲染适配；业务语义组件放在具体 deck 目录。

package/template-full/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "pdf": "node src/reveal/tools/export-pdf.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@xyflow/react": "^12.11.0",
+    "animejs": "^4.4.1",
+    "d3-force": "^3.0.0",
+    "d3-hierarchy": "^3.1.2",
+    "d3-interpolate": "^3.0.1",
+    "d3-sankey": "^0.12.3",
+    "d3-scale": "^4.0.2",
+    "d3-shape": "^3.2.0",
+    "framer-motion": "^12.40.0",
+    "katex": "^0.17.0",
+    "lucide-react": "^1.21.0",
+    "pdf-lib": "^1.17.1",
+    "playwright": "^1.61.0",
+    "prismjs": "^1.30.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "reveal.js": "^6.0.1",
+    "roughjs": "^4.6.6"
+  },
+  "devDependencies": {
+    "@types/d3-force": "^3.0.10",
+    "@types/d3-hierarchy": "^3.1.7",
+    "@types/d3-interpolate": "^3.0.4",
+    "@types/d3-sankey": "^0.12.5",
+    "@types/d3-scale": "^4.0.9",
+    "@types/d3-shape": "^3.1.8",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "chokidar": "^5.0.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16"
+  }
+}

package/template-full/src/reveal/components/auto-layout.ts

@@ -0,0 +1,229 @@
+/**
+ * Generic empty-slot finder for slide annotations.
+ *
+ * Given a canvas size, a list of occupied rectangles, and a desired slot size,
+ * finds the best position that:
+ *   1. Does not overlap any occupied rect (with margin)
+ *   2. Maximizes distance from occupied rects (use empty space well)
+ *   3. Optionally stays close to a "near" point (e.g. the active node)
+ *
+ * Usage:
+ *   const pos = findEmptySlot({
+ *     canvasW: 1200, canvasH: 700,
+ *     occupied: [ {x:10, y:10, w:200, h:150}, ... ],
+ *     slotW: 500, slotH: 160,
+ *     margin: 16,
+ *     near: { x: 300, y: 100 },   // optional: prefer positions near this point
+ *   });
+ *   // pos = { x, y }
+ */
+
+export interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface FindEmptySlotOpts {
+  canvasW: number;
+  canvasH: number;
+  occupied: Rect[];
+  slotW: number;
+  slotH: number;
+  margin?: number;
+  near?: Point | null;
+  step?: number;
+}
+
+export interface FindLargestSlotOpts {
+  canvasW: number;
+  canvasH: number;
+  occupied: Rect[];
+  maxW?: number;
+  maxH?: number;
+  margin?: number;
+  step?: number;
+  near?: Point | null;
+}
+
+interface CascadeNode {
+  step: number;
+  id: string;
+  col: number;
+  row: number;
+}
+
+export interface NodeOccupiedRectsOpts {
+  nx: (col: number) => number;
+  ny: (row: number) => number;
+  iconR: number;
+  labelH?: number;
+}
+
+function rectsOverlap(a: Rect, b: Rect, gap: number): boolean {
+  return !(a.x + a.w + gap <= b.x || b.x + b.w + gap <= a.x ||
+           a.y + a.h + gap <= b.y || b.y + b.h + gap <= a.y);
+}
+
+function rectMinDist(slot: Rect, rect: Rect): number {
+  const dx = Math.max(rect.x - (slot.x + slot.w), slot.x - (rect.x + rect.w), 0);
+  const dy = Math.max(rect.y - (slot.y + slot.h), slot.y - (rect.y + rect.h), 0);
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+export function findEmptySlot({
+  canvasW,
+  canvasH,
+  occupied,
+  slotW,
+  slotH,
+  margin = 16,
+  near = null,
+  step = 16,
+}: FindEmptySlotOpts): Point {
+  let bestPos: Point = { x: margin, y: canvasH - slotH - margin };
+  let bestScore = -Infinity;
+
+  for (let y = margin; y + slotH <= canvasH - margin; y += step) {
+    for (let x = margin; x + slotW <= canvasW - margin; x += step) {
+      const slot: Rect = { x: x, y: y, w: slotW, h: slotH };
+
+      let overlaps = false;
+      for (let i = 0; i < occupied.length; i++) {
+        if (rectsOverlap(slot, occupied[i], margin)) {
+          overlaps = true;
+          break;
+        }
+      }
+      if (overlaps) continue;
+
+      let minDist = Infinity;
+      for (let j = 0; j < occupied.length; j++) {
+        const d = rectMinDist(slot, occupied[j]);
+        if (d < minDist) minDist = d;
+      }
+
+      // Small bonus for not being jammed against a node, but cap it low
+      let score = Math.min(minDist, 30) * 0.5;
+
+      // Primary: stay as close as possible to the active node
+      if (near) {
+        const dx = (x + slotW / 2) - near.x;
+        const dy = (y + slotH / 2) - near.y;
+        score -= Math.sqrt(dx * dx + dy * dy) * 0.8;
+      }
+
+      // Slight preference for horizontally centered positions
+      const cxDist = Math.abs(x + slotW / 2 - canvasW / 2);
+      score -= cxDist * 0.02;
+
+      if (score > bestScore) {
+        bestScore = score;
+        bestPos = { x: x, y: y };
+      }
+    }
+  }
+
+  return bestPos;
+}
+
+/**
+ * Find the largest empty rectangle in the canvas that doesn't overlap any occupied rect.
+ * Returns { x, y, w, h }. If maxW/maxH are provided, the result is capped.
+ */
+export function findLargestSlot({
+  canvasW, canvasH, occupied,
+  maxW, maxH,
+  margin = 14,
+  step = 18,
+  near = null,
+}: FindLargestSlotOpts): Rect {
+  maxW = maxW || (canvasW - 2 * margin);
+  maxH = maxH || (canvasH - 2 * margin);
+
+  let best: Rect | null = null;
+  let bestScore = -Infinity;
+
+  for (let y = margin; y < canvasH - margin - 60; y += step) {
+    for (let x = margin; x < canvasW - margin - 60; x += step) {
+      let inside = false;
+      for (let i = 0; i < occupied.length; i++) {
+        const r = occupied[i];
+        if (x >= r.x - margin && x < r.x + r.w + margin &&
+            y >= r.y - margin && y < r.y + r.h + margin) {
+          inside = true; break;
+        }
+      }
+      if (inside) continue;
+
+      let w = Math.min(canvasW - margin - x, maxW);
+      for (let i = 0; i < occupied.length; i++) {
+        const r = occupied[i];
+        const rl = r.x - margin;
+        if (rl > x && rl < x + w &&
+            y < r.y + r.h + margin && y + maxH > r.y - margin) {
+          w = Math.min(w, rl - x);
+        }
+      }
+
+      let h = Math.min(canvasH - margin - y, maxH);
+      for (let i = 0; i < occupied.length; i++) {
+        const r = occupied[i];
+        const rt = r.y - margin;
+        if (rt > y && rt < y + h &&
+            x < r.x + r.w + margin && x + w > r.x - margin) {
+          h = Math.min(h, rt - y);
+        }
+      }
+
+      if (w < 60 || h < 60) continue;
+
+      const area = w * h;
+      let score = area;
+      if (near) {
+        const dx = (x + w / 2) - near.x;
+        const dy = (y + h / 2) - near.y;
+        score -= Math.sqrt(dx * dx + dy * dy) * 50;
+      }
+
+      if (score > bestScore) {
+        bestScore = score;
+        best = { x: x, y: y, w: w, h: h };
+      }
+    }
+  }
+
+  return best || { x: margin, y: margin, w: maxW, h: maxH };
+}
+
+/**
+ * Build occupied rectangles from cascade nodes that are visible at a given step.
+ * Each node becomes a bounding rect covering its icon circle + label area.
+ */
+export function nodeOccupiedRects(
+  nodes: CascadeNode[],
+  visibleStep: number,
+  { nx, ny, iconR, labelH = 50 }: NodeOccupiedRectsOpts,
+): Rect[] {
+  const rects: Rect[] = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    if (n.step > visibleStep) continue;
+    const cx = nx(n.col);
+    const cy = ny(n.row);
+    const r = (n.id === "dns" || n.id === "users") ? iconR + 4 : iconR;
+    rects.push({
+      x: cx - r - 12,
+      y: cy - r - 30,
+      w: 2 * (r + 12),
+      h: 2 * r + 30 + labelH,
+    });
+  }
+  return rects;
+}