slides-grab 1.1.4 → 1.1.6

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.4",
+  "version": "1.1.6",
   "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/html2pdf.js

@@ -403,7 +403,6 @@ export async function normalizeBodyToSlideFrame(page, slideFrame) {
     const documentElement = document.documentElement;
 
     body.style.margin = '0';
-    body.style.padding = '0';
     body.style.width = `${width}px`;
     body.style.height = `${height}px`;
     body.style.minWidth = `${width}px`;

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

@@ -24,11 +24,12 @@ 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.
+3. 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/`.
+4. Run `slides-grab validate --slides-dir <path>` after generation or edits.
+5. If validation fails, automatically fix the source slide HTML/CSS and re-run validation until it passes.
+6. Run `slides-grab build-viewer --slides-dir <path>` only after validation passes.
+7. Iterate on user feedback by editing only requested slide files, then re-run validation and rebuild the viewer.
+8. Keep revising until user approves conversion stage.
 
 ## Rules
 - Keep slide size 720pt x 405pt.
@@ -37,6 +38,8 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 - 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.
 - Prefer `<img>` for slide imagery and `data-image-placeholder` when no final asset exists.
+- 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.

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,6 +18,7 @@ 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>`
+- Use `tldraw`-generated local assets for complex diagrams when possible
 - Allow `data:` URLs only when the slide must be fully self-contained
 - Never use absolute filesystem paths
 
@@ -40,10 +42,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.
@@ -536,28 +540,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.
 

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

@@ -9,6 +9,7 @@
 - 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 use absolute filesystem paths in slide HTML.
@@ -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.

package/src/tldraw/render.js

@@ -0,0 +1,470 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { chromium } from 'playwright';
+
+const require = createRequire(import.meta.url);
+
+export const DEFAULT_TLDRAW_WIDTH = 960;
+export const DEFAULT_TLDRAW_HEIGHT = 540;
+export const DEFAULT_TLDRAW_PADDING = 24;
+export const DEFAULT_TLDRAW_OUTPUT = 'diagram.svg';
+
+function readOptionValue(args, index, optionName) {
+  const next = args[index + 1];
+  if (!next || next.startsWith('-')) {
+    throw new Error(`Missing value for ${optionName}.`);
+  }
+  return next;
+}
+
+function parsePositiveInteger(value, optionName) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${optionName} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+function parseNonNegativeInteger(value, optionName) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${optionName} must be zero or a positive integer.`);
+  }
+  return parsed;
+}
+
+function formatNumber(value) {
+  return Number.parseFloat(Number(value).toFixed(4)).toString();
+}
+
+function escapeAttribute(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+function extractSvgMarkup(svg) {
+  const match = String(svg).match(/<svg\b[^>]*>([\s\S]*?)<\/svg>\s*$/i);
+  if (!match) {
+    throw new Error('Rendered tldraw output did not contain a root <svg> element.');
+  }
+  return match[1];
+}
+
+function findPackageJsonPath(moduleName) {
+  const resolvedEntry = require.resolve(moduleName);
+  let currentDir = dirname(resolvedEntry);
+
+  while (true) {
+    const packageJsonPath = join(currentDir, 'package.json');
+    if (existsSync(packageJsonPath)) {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+      if (packageJson.name === moduleName) {
+        return packageJsonPath;
+      }
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+
+  throw new Error(`Unable to locate package.json for ${moduleName}.`);
+}
+
+function getInstalledPackageVersion(moduleName) {
+  const packageJsonPath = findPackageJsonPath(moduleName);
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+  if (!packageJson.version) {
+    throw new Error(`Package ${moduleName} does not declare a version.`);
+  }
+  return packageJson.version;
+}
+
+function isLegacyTldrawPayload(payload) {
+  return Boolean(payload && typeof payload === 'object' && payload.document && payload.document.version);
+}
+
+export function buildTldrawImportUrl() {
+  const tldrawVersion = getInstalledPackageVersion('tldraw');
+  const reactVersion = getInstalledPackageVersion('react');
+  const reactDomVersion = getInstalledPackageVersion('react-dom');
+
+  return `https://esm.sh/tldraw@${encodeURIComponent(tldrawVersion)}?deps=react@${encodeURIComponent(reactVersion)},react-dom@${encodeURIComponent(reactDomVersion)}`;
+}
+
+export function parseTldrawCliArgs(args = []) {
+  const options = {
+    input: '',
+    output: DEFAULT_TLDRAW_OUTPUT,
+    width: DEFAULT_TLDRAW_WIDTH,
+    height: DEFAULT_TLDRAW_HEIGHT,
+    padding: DEFAULT_TLDRAW_PADDING,
+    background: 'transparent',
+    pageId: '',
+    help: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--input') {
+      options.input = readOptionValue(args, index, '--input');
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--input=')) {
+      options.input = arg.slice('--input='.length);
+      continue;
+    }
+
+    if (arg === '--output') {
+      options.output = readOptionValue(args, index, '--output');
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--output=')) {
+      options.output = arg.slice('--output='.length);
+      continue;
+    }
+
+    if (arg === '--width') {
+      options.width = parsePositiveInteger(readOptionValue(args, index, '--width'), '--width');
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--width=')) {
+      options.width = parsePositiveInteger(arg.slice('--width='.length), '--width');
+      continue;
+    }
+
+    if (arg === '--height') {
+      options.height = parsePositiveInteger(readOptionValue(args, index, '--height'), '--height');
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--height=')) {
+      options.height = parsePositiveInteger(arg.slice('--height='.length), '--height');
+      continue;
+    }
+
+    if (arg === '--padding') {
+      options.padding = parseNonNegativeInteger(readOptionValue(args, index, '--padding'), '--padding');
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--padding=')) {
+      options.padding = parseNonNegativeInteger(arg.slice('--padding='.length), '--padding');
+      continue;
+    }
+
+    if (arg === '--background') {
+      options.background = readOptionValue(args, index, '--background').trim() || 'transparent';
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--background=')) {
+      options.background = arg.slice('--background='.length).trim() || 'transparent';
+      continue;
+    }
+
+    if (arg === '--page-id') {
+      options.pageId = readOptionValue(args, index, '--page-id').trim();
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--page-id=')) {
+      options.pageId = arg.slice('--page-id='.length).trim();
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (!options.help && (!options.input || !options.input.trim())) {
+    throw new Error('--input must be a non-empty string.');
+  }
+
+  options.input = options.input.trim();
+  options.output = String(options.output).trim();
+  options.background = options.background || 'transparent';
+
+  if (!options.help && !options.output) {
+    throw new Error('--output must be a non-empty string.');
+  }
+
+  return options;
+}
+
+export function getTldrawUsage() {
+  return [
+    'Usage: node scripts/render-tldraw.js [options]',
+    '',
+    'Options:',
+    '  --input <path>       Input current-format .tldr or store-snapshot JSON file',
+    `  --output <path>      Output SVG asset path (default: ${DEFAULT_TLDRAW_OUTPUT})`,
+    `  --width <px>         Exact output width in CSS pixels (default: ${DEFAULT_TLDRAW_WIDTH})`,
+    `  --height <px>        Exact output height in CSS pixels (default: ${DEFAULT_TLDRAW_HEIGHT})`,
+    `  --padding <px>       Inner fit padding in CSS pixels (default: ${DEFAULT_TLDRAW_PADDING})`,
+    '  --background <css>   Optional wrapper background fill (default: transparent)',
+    '  --page-id <id>       Optional tldraw page id to export',
+    '  -h, --help           Show this help message',
+    '',
+    'Notes:',
+    '  - Legacy pre-records .tldr files are not supported. Open and resave them in a current tldraw build first.',
+    '',
+    'Examples:',
+    '  node scripts/render-tldraw.js --input slides/assets/diagram.tldr --output slides/assets/diagram.svg',
+    '  node scripts/render-tldraw.js --input deck/assets/system.json --output deck/assets/system.svg --width 640 --height 320',
+  ].join('\n');
+}
+
+export function normalizeTldrawSnapshot(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('Expected the tldraw input file to contain a JSON object.');
+  }
+
+  if (isLegacyTldrawPayload(payload)) {
+    throw new Error('Legacy pre-records .tldr files are not supported yet. Open the diagram in a current tldraw build and save it again before exporting.');
+  }
+
+  if (payload.store && payload.schema) {
+    return payload;
+  }
+
+  if (Array.isArray(payload.records) && payload.schema) {
+    const store = Object.fromEntries(
+      payload.records.map((record) => {
+        if (!record || typeof record !== 'object' || typeof record.id !== 'string') {
+          throw new Error('Each tldraw record must be an object with a string id.');
+        }
+        return [record.id, record];
+      }),
+    );
+
+    return {
+      store,
+      schema: payload.schema,
+    };
+  }
+
+  throw new Error('Input JSON must contain either { store, schema } or a current-format { records, schema } tldraw file.');
+}
+
+export function buildFixedSizeSvg(
+  { svg, width, height },
+  {
+    targetWidth = DEFAULT_TLDRAW_WIDTH,
+    targetHeight = DEFAULT_TLDRAW_HEIGHT,
+    padding = DEFAULT_TLDRAW_PADDING,
+    background = 'transparent',
+  } = {},
+) {
+  const sourceWidth = Number(width);
+  const sourceHeight = Number(height);
+
+  if (!Number.isFinite(sourceWidth) || sourceWidth <= 0 || !Number.isFinite(sourceHeight) || sourceHeight <= 0) {
+    throw new Error('Rendered tldraw output must include positive width and height values.');
+  }
+
+  const safePadding = Math.max(0, padding);
+  const availableWidth = Math.max(1, targetWidth - safePadding * 2);
+  const availableHeight = Math.max(1, targetHeight - safePadding * 2);
+  const scale = Math.min(availableWidth / sourceWidth, availableHeight / sourceHeight);
+  const fittedWidth = sourceWidth * scale;
+  const fittedHeight = sourceHeight * scale;
+  const offsetX = (targetWidth - fittedWidth) / 2;
+  const offsetY = (targetHeight - fittedHeight) / 2;
+  const markup = extractSvgMarkup(svg);
+  const backgroundMarkup = background && background !== 'transparent'
+    ? `\n  <rect x="0" y="0" width="${targetWidth}" height="${targetHeight}" fill="${escapeAttribute(background)}" />`
+    : '';
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${targetWidth}" height="${targetHeight}" viewBox="0 0 ${targetWidth} ${targetHeight}" role="img" aria-label="tldraw diagram export">`,
+    backgroundMarkup,
+    `  <g transform="translate(${formatNumber(offsetX)} ${formatNumber(offsetY)}) scale(${formatNumber(scale)})">`,
+    markup
+      .split('\n')
+      .map((line) => `    ${line}`)
+      .join('\n'),
+    '  </g>',
+    '</svg>',
+    '',
+  ].join('\n');
+}
+
+export async function loadTldrawInput(inputPath) {
+  const raw = await readFile(inputPath, 'utf8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Unable to parse tldraw JSON from ${inputPath}: ${error.message}`);
+  }
+  return normalizeTldrawSnapshot(parsed);
+}
+
+export async function renderTldrawSnapshot(snapshot, { pageId = '' } = {}) {
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage({ viewport: { width: DEFAULT_TLDRAW_WIDTH, height: DEFAULT_TLDRAW_HEIGHT } });
+
+  try {
+    await page.setContent('<!DOCTYPE html><html><head><meta charset="utf-8"></head><body></body></html>', {
+      waitUntil: 'load',
+    });
+
+    const moduleUrl = buildTldrawImportUrl();
+
+    await page.evaluate(
+      async ({ snapshot: browserSnapshot, requestedPageId, browserModuleUrl }) => {
+        window.__TLDRAW_RENDER_RESULT__ = null;
+        window.__TLDRAW_RENDER_ERROR__ = null;
+
+        try {
+          const {
+            Editor,
+            createTLStore,
+            defaultAddFontsFromNode,
+            defaultBindingUtils,
+            defaultShapeUtils,
+            tipTapDefaultExtensions,
+          } = await import(browserModuleUrl);
+          const container = document.createElement('div');
+          container.style.position = 'fixed';
+          container.style.inset = '0';
+          container.classList.add('tl-container', 'tl-theme__light');
+          document.body.appendChild(container);
+
+          const tempElm = document.createElement('div');
+          container.appendChild(tempElm);
+
+          const store = createTLStore({
+            snapshot: browserSnapshot,
+            shapeUtils: defaultShapeUtils,
+          });
+
+          const editor = new Editor({
+            store,
+            shapeUtils: defaultShapeUtils,
+            bindingUtils: defaultBindingUtils,
+            tools: [],
+            getContainer: () => tempElm,
+            options: {
+              text: {
+                tipTapConfig: {
+                  extensions: tipTapDefaultExtensions,
+                },
+                addFontsFromNode: defaultAddFontsFromNode,
+              },
+            },
+          });
+
+          if (requestedPageId) {
+            editor.setCurrentPage(requestedPageId);
+          }
+
+          await editor.fonts.loadRequiredFontsForCurrentPage(editor.options.maxFontsToLoadBeforeRender);
+          await new Promise((resolveAnimation) => requestAnimationFrame(() => requestAnimationFrame(resolveAnimation)));
+
+          const shapeIds = Array.from(editor.getCurrentPageShapeIds());
+          if (shapeIds.length === 0) {
+            throw new Error('The selected tldraw page does not contain any shapes to export.');
+          }
+
+          const result = await editor.getSvgString(shapeIds, {
+            background: false,
+            padding: 0,
+          });
+
+          editor.dispose();
+
+          if (!result) {
+            throw new Error('tldraw did not return an SVG export.');
+          }
+
+          window.__TLDRAW_RENDER_RESULT__ = result;
+        } catch (error) {
+          window.__TLDRAW_RENDER_ERROR__ = error instanceof Error ? error.message : String(error);
+        }
+      },
+      {
+        snapshot,
+        requestedPageId: pageId,
+        browserModuleUrl: moduleUrl,
+      },
+    );
+
+    await page.waitForFunction(
+      () => window.__TLDRAW_RENDER_RESULT__ !== null || window.__TLDRAW_RENDER_ERROR__ !== null,
+      null,
+      { timeout: 30000 },
+    );
+
+    const errorMessage = await page.evaluate(() => window.__TLDRAW_RENDER_ERROR__);
+    if (errorMessage) {
+      throw new Error(errorMessage);
+    }
+
+    const result = await page.evaluate(() => window.__TLDRAW_RENDER_RESULT__);
+    if (!result) {
+      throw new Error('tldraw render completed without producing an SVG export.');
+    }
+
+    return result;
+  } finally {
+    await browser.close();
+  }
+}
+
+export async function renderTldrawFile(inputPath, outputPath, options = {}) {
+  const snapshot = await loadTldrawInput(inputPath);
+  const rendered = await renderTldrawSnapshot(snapshot, { pageId: options.pageId });
+  const fittedSvg = buildFixedSizeSvg(rendered, {
+    targetWidth: options.width,
+    targetHeight: options.height,
+    padding: options.padding,
+    background: options.background,
+  });
+
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, fittedSvg, 'utf8');
+  return {
+    inputPath,
+    outputPath,
+    width: options.width,
+    height: options.height,
+  };
+}
+
+export async function main(args = process.argv.slice(2)) {
+  const options = parseTldrawCliArgs(args);
+  if (options.help) {
+    process.stdout.write(`${getTldrawUsage()}\n`);
+    return;
+  }
+
+  const inputPath = resolve(process.cwd(), options.input);
+  const outputPath = resolve(process.cwd(), options.output);
+  const result = await renderTldrawFile(inputPath, outputPath, options);
+  process.stdout.write(`Generated tldraw SVG: ${result.outputPath} (${result.width}x${result.height})\n`);
+}

package/templates/diagram-tldraw.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #ffffff;
+      color: #111827;
+      padding: 34pt 40pt 28pt;
+      display: flex;
+      flex-direction: column;
+      gap: 12pt;
+    }
+    .diagram-frame {
+      flex: 1;
+      min-height: 0;
+      border: 1pt solid #e5e7eb;
+      border-radius: 14pt;
+      background: #f8fafc;
+      padding: 12pt;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      overflow: hidden;
+    }
+    .diagram-frame img {
+      display: block;
+      width: 100%;
+      height: 100%;
+      object-fit: contain;
+    }
+  </style>
+</head>
+<body>
+  <div style="display: flex; justify-content: space-between; align-items: baseline;">
+    <h2 style="font-size: 28pt; font-weight: 700; letter-spacing: -0.01em;">System Diagram</h2>
+    <p style="font-size: 10pt; color: #6b7280;">DIAGRAM / TLDRAW</p>
+  </div>
+
+  <p style="font-size: 12pt; color: #4b5563;">
+    Render a current-format local .tldr file with slides-grab tldraw, then reference the generated SVG asset below.
+  </p>
+
+  <div class="diagram-frame">
+    <img src="./assets/diagram.svg" alt="System architecture diagram" />
+  </div>
+
+  <p style="font-size: 9pt; color: #9ca3af;">
+    Example asset path: ./assets/diagram.svg
+  </p>
+</body>
+</html>