slides-grab 1.3.0 → 1.4.0

package/README-ko.md

@@ -54,11 +54,13 @@ CLI와 공유 에이전트 스킬만 사용하려면 npm 패키지를 설치하
 ```bash
 npm install slides-grab
 npx playwright install chromium
-npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy
+npx slides-grab install-skills --target all --scope user
 ```
 
 이 방법은 일반적인 사용에 충분합니다. slides-grab 자체를 수정하거나 기여하려는 경우에만 저장소를 클론하세요.
 
+이 명령은 같은 공유 Agent Skills와 얇은 런타임 adapter를 Codex 런타임과 Claude Code 런타임 위치에 모두 설치합니다. 패키지된 워크플로우는 번들된 `SKILL.md`, `references/`, `slides-grab` CLI만 사용합니다. `slides-grab pdf`, `slides-grab convert`, `slides-grab figma` export는 현재 슬라이드 파일에 대한 최신 `slides-grab design-gate` `proceed` 기록이 없으면 차단됩니다.
+
 ## 왜 slides-grab인가요?
 
 많은 AI 도구가 슬라이드 HTML을 생성하지만, 사용자가 화면에서 **수정하고 싶은 부분을 직접 가리키고** 그 자리에서 반복 편집할 수 있게 해 주는 도구는 드뭅니다. slides-grab은 다음 흐름을 제공합니다.
@@ -72,7 +74,7 @@ npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --cop
 
 워크플로 명령은 `--slides-dir <path>`를 지원하며 기본값은 `slides`입니다.
 
-새 클론에서는 `--help`, `list-templates`, `list-styles`, `preview-styles` 같은 탐색 명령은 덱 없이도 동작합니다. `edit`, `build-viewer`, `validate`, `convert`, `pdf`는 `slide-*.html` 파일이 들어 있는 슬라이드 작업공간이 필요합니다.
+새 클론에서는 `--help`, `list-templates`, `list-styles`, `preview-styles` 같은 탐색 명령은 덱 없이도 동작합니다. `edit`, `build-viewer`, `validate`, `png`, `design-gate`는 `slide-*.html` 파일이 들어 있는 슬라이드 작업공간이 필요하고, `convert`, `pdf`, `figma`는 추가로 최신 `Proceed` design gate가 필요합니다.
 
 ```bash
 slides-grab edit              # 시각적 슬라이드 편집기 실행
@@ -90,13 +92,13 @@ slides-grab image --prompt "..."    # 로컬 슬라이드 이미지 생성
 slides-grab fetch-video --url <youtube-url> --slides-dir decks/my-deck  # yt-dlp로 동영상 에셋 다운로드
 slides-grab tldraw            # .tldr 다이어그램을 슬라이드 크기의 로컬 SVG로 렌더링
 slides-grab list-templates    # 사용 가능한 슬라이드 템플릿 표시
-slides-grab list-styles       # 번들된 35개 디자인 스타일 표시
-slides-grab preview-styles    # 35개 스타일 미리보기 갤러리를 브라우저에서 열기
+slides-grab list-styles       # 기본으로 선택 가능한 92개 디자인 스타일 표시 (3개 소스-앨리어스를 포함해 95개 해석 가능; --all로 전체 표시)
+slides-grab preview-styles    # 95개 스타일 미리보기 갤러리를 브라우저에서 열기
 ```
 
 ## 디자인 스타일 모음
 
-slides-grab은 [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles)에서 파생된 30개 스타일과 slides-grab 고유 스타일 5개, 총 35개 디자인 스타일을 제공합니다. 에이전트에게 특정 스타일을 요청하거나 완전히 커스텀 디자인을 요청할 수 있습니다.
+slides-grab은 [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles)에서 파생된 30개 스타일, slides-grab 고유 스타일 5개, [epoko77-ai/design-diversity](https://github.com/epoko77-ai/design-diversity)에서 파생된 PPT 팩 60개를 포함해 총 95개 디자인 스타일을 제공합니다. 60개 design-diversity PPT 팩은 분류됩니다 — 직접 중복은 빌트인에 앨리어스 처리(기본 숨김)되고, 유사 중복은 `relatedStyleIds`로 연결되며, 완전히 새 팩은 추가됩니다. 따라서 92개만 기본으로 선택 가능하며 95개 모두 해석 가능합니다(`list-styles --all`로 앨리어스 확인). 에이전트에게 특정 스타일을 요청하거나 완전히 커스텀 디자인을 요청할 수 있습니다.
 
 ```bash
 slides-grab list-styles
@@ -229,7 +231,7 @@ npm install slides-grab
 Vercel Agent Skills로 공유 에이전트 스킬을 설치하려면 다음을 실행하세요.
 
 ```bash
-npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy
+npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy --full-depth
 ```
 
 이 npm 설치 경로는 일반적인 사용에 충분합니다. slides-grab 자체를 수정하거나 기여하려는 경우에만 저장소를 클론하세요.

package/README.md

@@ -64,9 +64,11 @@ npm ci && npx playwright install chromium
 ```bash
 npm install slides-grab
 npx playwright install chromium
-npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy
+npx slides-grab install-skills --target all --scope user
 ```
 
+This installs the same shared Agent Skills plus lightweight runtime adapters into Codex and Claude Code locations. The packaged workflow relies on bundled `SKILL.md` files, bundled `references/`, and the `slides-grab` CLI. Exports through `slides-grab pdf`, `slides-grab convert`, and `slides-grab figma` are blocked until `slides-grab design-gate` records a fresh `proceed` receipt for the current slide files.
+
 ## Why This Project?
 
 There are many AI tools that generate slide HTML. Almost none let you **visually point at what you want changed** and iterate in-place. slides-grab fills that gap:
@@ -80,7 +82,7 @@ There are many AI tools that generate slide HTML. Almost none let you **visually
 
 Workflow commands support `--slides-dir <path>` (default: `slides`).
 
-On a fresh clone, the discovery commands (`--help`, `list-templates`, `list-styles`, and `preview-styles`) work without a deck. `edit`, `build-viewer`, `validate`, `convert`, and `pdf` require an existing slides workspace containing `slide-*.html`.
+On a fresh clone, the discovery commands (`--help`, `list-templates`, `list-styles`, and `preview-styles`) work without a deck. `edit`, `build-viewer`, `validate`, `png`, and `design-gate` require an existing slides workspace containing `slide-*.html`; `convert`, `pdf`, and `figma` additionally require a fresh `Proceed` design gate.
 
 ```bash
 slides-grab edit              # Launch visual slide editor
@@ -98,13 +100,13 @@ slides-grab image --prompt "..."    # Generate a local slide image with god-tibo
 slides-grab fetch-video --url <youtube-url> --slides-dir decks/my-deck  # Download a local video asset with yt-dlp
 slides-grab tldraw           # Render a .tldr diagram into a slide-sized local SVG asset
 slides-grab list-templates    # Show available slide templates
-slides-grab list-styles       # Show 35 bundled design styles (browse, preview, select)
-slides-grab preview-styles                        # Open the 35-style visual gallery in browser
+slides-grab list-styles       # Show 92 selectable design styles by default (95 resolvable incl. 3 source-aliases; --all shows all)
+slides-grab preview-styles                        # Open the 95-style visual gallery in browser
 ```
 
 ## Design Style Collections
 
-slides-grab bundles 35 design styles: 30 derived from [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles) plus 5 slides-grab originals. Agents can also create fully custom designs beyond the bundled collection.
+slides-grab bundles 95 design styles: 30 derived from [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles), 5 slides-grab originals, and 60 PPT packs derived from [epoko77-ai/design-diversity](https://github.com/epoko77-ai/design-diversity). The 60 design-diversity PPT packs are classified — direct duplicates are aliased to builtins (hidden by default), near-duplicates are linked via `relatedStyleIds`, and net-new packs are added — so 92 are selectable by default while all 95 remain resolvable (use `list-styles --all` to see aliases). Agents can also create fully custom designs beyond the bundled collection.
 
 ```bash
 slides-grab list-styles                           # Browse the catalog
@@ -237,7 +239,7 @@ npm install slides-grab
 Install shared agent skills with Vercel Agent Skills:
 
 ```bash
-npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy
+npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy --full-depth
 ```
 
 This npm-install path is enough for normal usage. Clone the repo only when you want to modify or contribute to `slides-grab` itself.

package/bin/ppt-agent.js

@@ -9,6 +9,7 @@ import {
   getFigmaImportCaveats,
   getFigmaManualImportInstructions,
 } from '../src/figma.js';
+import { assertDesignGateReady } from '../src/design-gate-state.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, '..');
@@ -64,6 +65,17 @@ async function runCommand(relativePath, args = []) {
   }
 }
 
+async function ensureDesignGateForExport(slidesDir, label) {
+  try {
+    await assertDesignGateReady(resolve(process.cwd(), slidesDir), { label });
+  } catch (error) {
+    console.error(`[slides-grab] ${error.message}`);
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
 function collectRepeatedOption(value, previous = []) {
   return [...previous, value];
 }
@@ -109,6 +121,66 @@ program
     await runCommand('scripts/validate-slides.js', args);
   });
 
+program
+  .command('design-gate')
+  .description('Record the required visual QA gate evidence before export')
+  .option('--slides-dir <path>', 'Slide directory', 'slides')
+  .option('--slide-mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
+  .option('--resolution <preset>', 'PNG evidence resolution preset: 720p, 1080p, 1440p, 2160p, or 4k', '2160p')
+  .requiredOption('--verdict <verdict>', 'Gate verdict: proceed, revise, or rethink')
+  .requiredOption('--pass-a-report <path>', 'Pass A review report file')
+  .requiredOption('--pass-b-report <path>', 'Pass B review report file')
+  .option('--output-dir <path>', 'PNG evidence directory (default: <slides-dir>/.slides-grab/gate-preview)')
+  .action(async (options = {}) => {
+    const args = [
+      '--slides-dir',
+      options.slidesDir,
+      '--slide-mode',
+      options.slideMode,
+      '--resolution',
+      options.resolution,
+      '--verdict',
+      options.verdict,
+      '--pass-a-report',
+      options.passAReport,
+      '--pass-b-report',
+      options.passBReport,
+    ];
+    if (options.outputDir) {
+      args.push('--output-dir', String(options.outputDir));
+    }
+    await runCommand('scripts/design-gate.js', args);
+  });
+
+function registerInstallSkillsCommand(commandName) {
+  program
+    .command(commandName)
+    .description('Install slides-grab skills and lightweight runtime adapters for Codex and Claude Code')
+    .option('--target <target>', 'Runtime target: all, codex, or claude-code', 'all')
+    .option('--runtime <target>', 'Alias for --target')
+    .option('--scope <scope>', 'Install scope: project or user', 'project')
+    .option('--project-dir <path>', 'Project directory for project scope')
+    .option('--target-root <path>', 'Root directory for user-style installs')
+    .option('--dry-run', 'Print planned writes without copying')
+    .option('--json', 'Print JSON result')
+    .action(async (options = {}) => {
+      const args = [
+        '--target',
+        String(options.runtime || options.target),
+        '--scope',
+        String(options.scope),
+      ];
+      if (options.projectDir) args.push('--project-dir', String(options.projectDir));
+      if (options.targetRoot) args.push('--target-root', String(options.targetRoot));
+      if (options.dryRun) args.push('--dry-run');
+      if (options.json) args.push('--json');
+      await runCommand('scripts/install-runtime.js', args);
+    });
+}
+
+registerInstallSkillsCommand('install-skills');
+registerInstallSkillsCommand('install-runtime');
+
 program
   .command('convert')
   .description('Convert slide HTML files to experimental / unstable PPTX')
@@ -117,6 +189,7 @@ program
   .option('--mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .option('--resolution <preset>', 'Raster size preset: 720p, 1080p, 1440p, 2160p, or 4k (default: 2160p)')
   .action(async (options = {}) => {
+    if (!(await ensureDesignGateForExport(options.slidesDir, 'PPTX export'))) return;
     const args = ['--slides-dir', options.slidesDir, '--mode', options.mode];
     if (options.output) {
       args.push('--output', String(options.output));
@@ -136,6 +209,7 @@ program
   .option('--slide-mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .option('--resolution <preset>', 'Capture raster size preset: 720p, 1080p, 1440p, 2160p, or 4k (default: 2160p in capture mode)')
   .action(async (options = {}) => {
+    if (!(await ensureDesignGateForExport(options.slidesDir, 'PDF export'))) return;
     const args = ['--slides-dir', options.slidesDir];
     if (options.output) {
       args.push('--output', String(options.output));
@@ -196,6 +270,7 @@ program
   .option('--mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .addHelpText('after', figmaHelpText)
   .action(async (options = {}) => {
+    if (!(await ensureDesignGateForExport(options.slidesDir, 'Figma export'))) return;
     const args = ['--slides-dir', options.slidesDir, '--mode', options.mode];
     if (options.output) {
       args.push('--output', String(options.output));
@@ -295,10 +370,12 @@ program
 program
   .command('list-styles')
   .description('List bundled design styles agents and users can reference during slide generation')
-  .action(async () => {
+  .option('--all', 'Include source-alias styles that resolve to a builtin (hidden by default)')
+  .action(async (options = {}) => {
     try {
-      const { listDesignStyles } = await import('../src/design-styles.js');
-      const styles = listDesignStyles();
+      const { listDesignStyles, listSelectableDesignStyles } = await import('../src/design-styles.js');
+      const showAll = Boolean(options.all);
+      const styles = showAll ? listDesignStyles() : listSelectableDesignStyles();
 
       if (styles.length === 0) {
         console.log('No bundled design styles found.');
@@ -307,11 +384,33 @@ program
 
       console.log('Available design styles:\n');
       for (const style of styles) {
-        console.log(`  ${style.id.padEnd(22)} ${style.title}`);
+        let tag;
+        if (style.classification === 'builtin') {
+          tag = '[builtin]';
+        } else if (style.classification === 'source-variant') {
+          tag = '[variant]';
+        } else if (style.classification === 'source-alias') {
+          tag = `[alias -> ${style.aliasOf}]`;
+        } else {
+          tag = '[new]';
+        }
+        console.log(`  ${style.id.padEnd(38)} ${tag} ${style.title}`);
         console.log(`    ${style.mood} · ${style.bestFor}`);
+        if (style.classification === 'source-variant' && Array.isArray(style.relatedStyleIds) && style.relatedStyleIds.length) {
+          console.log(`    related: ${style.relatedStyleIds.join(', ')}`);
+        }
       }
 
-      console.log(`\nTotal: ${styles.length} styles`);
+      const totalResolvable = listDesignStyles().length;
+      if (!showAll) {
+        const hiddenCount = totalResolvable - styles.length;
+        console.log(`\nTotal: ${styles.length} selectable styles`);
+        console.log(`${hiddenCount} source-alias slug(s) hidden (resolve to a builtin); use --all to show all ${totalResolvable} resolvable styles`);
+      } else {
+        const selectableCount = listSelectableDesignStyles().length;
+        const aliasCount = totalResolvable - selectableCount;
+        console.log(`\nTotal: ${styles.length} resolvable styles (${selectableCount} selectable, ${aliasCount} aliases)`);
+      }
       console.log('Preview: slides-grab preview-styles [--style <id>]');
     } catch (error) {
       reportCliError(error);
@@ -320,7 +419,7 @@ program
 
 program
   .command('preview-styles')
-  .description('Print the path to the bundled 35-style visual preview gallery')
+  .description('Print the path to the bundled 95-style visual preview gallery')
   .action(async () => {
     try {
       const { getPreviewHtmlPath } = await import('../src/design-styles.js');
@@ -418,6 +517,12 @@ program
         console.log(`# Bundled style: ${style.title} (${style.id})`);
         console.log(`Mood: ${style.mood}`);
         console.log(`Best for: ${style.bestFor}`);
+        if (style.source?.repo) console.log(`Source: ${style.source.repo}`);
+        if (style.source?.url) console.log(`Source URL: ${style.source.url}`);
+        if (style.classification) console.log(`Classification: ${style.classification}`);
+        if (style.aliasOf) console.log(`Alias of: ${style.aliasOf}`);
+        if (Array.isArray(style.aliases) && style.aliases.length) console.log(`Aliases: ${style.aliases.join(', ')}`);
+        if (Array.isArray(style.relatedStyleIds) && style.relatedStyleIds.length) console.log(`Related styles: ${style.relatedStyleIds.join(', ')}`);
         if (Array.isArray(style.background)) {
           console.log('\n## Background');
           for (const b of style.background) console.log(`- ${b}`);
@@ -434,6 +539,14 @@ program
           console.log('\n## Layout');
           for (const l of style.layout) console.log(`- ${l}`);
         }
+        if (Array.isArray(style.signature)) {
+          console.log('\n## Signature');
+          for (const s of style.signature) console.log(`- ${s}`);
+        }
+        if (Array.isArray(style.avoid)) {
+          console.log('\n## Avoid');
+          for (const a of style.avoid) console.log(`- ${a}`);
+        }
       }
     } catch (error) {
       reportCliError(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slides-grab",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Agent-first presentation framework — plan, design, and visually edit HTML slides with Claude Code or Codex, then export to PDF or experimental/unstable PPTX/Figma formats",
   "license": "MIT",
   "author": "vkehfdl1",
@@ -39,10 +39,14 @@
     "scripts/generate-image.js",
     "src/god-tibo-imagen.js",
     "scripts/figma-export.js",
+    "scripts/design-gate.js",
     "scripts/html2pdf.js",
+    "scripts/html2png.js",
     "scripts/html2pptx.js",
+    "scripts/install-runtime.js",
     "scripts/render-tldraw.js",
     "scripts/validate-slides.js",
+    "runtimes/",
     "skills/",
     "src/",
     "templates/",
@@ -56,7 +60,7 @@
     "build:showcase": "node showcase/scripts/build-manifest.js",
     "validate": "node scripts/validate-slides.js",
     "convert": "node convert.cjs",
-    "test": "node --test --test-concurrency=1 tests/docs/readme-ko.test.js tests/design/design-styles.test.js tests/design/design-md-parser.test.js tests/editor/editor-codex-edit.test.js tests/editor/edit-subprocess-abort.test.js tests/editor/editor-server.test.js tests/editor/editor-server-orphan-prevention.test.js tests/editor/editor-model-dispatch.test.js tests/god-tibo/god-tibo.test.js tests/nano-banana/nano-banana.test.js tests/pdf/html2pdf.test.js tests/pdf/html2pdf.e2e.test.js tests/figma/figma-export.test.js tests/image-contract/image-contract.test.js tests/tldraw/render-tldraw.test.js tests/validation/validate-slides.test.js tests/viewer/build-viewer.test.js tests/skills/installable-skills.test.js tests/video/download-video.test.js",
+    "test": "node --test --test-concurrency=1 tests/docs/readme-ko.test.js tests/design/design-styles.test.js tests/design/design-md-parser.test.js tests/design-gate/design-gate.test.js tests/runtime/install-runtime.test.js tests/editor/editor-codex-edit.test.js tests/editor/edit-subprocess-abort.test.js tests/editor/editor-server.test.js tests/editor/editor-server-orphan-prevention.test.js tests/editor/editor-model-dispatch.test.js tests/god-tibo/god-tibo.test.js tests/nano-banana/nano-banana.test.js tests/pdf/html2pdf.test.js tests/pdf/html2pdf.e2e.test.js tests/figma/figma-export.test.js tests/image-contract/image-contract.test.js tests/tldraw/render-tldraw.test.js tests/validation/validate-slides.test.js tests/viewer/build-viewer.test.js tests/skills/installable-skills.test.js tests/video/download-video.test.js",
     "test:e2e": "node --test tests/editor/editor-ui.e2e.test.js tests/editor/editor-concurrency.e2e.test.js"
   },
   "dependencies": {

package/runtimes/claude-code/agents/design-critic-agent.md

@@ -0,0 +1,23 @@
+---
+name: design-critic-agent
+description: Run the slides-grab design gate before export.
+tools: Read, Grep, Glob, Bash, Task
+---
+
+Use the canonical gate in `skills/slides-grab-design/references/design-gate.md`.
+
+Required workflow:
+
+1. Run `slides-grab validate --slides-dir <slides-dir>`.
+2. Render evidence with `slides-grab png --slides-dir <slides-dir> --output-dir <slides-dir>/.slides-grab/gate-preview`.
+3. Produce two read-only review reports:
+   - Pass A: System Contract / Constraint Integrity.
+   - Pass B: Audience Impact / Expressive Readability.
+   Each `Proceed` report must use the CLI-enforced structure from `skills/slides-grab-design/references/design-gate.md`: role title, `VERDICT: PASS`, confidence, rendered PNG evidence filenames, current `slide-*.html: <sha256>` fingerprints, `Unresolved Critical: 0`, `Blocking findings: None`, findings table, and all required checks marked `PASS`.
+4. If both passes conclude Proceed, record the gate with:
+
+```bash
+slides-grab design-gate --slides-dir <slides-dir> --verdict proceed --pass-a-report <pass-a.md> --pass-b-report <pass-b.md>
+```
+
+If either pass finds blocking issues, or if `slides-grab design-gate` rejects the reports, fix the slides/reports and repeat from validation and fresh rendered evidence. Do not run `slides-grab pdf`, `slides-grab convert`, or `slides-grab figma` until the CLI gate records `proceed`.

package/runtimes/codex/agents/slides-grab-design-critic.md

@@ -0,0 +1,22 @@
+---
+name: slides-grab-design-critic
+description: Run the slides-grab design gate before export.
+---
+
+Use the canonical gate in `skills/slides-grab-design/references/design-gate.md`.
+
+Required workflow:
+
+1. Run `slides-grab validate --slides-dir <slides-dir>`.
+2. Render evidence with `slides-grab png --slides-dir <slides-dir> --output-dir <slides-dir>/.slides-grab/gate-preview`.
+3. Produce two read-only review reports:
+   - Pass A: System Contract / Constraint Integrity.
+   - Pass B: Audience Impact / Expressive Readability.
+   Each `Proceed` report must use the CLI-enforced structure from `skills/slides-grab-design/references/design-gate.md`: role title, `VERDICT: PASS`, confidence, rendered PNG evidence filenames, current `slide-*.html: <sha256>` fingerprints, `Unresolved Critical: 0`, `Blocking findings: None`, findings table, and all required checks marked `PASS`.
+4. If both passes conclude Proceed, record the gate with:
+
+```bash
+slides-grab design-gate --slides-dir <slides-dir> --verdict proceed --pass-a-report <pass-a.md> --pass-b-report <pass-b.md>
+```
+
+If either pass finds blocking issues, or if `slides-grab design-gate` rejects the reports, fix the slides/reports and repeat from validation and fresh rendered evidence. Do not run `slides-grab pdf`, `slides-grab convert`, or `slides-grab figma` until the CLI gate records `proceed`.

package/scripts/build-viewer.js

@@ -10,8 +10,8 @@
 
 import { readFileSync, writeFileSync, readdirSync } from 'fs';
 import { createRequire } from 'node:module';
-import { join, resolve } from 'path';
-import { fileURLToPath } from 'url';
+import { dirname, extname, join, resolve } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
 
 import { buildSlideRuntimeHtml } from '../src/image-contract.js';
 
@@ -24,6 +24,25 @@ const {
 } = require('../src/slide-mode.cjs');
 
 const DEFAULT_SLIDES_DIR = 'slides';
+const LOCAL_ASSET_PREFIX = './assets/';
+
+// Deliberate sandbox decision: allow-scripts (so Chart.js and other in-slide JS
+// render in the viewer) WITHOUT allow-same-origin. Omitting allow-same-origin gives
+// each iframe an opaque origin so first-party slide content cannot reach the parent
+// viewer document. Because relative URLs break under an opaque origin, local
+// ./assets/ references are inlined as data: URLs in loadSlides()/inlineLocalAssetsForSrcdoc.
+const SLIDE_FRAME_SANDBOX = 'allow-scripts';
+
+const MIME_BY_EXTENSION = new Map([
+  ['.avif', 'image/avif'],
+  ['.gif', 'image/gif'],
+  ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'],
+  ['.mp4', 'video/mp4'],
+  ['.png', 'image/png'],
+  ['.svg', 'image/svg+xml'],
+  ['.webp', 'image/webp'],
+]);
 
 function printUsage() {
   process.stdout.write(
@@ -127,18 +146,61 @@ export function escapeForSrcdoc(html) {
 }
 
 export function loadSlides(slidesDir) {
+  const slideBaseHref = pathToFileURL(`${resolve(slidesDir)}/`).href;
   return findSlideFiles(slidesDir).map((file) => {
-    const html = readFileSync(join(slidesDir, file), 'utf-8');
+    const slidePath = join(slidesDir, file);
+    const html = inlineLocalAssetsForSrcdoc(readFileSync(slidePath, 'utf-8'), slidePath);
     return {
       file,
       html: buildSlideRuntimeHtml(html, {
-        baseHref: './',
+        baseHref: slideBaseHref,
         slideFile: file,
       }),
     };
   });
 }
 
+function getMimeType(filePath) {
+  return MIME_BY_EXTENSION.get(extname(filePath).toLowerCase()) || 'application/octet-stream';
+}
+
+function toDataUrl(filePath) {
+  const bytes = readFileSync(filePath);
+  return `data:${getMimeType(filePath)};base64,${bytes.toString('base64')}`;
+}
+
+export function inlineLocalAssetsForSrcdoc(html, slidePath) {
+  const resolveAsset = (source) => {
+    if (!source.startsWith(LOCAL_ASSET_PREFIX)) {
+      return source;
+    }
+
+    try {
+      return toDataUrl(resolve(dirname(slidePath), source));
+    } catch {
+      return source;
+    }
+  };
+
+  return html
+    .replace(/\b(src|poster)=("([^"]*)"|'([^']*)')/gi, (match, attribute, quoted, doubleValue, singleValue) => {
+      const value = doubleValue ?? singleValue ?? '';
+      const nextValue = resolveAsset(value);
+      if (nextValue === value) {
+        return match;
+      }
+      const quote = quoted.startsWith("'") ? "'" : '"';
+      return `${attribute}=${quote}${nextValue}${quote}`;
+    })
+    .replace(/url\(\s*(['"]?)(\.\/assets\/[^'")]+)\1\s*\)/gi, (match, quote, source) => {
+      const nextValue = resolveAsset(source);
+      if (nextValue === source) {
+        return match;
+      }
+      return `url("${nextValue}")`;
+    });
+}
+
 export function buildViewerHtml(slides, { slideMode = DEFAULT_SLIDE_MODE } = {}) {
   const { framePt } = getSlideModeConfig(slideMode);
 
@@ -261,7 +323,7 @@ export function buildViewerHtml(slides, { slideMode = DEFAULT_SLIDE_MODE } = {})
 
     <div class="slide-viewport" id="viewport">
       <div class="slide-scaler" id="scaler">
-${slides.map((s, i) => `        <iframe class="slide-frame${i === 0 ? ' active' : ''}" data-slide="${i + 1}" srcdoc="${escapeForSrcdoc(s.html)}" sandbox="allow-same-origin"></iframe>`).join('\n')}
+${slides.map((s, i) => `        <iframe class="slide-frame${i === 0 ? ' active' : ''}" data-slide="${i + 1}" srcdoc="${escapeForSrcdoc(s.html)}" sandbox="${SLIDE_FRAME_SANDBOX}"></iframe>`).join('\n')}
       </div>
     </div>
   </div>