slides-grab 1.1.5 → 1.2.0

package/README.md

@@ -82,6 +82,7 @@ slides-grab figma             # Export an experimental / unstable Figma Slides i
 slides-grab pdf               # Export PDF in capture mode (default)
 slides-grab pdf --resolution 2160p  # Higher-resolution image-backed PDF export
 slides-grab pdf --mode print  # Export searchable/selectable text PDF
+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-themes       # Show available color themes
 ```
@@ -116,6 +117,27 @@ slides-grab figma      --slides-dir decks/my-deck --output decks/my-deck-figma.p
 
 > **Warning:** `slides-grab convert` and `slides-grab figma` are currently **experimental / unstable**. Expect best-effort output, layout shifts, and manual cleanup in PowerPoint or Figma.
 
+### Tldraw Diagram Assets
+
+Use `slides-grab tldraw` when you want a newly authored `tldraw` diagram to fit an exact slide region and remain export-friendly as a local SVG asset. The command supports current-format `.tldr` files and store-snapshot JSON; legacy pre-records `.tldr` files must be reopened and resaved in a current `tldraw` build first:
+
+```bash
+slides-grab tldraw \
+  --input decks/my-deck/assets/system.tldr \
+  --output decks/my-deck/assets/system.svg \
+  --width 640 \
+  --height 320 \
+  --padding 16
+```
+
+Then reference the generated SVG from your slide HTML with a normal local image:
+
+```html
+<img src="./assets/system.svg" alt="System architecture diagram">
+```
+
+The built-in `diagram-tldraw` template is a simple starting point for this workflow.
+
 ### Figma Workflow
 
 ```bash

package/bin/ppt-agent.js

@@ -154,6 +154,28 @@ program
     await runCommand('scripts/figma-export.js', args);
   });
 
+program
+  .command('tldraw')
+  .description('Render a current-format .tldr or store-snapshot JSON file to an exact-size SVG asset for slides')
+  .option('--input <path>', 'Input current-format .tldr or snapshot JSON file')
+  .option('--output <path>', 'Output SVG asset path')
+  .option('--width <number>', 'Exact output width in CSS pixels')
+  .option('--height <number>', 'Exact output height in CSS pixels')
+  .option('--padding <number>', 'Inner fit padding in CSS pixels')
+  .option('--background <css>', 'Optional wrapper background fill')
+  .option('--page-id <id>', 'Optional tldraw page id to export')
+  .action(async (options = {}) => {
+    const args = [];
+    if (options.input) args.push('--input', String(options.input));
+    if (options.output) args.push('--output', String(options.output));
+    if (options.width) args.push('--width', String(options.width));
+    if (options.height) args.push('--height', String(options.height));
+    if (options.padding) args.push('--padding', String(options.padding));
+    if (options.background) args.push('--background', String(options.background));
+    if (options.pageId) args.push('--page-id', String(options.pageId));
+    await runCommand('scripts/render-tldraw.js', args);
+  });
+
 program
   .command('edit')
   .description('Start interactive slide editor with Codex image-based edit flow')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slides-grab",
-  "version": "1.1.5",
+  "version": "1.2.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",
@@ -38,6 +38,7 @@
     "scripts/figma-export.js",
     "scripts/html2pdf.js",
     "scripts/html2pptx.js",
+    "scripts/render-tldraw.js",
     "scripts/validate-slides.js",
     "skills/",
     "src/",
@@ -51,7 +52,7 @@
     "build-viewer": "node scripts/build-viewer.js",
     "validate": "node scripts/validate-slides.js",
     "convert": "node convert.cjs",
-    "test": "node --test tests/editor/editor-codex-edit.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/validation/validate-slides.test.js tests/skills/installable-skills.test.js",
+    "test": "node --test tests/editor/editor-codex-edit.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/skills/installable-skills.test.js",
     "test:e2e": "node --test tests/editor/editor-ui.e2e.test.js tests/editor/editor-concurrency.e2e.test.js"
   },
   "dependencies": {
@@ -60,7 +61,10 @@
     "pdf-lib": "^1.17.1",
     "playwright": "^1.40.0",
     "pptxgenjs": "^3.12.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "react-icons": "^5.0.0",
-    "sharp": "^0.33.0"
+    "sharp": "^0.33.0",
+    "tldraw": "^4.4.1"
   }
 }

package/scripts/editor-server.js

@@ -3,7 +3,6 @@
 import { readdir, readFile, writeFile, mkdtemp, rm, mkdir } from 'node:fs/promises';
 import { watch as fsWatch } from 'node:fs';
 import { basename, dirname, join, resolve, relative, sep } from 'node:path';
-import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { tmpdir } from 'node:os';
 
@@ -18,6 +17,10 @@ import {
   scaleSelectionToScreenshot,
   writeAnnotatedScreenshot,
 } from '../src/editor/codex-edit.js';
+import {
+  parseEditTimeoutMs,
+  runEditSubprocess,
+} from '../src/editor/edit-subprocess.js';
 import { buildSlideRuntimeHtml } from '../src/image-contract.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -45,6 +48,7 @@ const SLIDE_FILE_PATTERN = /^slide-.*\.html$/i;
 
 const MAX_RUNS = 200;
 const MAX_LOG_CHARS = 800_000;
+const EDIT_TIMEOUT_MS = parseEditTimeoutMs();
 
 function printUsage() {
   process.stdout.write(`Usage: slides-grab edit [options]\n\n`);
@@ -233,37 +237,24 @@ function randomRunId() {
   return `run-${ts}-${rand}`;
 }
 
+function mirrorRunLog(onLog) {
+  return (stream, chunk) => {
+    onLog(stream, chunk);
+    process[stream].write(chunk);
+  };
+}
+
 function spawnCodexEdit({ prompt, imagePath, model, cwd, onLog }) {
   const codexBin = process.env.PPT_AGENT_CODEX_BIN || 'codex';
   const args = buildCodexExecArgs({ prompt, imagePath, model });
-
-  return new Promise((resolvePromise, rejectPromise) => {
-    const child = spawn(codexBin, args, { cwd, stdio: 'pipe' });
-
-    let stdout = '';
-    let stderr = '';
-
-    child.stdout.on('data', (chunk) => {
-      const text = chunk.toString();
-      stdout += text;
-      onLog('stdout', text);
-      process.stdout.write(text);
-    });
-
-    child.stderr.on('data', (chunk) => {
-      const text = chunk.toString();
-      stderr += text;
-      onLog('stderr', text);
-      process.stderr.write(text);
-    });
-
-    child.on('close', (code) => {
-      resolvePromise({ code: code ?? 1, stdout, stderr });
-    });
-
-    child.on('error', (error) => {
-      rejectPromise(error);
-    });
+  return runEditSubprocess({
+    bin: codexBin,
+    args,
+    cwd,
+    stdio: 'pipe',
+    timeoutMs: EDIT_TIMEOUT_MS,
+    engineLabel: 'Codex',
+    onLog: mirrorRunLog(onLog),
   });
 }
 
@@ -275,37 +266,15 @@ function spawnClaudeEdit({ prompt, imagePath, model, cwd, onLog }) {
   const env = { ...process.env };
   delete env.CLAUDECODE;
 
-  return new Promise((resolvePromise, rejectPromise) => {
-    const child = spawn(claudeBin, args, {
-      cwd,
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env,
-    });
-
-    let stdout = '';
-    let stderr = '';
-
-    child.stdout.on('data', (chunk) => {
-      const text = chunk.toString();
-      stdout += text;
-      onLog('stdout', text);
-      process.stdout.write(text);
-    });
-
-    child.stderr.on('data', (chunk) => {
-      const text = chunk.toString();
-      stderr += text;
-      onLog('stderr', text);
-      process.stderr.write(text);
-    });
-
-    child.on('close', (code) => {
-      resolvePromise({ code: code ?? 1, stdout, stderr });
-    });
-
-    child.on('error', (error) => {
-      rejectPromise(error);
-    });
+  return runEditSubprocess({
+    bin: claudeBin,
+    args,
+    cwd,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeoutMs: EDIT_TIMEOUT_MS,
+    engineLabel: 'Claude',
+    onLog: mirrorRunLog(onLog),
   });
 }
 
@@ -674,7 +643,7 @@ async function startServer(opts) {
       const success = result.code === 0;
       const message = success
         ? `${engineLabel} edit completed.`
-        : `${engineLabel} exited with code ${result.code}.`;
+        : (result.timeoutMessage || `${engineLabel} exited with code ${result.code}.`);
 
       runStore.finishRun(runId, {
         status: success ? 'success' : 'failed',

package/scripts/render-tldraw.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  buildFixedSizeSvg,
+  buildTldrawImportUrl,
+  DEFAULT_TLDRAW_HEIGHT,
+  DEFAULT_TLDRAW_OUTPUT,
+  DEFAULT_TLDRAW_PADDING,
+  DEFAULT_TLDRAW_WIDTH,
+  getTldrawUsage,
+  loadTldrawInput,
+  main,
+  normalizeTldrawSnapshot,
+  parseTldrawCliArgs,
+  renderTldrawFile,
+  renderTldrawSnapshot,
+} from '../src/tldraw/render.js';
+
+export {
+  buildFixedSizeSvg,
+  buildTldrawImportUrl,
+  DEFAULT_TLDRAW_HEIGHT,
+  DEFAULT_TLDRAW_OUTPUT,
+  DEFAULT_TLDRAW_PADDING,
+  DEFAULT_TLDRAW_WIDTH,
+  getTldrawUsage,
+  loadTldrawInput,
+  normalizeTldrawSnapshot,
+  parseTldrawCliArgs,
+  renderTldrawFile,
+  renderTldrawSnapshot,
+};
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main().catch((error) => {
+    console.error(`[slides-grab] ${error.message}`);
+    process.exit(1);
+  });
+}

package/skills/slides-grab/SKILL.md

@@ -33,9 +33,10 @@ Use the installed **slides-grab-design** skill.
 3. Run validation: `slides-grab validate --slides-dir <path>`
 4. If validation fails, automatically fix the slide HTML/CSS until validation passes.
 5. Build the viewer: `slides-grab build-viewer --slides-dir <path>`
-6. Present viewer to user for review.
-7. Revise individual slides based on feedback, then re-run validation and rebuild the viewer.
-8. Optionally launch the visual editor: `slides-grab edit --slides-dir <path>`
+6. For complex diagrams (architecture, workflows, relationship maps, multi-node concepts), prefer `tldraw` over hand-built HTML/CSS diagrams. Render the asset with `slides-grab tldraw`, store it under `<slides-dir>/assets/`, and place it in the slide with a normal `<img>`.
+7. Present viewer to user for review.
+8. Revise individual slides based on feedback, then re-run validation and rebuild the viewer.
+9. Optionally launch the visual editor: `slides-grab edit --slides-dir <path>`
 
 **Do not proceed to Stage 3 without approval.**
 
@@ -58,6 +59,7 @@ Use the installed **slides-grab-export** skill.
 4. **Use `decks/<deck-name>/`** as the slides workspace for multi-deck projects.
 5. **Call out export risk clearly**: PPTX and Figma export are experimental / unstable and must be described as best-effort output.
 6. Use the stage skills as the source of truth for plan, design, and export rules.
+7. When a slide needs a complex diagram, default to a `tldraw`-generated asset unless the user explicitly asks for a different approach.
 
 ## Reference
 - `references/presentation-workflow-reference.md` — archived end-to-end workflow guidance from the legacy skill set

package/skills/slides-grab/references/presentation-workflow-reference.md

@@ -26,9 +26,10 @@ Use **design-skill** (`.claude/skills/design-skill/SKILL.md`).
 3. Run validation: `slides-grab validate --slides-dir <path>`
 4. If validation fails, automatically fix the slide HTML/CSS until validation passes.
 5. Build the viewer: `node scripts/build-viewer.js --slides-dir <path>`
-6. Present viewer to user for review.
-7. Revise individual slides based on feedback, then re-run validation and rebuild the viewer.
-8. Optionally launch the visual editor: `slides-grab edit --slides-dir <path>`
+6. For complex diagrams (architecture, workflows, relationship maps, multi-node concepts), prefer `tldraw`. Render a local diagram asset with `slides-grab tldraw`, store it under `<slides-dir>/assets/`, and place it into the slide with a normal `<img>`.
+7. Present viewer to user for review.
+8. Revise individual slides based on feedback, then re-run validation and rebuild the viewer.
+9. Optionally launch the visual editor: `slides-grab edit --slides-dir <path>`
 
 **Do not proceed to Stage 3 without approval.**
 
@@ -50,3 +51,4 @@ Use **pptx-skill** (`.claude/skills/pptx-skill/SKILL.md`).
 3. **Read each stage's SKILL.md** for detailed rules — this skill only orchestrates.
 4. **Use `decks/<deck-name>/`** as the slides workspace for multi-deck projects.
 5. **Call out export risk clearly**: PPTX and Figma export are experimental / unstable and should be described as best-effort output.
+6. **Prefer tldraw for complex diagrams**: Use `slides-grab tldraw` for diagram-heavy slides unless the user explicitly wants another rendering path.

package/skills/slides-grab-design/SKILL.md

@@ -23,20 +23,29 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 
 ## Workflow
 1. Read approved `slide-outline.md`.
-2. Generate slide HTML files with 2-digit numbering in selected `--slides-dir`.
-3. Run `slides-grab validate --slides-dir <path>` after generation or edits.
-4. If validation fails, automatically fix the source slide HTML/CSS and re-run validation until it passes.
-5. Run `slides-grab build-viewer --slides-dir <path>` only after validation passes.
-6. Iterate on user feedback by editing only requested slide files, then re-run validation and rebuild the viewer.
-7. Keep revising until user approves conversion stage.
+2. Before generating slides, write a quick **visual thesis** (mood/material/energy), a **content plan** (opener → support/proof → detail/story → close/CTA), and the core design tokens (background, surface, text, muted, accent + display/headline/body/caption roles).
+3. Generate slide HTML files with 2-digit numbering in selected `--slides-dir`.
+4. If the deck needs a complex diagram (architecture, workflows, relationship maps, multi-node concepts), create the diagram in `tldraw`, export it with `slides-grab tldraw`, and treat the result as a local slide asset under `<slides-dir>/assets/`.
+5. Run `slides-grab validate --slides-dir <path>` after generation or edits.
+6. If validation fails, automatically fix the source slide HTML/CSS and re-run validation until it passes.
+7. Run `slides-grab build-viewer --slides-dir <path>` only after validation passes.
+8. Run the slide litmus check from `references/beautiful-slide-defaults.md` before presenting the deck for review.
+9. Iterate on user feedback by editing only requested slide files, then re-run validation and rebuild the viewer.
+10. Keep revising until user approves conversion stage.
 
 ## Rules
 - Keep slide size 720pt x 405pt.
 - Keep semantic text tags (`p`, `h1-h6`, `ul`, `ol`, `li`).
 - Put local images under `<slides-dir>/assets/` and reference them as `./assets/<file>`.
 - Allow `data:` URLs when the slide must be fully self-contained.
-- Treat remote `https://` images as best-effort only, and never use absolute filesystem paths.
+- Do not leave remote `http(s)://` image URLs in saved slide HTML; download source images into `<slides-dir>/assets/` and reference them as `./assets/<file>`.
 - Prefer `<img>` for slide imagery and `data-image-placeholder` when no final asset exists.
+- Default to one job per slide, one dominant visual anchor, and copy that scans in seconds.
+- Treat opening slides and section dividers like posters, not dashboards.
+- Default to cardless layouts; only add a card when it improves structure or comprehension.
+- Use whitespace, alignment, scale, cropping, and contrast before adding decorative chrome.
+- Prefer `tldraw` for complex diagrams instead of recreating dense node/edge diagrams directly in HTML/CSS.
+- Use `slides-grab tldraw` plus `templates/diagram-tldraw.html` when that gives a cleaner, more export-friendly result.
 - Do not present slides for review until `slides-grab validate --slides-dir <path>` passes.
 - Do not start conversion before approval.
 - Use the packaged CLI and bundled references only; do not depend on unpublished agent-specific files.
@@ -45,4 +54,5 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 For full constraints and style system, follow:
 - `references/design-rules.md`
 - `references/detailed-design-rules.md`
+- `references/beautiful-slide-defaults.md` — slide-specific art direction defaults adapted from OpenAI's frontend design guidance
 - `references/design-system-full.md` — archived full design system, templates, and advanced pattern guidance

package/skills/slides-grab-design/references/beautiful-slide-defaults.md

@@ -0,0 +1,45 @@
+# Beautiful Slide Defaults
+
+Slide-specific art direction guidance adapted from OpenAI's frontend design guidance for GPT-5.4. Use it to make HTML slides feel deliberate, premium, and instantly scannable without breaking `slides-grab`'s export constraints.
+
+## Working Model
+
+Before building the deck, write two things:
+
+- **visual thesis** — one sentence describing the mood, material, energy, and imagery treatment
+- **content plan** — opener → support/proof → detail/story → close/CTA or decision
+
+If the style direction is still open, gather visual references or a mood board first. Define the core tokens early: `background`, `surface`, `primary text`, `muted text`, `accent`, plus typography roles for `display`, `headline`, `body`, and `caption`.
+
+## Beautiful Defaults for Slides
+
+- Start with composition, not components.
+- Treat the opening slide like a poster and make the title or brand the loudest text.
+- Give each slide one job, one primary takeaway, and one dominant visual anchor.
+- Keep copy short enough to scan in seconds.
+- Use whitespace, alignment, scale, cropping, and contrast before adding chrome.
+- Limit the system by default: two typefaces max and one accent color.
+- Default to cardless layouts. Prefer sections, grids, media blocks, dividers, and strong negative space.
+- Use real imagery, product views, diagrams, or data as the main visual idea. Decorative gradients and abstract filler do not count.
+- Keep the first slide free of secondary clutter such as stat strips, metadata piles, or multiple competing callouts unless the brief explicitly demands them.
+
+## Narrative Sequence for Decks
+
+Use a narrative rhythm that feels intentional:
+
+1. **Opener** — identity, premise, or promise
+2. **Support / proof** — key evidence, context, or concrete value
+3. **Detail / story** — workflow, mechanism, or deeper explanation
+4. **Close / CTA** — decision, recommendation, next step, or final message
+
+Section dividers should reset the visual tempo. Alternate dense proof slides with simpler image-led or statement-led slides so the deck keeps breathing.
+
+## Review Litmus
+
+Before showing the deck, ask:
+
+- Can the audience grasp the main point of each slide in 3–5 seconds?
+- Does each slide have one dominant idea instead of multiple competing blocks?
+- Is there one real visual anchor, not just decoration?
+- Would this still feel premium without shadows, cards, or extra chrome?
+- Can any line of copy, badge, or callout be removed without losing meaning?

package/skills/slides-grab-design/references/design-rules.md

@@ -6,6 +6,7 @@ These are the packaged design rules for installable `slides-grab` skills.
 - Validate slides: `slides-grab validate --slides-dir <path>`
 - Build review viewer: `slides-grab build-viewer --slides-dir <path>`
 - Launch editor: `slides-grab edit --slides-dir <path>`
+- Render `tldraw` diagrams: `slides-grab tldraw --input <path> --output <path>`
 
 ## Slide spec
 - Slide size: `720pt x 405pt` (16:9)
@@ -17,7 +18,10 @@ These are the packaged design rules for installable `slides-grab` skills.
 ## Asset rules
 - Store deck-local assets in `<slides-dir>/assets/`
 - Reference deck-local assets as `./assets/<file>`
+- If an image comes from the web, download it into `<slides-dir>/assets/` before referencing it
+- Use `tldraw`-generated local assets for complex diagrams when possible
 - Allow `data:` URLs only when the slide must be fully self-contained
+- Do not leave remote `http(s)://` image URLs in saved slide HTML
 - Never use absolute filesystem paths
 
 ## Package-published theme references
@@ -40,10 +44,12 @@ These are the packaged design rules for installable `slides-grab` skills.
 - `templates/closing.html`
 - `templates/chart.html`
 - `templates/diagram.html`
+- `templates/diagram-tldraw.html`
 - `templates/custom/`
 
 ## Review loop
 - Generate or edit only the needed slide files.
+- Prefer `tldraw` for complex diagrams instead of hand-building dense diagram geometry in HTML/CSS.
 - Re-run validation after every generation/edit pass.
 - Rebuild the viewer only after validation passes.
 - Do not move to export until the user approves the reviewed deck.

package/skills/slides-grab-design/references/design-system-full.md

@@ -282,6 +282,10 @@ grid-template-columns: 1fr 2.3fr;
 ### 12. Diagram Slide
 - Template file: `templates/diagram.html`
 
+### 13. Tldraw Diagram Slide
+- Template file: `templates/diagram-tldraw.html`
+- Use this when the slide needs a complex diagram that will be easier to author in `tldraw` and safer to export as a local image asset.
+
 ### Custom Templates
 - Custom template directory: `templates/custom/`
 - Users can add template files as drop-in for reuse.
@@ -457,11 +461,13 @@ Store the image at `<slides-dir>/assets/team-photo.png`.
 <img src="data:image/svg+xml;base64,..." alt="Illustration" style="width: 220pt; height: 140pt; object-fit: cover;">
 ```
 
-#### Remote URL (Best-Effort Only)
+#### Remote URL Source (Download Before Saving)
 ```html
 <img src="https://images.example.com/hero.png" alt="Hero image" style="width: 220pt; height: 140pt; object-fit: cover;">
 ```
 
+If the image source starts on the web, download it into `<slides-dir>/assets/` and change the saved slide HTML to `./assets/<file>`.
+
 #### Placeholder (Image Stand-In)
 ```html
 <div data-image-placeholder style="width: 220pt; height: 140pt; border: 1px dashed #c7c7c7; background: #f3f4f6; display: flex; align-items: center; justify-content: center;">
@@ -474,7 +480,7 @@ Rules:
 - Use `./assets/<file>` as the default image contract for slide HTML.
 - Keep slide assets in `<slides-dir>/assets/`.
 - `data:` URLs are allowed for fully self-contained slides.
-- Remote `https://` URLs are allowed but non-deterministic and should be treated as fallback only.
+- Do not leave remote `http(s)://` image URLs in saved slide HTML; download source images into `<slides-dir>/assets/` and reference them as `./assets/<file>`.
 - Do not use absolute filesystem paths in slide HTML.
 - Do not use non-body `background-image` for content imagery; use `<img>` instead.
 - Use `data-image-placeholder` to reserve space when no image is available yet.
@@ -536,28 +542,30 @@ This skill is **Stage 2**. It works from the `slide-outline.md` approved by the
 ### Steps
 
 1. **Analyze + Design**: Read `slide-outline.md`, decide theme/layout, generate HTML slides
-2. **Validate slides**: After slide generation or edits, automatically run:
+2. **Diagram choice**: If a slide needs a complex diagram (architecture, workflows, relationship maps, multi-node concepts), prefer `tldraw`. Export the diagram with `slides-grab tldraw` and reference the generated local asset from the slide HTML.
+3. **Validate slides**: After slide generation or edits, automatically run:
    ```bash
    slides-grab validate --slides-dir <path>
    ```
-3. **Auto-fix validation issues**: If validation fails, fix the source HTML/CSS and re-run validation until it passes
-4. **Auto-build viewer**: After validation passes, automatically run:
+4. **Auto-fix validation issues**: If validation fails, fix the source HTML/CSS and re-run validation until it passes
+5. **Auto-build viewer**: After validation passes, automatically run:
    ```bash
    node scripts/build-viewer.js --slides-dir <path>
    ```
-5. **Guide user to review**: Tell the user to check slides in the browser:
+6. **Guide user to review**: Tell the user to check slides in the browser:
    ```
    open <slides-dir>/viewer.html
    ```
-6. **Revision loop**: When the user requests changes to specific slides:
+7. **Revision loop**: When the user requests changes to specific slides:
    - Edit only the relevant HTML file
    - Re-run `slides-grab validate --slides-dir <path>` and fix any failures
    - Re-run `node scripts/build-viewer.js --slides-dir <path>` to rebuild the viewer
    - Guide user to review again
-7. **Completion**: Repeat the revision loop until the user signals approval for PPTX conversion
+8. **Completion**: Repeat the revision loop until the user signals approval for PPTX conversion
 
 ### Absolute Rules
 - **Never start PPTX conversion without approval** — PPTX conversion is the responsibility of `pptx-skill` and requires explicit user approval.
+- **Prefer tldraw for complex diagrams** — Use `slides-grab tldraw` when the slide needs a non-trivial diagram instead of forcing dense diagram geometry into HTML/CSS.
 - **Never skip validation** — Run `slides-grab validate --slides-dir <path>` after generation or edits and fix failures before review.
 - **Never forget to build the viewer** — Run `node scripts/build-viewer.js --slides-dir <path>` every time slides are generated or modified.
 
@@ -567,6 +575,6 @@ This skill is **Stage 2**. It works from the `slide-outline.md` approved by the
 
 1. **CSS gradients**: Not supported in PowerPoint conversion — replace with background images
 2. **Webfonts**: Always include the Pretendard CDN link
-3. **Image paths**: Use `./assets/<file>` from each `slide-XX.html`; avoid absolute filesystem paths
+3. **Image paths**: Use `./assets/<file>` from each `slide-XX.html`; avoid absolute filesystem paths and do not leave remote `http(s)://` image URLs in saved slide HTML
 4. **Colors**: Always include `#` prefix in CSS
 5. **Text rules**: Never place text directly in div/span

package/skills/slides-grab-design/references/detailed-design-rules.md

@@ -9,8 +9,9 @@
 - Always include alt on img tags.
 - Use `./assets/<file>` as the default image contract for slide HTML.
 - Keep slide assets in `<slides-dir>/assets/`.
+- Use `tldraw`-generated assets for complex diagrams whenever possible.
 - `data:` URLs are allowed for fully self-contained slides.
-- Remote `https://` URLs are allowed but non-deterministic and fallback only.
+- Do not leave remote `http(s)://` image URLs in saved slide HTML; download source images into `<slides-dir>/assets/` and reference them as `./assets/<file>`.
 - Do not use absolute filesystem paths in slide HTML.
 - Do not use non-body `background-image` for content imagery; use `<img>` instead.
 - Use `data-image-placeholder` to reserve space when no image is available yet.
@@ -23,6 +24,7 @@
 - After slide generation or edits, run `slides-grab validate --slides-dir <path>`.
 - After validation passes, run `slides-grab build-viewer --slides-dir <path>`.
 - Edit only the relevant HTML file during revision loops.
+- Prefer `slides-grab tldraw` + local exported assets for architecture, workflow, relationship, and other complex diagrams.
 - Never start PPTX conversion without explicit approval.
 - Never forget to build the viewer after slide changes.
 - Do not persist runtime-only editor/viewer injections in saved slide HTML.