openfig-cli 0.3.11

package/LICENSE

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

package/README.md

@@ -0,0 +1,95 @@
+<img src="assets/logo.webp" alt="OpenFig" width="320" />
+
+Open tools for Figma files.
+
+Parse, inspect, and render `.deck` and `.fig` files without the Figma application — including PNG export.
+
+OpenFig is an open-source implementation of the Figma file format that allows developers to inspect, parse, and render Figma files without using the Figma application or API. The primary use case is Figma Slides (`.deck`), with `.fig` design file support also available.
+
+## Figma File Formats
+
+Each Figma product has its own native file format. Active development — status may change:
+
+| Product | Extension | Status |
+|---------|-----------|--------|
+| Figma Slides | `.deck` | ✅ |
+| Figma Design | `.fig` | ✅ read + PNG render |
+| Figma Jam (whiteboard) | `.jam` | ❌ not yet |
+| Figma Buzz | `.buzz` | ❌ not yet |
+| Figma Sites | `.site` | ❌ not yet |
+| Figma Make | `.make` | ❌ not yet |
+
+## Render Quality
+
+OpenFig achieves **≥99% SSIM** (Structural Similarity Index) against Figma reference exports across all test cases. Render fidelity is verified with visual regression tests against real Figma-exported PNGs.
+
+| Test suite | Visual results |
+|------------|----------------|
+| `.deck` slides | [render-report-deck.html](https://rcoenen.github.io/OpenFig/test/rasterizer/reports/openfig-render-report-deck.html) |
+| `.fig` design frames | [render-report-fig.html](https://rcoenen.github.io/OpenFig/test/rasterizer/reports/openfig-render-report-fig.html) |
+
+## Why native `.deck`?
+
+Figma Slides lets you download presentations as `.deck` files and re-upload them. This is the **native** round-trip format. Exporting to `.pptx` is lossy — vectors get rasterized, fonts fall back to system defaults, layout breaks. By staying in `.deck`, you preserve everything exactly as Figma renders it.
+
+OpenFig makes this round-trip programmable. Download a `.deck`, modify it, re-upload. Everything stays native.
+
+Plug in Claude Cowork or any coding agent and you have an AI that can read and edit Figma presentations end-to-end — without ever opening the Figma UI.
+
+## Use Cases
+
+- **AI agent for presentations** — let an LLM rewrite copy, insert images, and produce a ready-to-upload `.deck`
+- **Batch-produce branded decks** — start from a template, feed in data per client/project, get pixel-perfect slides out
+- **Inspect and audit** — understand the internal structure of any `.deck` file
+- **Automate** text and image placement across dozens of slides in seconds
+
+## Install
+
+```bash
+npm install -g openfig
+```
+
+Node 18+. No build step. Pure ESM.
+
+## Quick Start
+
+```bash
+openfig inspect my-presentation.deck        # node hierarchy
+openfig list-text my-presentation.deck      # all text + images per slide
+openfig list-overrides my-presentation.deck # editable fields per symbol
+```
+
+> Full CLI reference: [docs/cli.md](docs/cli.md)
+
+## Claude Cowork / MCP Integration
+
+> Install guide, MCP workflows, and template states: [docs/agentic/claude-cowork.md](docs/agentic/claude-cowork.md)
+
+## Programmatic API
+
+```javascript
+import { Deck } from 'openfig';
+
+const deck = await Deck.open('template.deck');
+const slide = deck.slides[0];
+slide.addText('Hello world', { style: 'Title' });
+await deck.save('output.deck');
+```
+
+| Docs | |
+|------|---|
+| MCP / Claude workflows | [docs/mcp.md](docs/mcp.md) |
+| High-level API | [docs/api-spec.md](docs/api-spec.md) |
+| Low-level FigDeck API | [docs/library.md](docs/library.md) |
+| Template workflows | [docs/template-workflows.md](docs/template-workflows.md) |
+| File format internals | [docs/format/](docs/format/) |
+
+## License
+
+MIT
+
+## Disclaimer
+
+Figma is a trademark of Figma, Inc.
+
+OpenFig is an independent open-source project and is not affiliated with, endorsed by, or sponsored by Figma, Inc.

package/bin/cli.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * OpenFig — Open-source tools for Figma .deck / .fig files.
+ *
+ * Usage: openfig <command> [args...]
+ *
+ * Commands:
+ *   inspect        Show document structure (node hierarchy tree)
+ *   list-text      List all text content in the deck
+ *   list-overrides List all editable override keys per symbol
+ *   update-text    Apply text overrides to a slide instance
+ *   insert-image   Apply an image fill override to a slide instance
+ *   clone-slide    Duplicate a template slide with new content
+ *   remove-slide   Mark slides as REMOVED
+ *   roundtrip      Decode and re-encode (pipeline validation)
+ *
+ * Disclaimer:
+ *   Figma is a trademark of Figma, Inc.
+ *   OpenFig is an independent open-source project and is not affiliated with,
+ *   endorsed by, or sponsored by Figma, Inc.
+ */
+
+const COMMANDS = {
+  'inspect':        './commands/inspect.mjs',
+  'list-text':      './commands/list-text.mjs',
+  'list-overrides': './commands/list-overrides.mjs',
+  'update-text':    './commands/update-text.mjs',
+  'insert-image':   './commands/insert-image.mjs',
+  'clone-slide':    './commands/clone-slide.mjs',
+  'remove-slide':   './commands/remove-slide.mjs',
+  'roundtrip':      './commands/roundtrip.mjs',
+  'export':         './commands/export.mjs',
+};
+
+const arg2 = process.argv[2];
+let command, rawArgs;
+
+if (!arg2 || arg2 === '--help' || arg2 === '-h') {
+  console.log(`OpenFig — Open-source tools for Figma .deck / .fig files\n`);
+  console.log('Usage: openfig <command> [args...]\n');
+  console.log('Commands:');
+  console.log('  export         Export slides as images (PNG/JPG/WEBP)');
+  console.log('  inspect        Show document structure (node hierarchy tree)');
+  console.log('  list-text      List all text content in the deck');
+  console.log('  list-overrides List editable override keys per symbol');
+  console.log('  update-text    Apply text overrides to a slide instance');
+  console.log('  insert-image   Apply image fill override to a slide instance');
+  console.log('  clone-slide    Duplicate a template slide with new content');
+  console.log('  remove-slide   Mark slides as REMOVED');
+  console.log('  roundtrip      Decode and re-encode (pipeline validation)');
+  process.exit(0);
+}
+
+if (COMMANDS[arg2]) {
+  command = arg2;
+  rawArgs = process.argv.slice(3);
+} else {
+  console.error(`Unknown command: ${arg2}\nRun with --help for available commands.`);
+  process.exit(1);
+}
+
+// Parse args: positional args + flags (--flag value, --flag=value)
+const positional = [];
+const flags = {};
+
+for (let i = 0; i < rawArgs.length; i++) {
+  const arg = rawArgs[i];
+  if (arg.startsWith('--')) {
+    const eqIdx = arg.indexOf('=');
+    let key, value;
+    if (eqIdx >= 0) {
+      key = arg.substring(2, eqIdx);
+      value = arg.substring(eqIdx + 1);
+    } else {
+      key = arg.substring(2);
+      // Peek ahead for value (unless next arg is also a flag)
+      if (i + 1 < rawArgs.length && !rawArgs[i + 1].startsWith('--')) {
+        value = rawArgs[++i];
+      } else {
+        value = true;
+      }
+    }
+    // Support repeating flags (e.g. --set k=v --set k2=v2)
+    if (flags[key] !== undefined) {
+      if (!Array.isArray(flags[key])) flags[key] = [flags[key]];
+      flags[key].push(value);
+    } else {
+      flags[key] = value;
+    }
+  } else if (arg.startsWith('-') && arg.length === 2) {
+    // Short flag like -o
+    const key = arg.substring(1);
+    if (i + 1 < rawArgs.length && !rawArgs[i + 1].startsWith('-')) {
+      flags[key] = rawArgs[++i];
+    } else {
+      flags[key] = true;
+    }
+  } else {
+    positional.push(arg);
+  }
+}
+
+// Run command
+const mod = await import(COMMANDS[command]);
+try {
+  await mod.run(positional, flags);
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  if (process.env.DEBUG) console.error(err.stack);
+  process.exit(1);
+}

package/bin/commands/clone-slide.mjs

@@ -0,0 +1,153 @@
+/**
+ * clone-slide — Duplicate a template slide with new content.
+ *
+ * Usage: node cli.mjs clone-slide <file.deck> -o <output.deck>
+ *        --template <slideId|name> --name <newName>
+ *        [--after <slideId>] [--set key=value ...] [--set-image key=path ...]
+ */
+import { FigDeck } from '../lib/core/fig-deck.mjs';
+import { nid, parseId, positionChar } from '../lib/core/node-helpers.mjs';
+import { imageOv } from '../lib/core/image-helpers.mjs';
+import { deepClone } from '../lib/core/deep-clone.mjs';
+import { readFileSync, copyFileSync, existsSync, mkdirSync } from 'fs';
+import { createHash } from 'crypto';
+import { join, resolve } from 'path';
+import { getImageDimensions, generateThumbnail } from '../lib/core/image-utils.mjs';
+
+function sha1Hex(buf) {
+  return createHash('sha1').update(buf).digest('hex');
+}
+
+export async function run(args, flags) {
+  const file = args[0];
+  const outPath = flags.o || flags.output;
+  const templateRef = flags.template;
+  const newName = flags.name || 'New Slide';
+  const sets = Array.isArray(flags.set) ? flags.set : (flags.set ? [flags.set] : []);
+  const setImages = Array.isArray(flags['set-image']) ? flags['set-image'] : (flags['set-image'] ? [flags['set-image']] : []);
+
+  if (!file || !outPath || !templateRef) {
+    console.error('Usage: clone-slide <file.deck> -o <out.deck> --template <id|name> --name <name> [--set key=val ...] [--set-image key=path ...]');
+    process.exit(1);
+  }
+
+  const deck = await FigDeck.fromDeckFile(file);
+
+  // Find template slide
+  const tmplSlide = findSlide(deck, templateRef);
+  if (!tmplSlide) { console.error(`Template slide not found: ${templateRef}`); process.exit(1); }
+
+  const tmplInst = deck.getSlideInstance(nid(tmplSlide));
+  if (!tmplInst) { console.error(`No instance on template slide`); process.exit(1); }
+
+  // Find SLIDE_ROW parent
+  const slideRowId = tmplSlide.parentIndex?.guid
+    ? `${tmplSlide.parentIndex.guid.sessionID}:${tmplSlide.parentIndex.guid.localID}`
+    : null;
+
+  // Generate new IDs
+  let nextId = deck.maxLocalID() + 1;
+  const slideId = nextId++;
+  const instId = nextId++;
+
+  // Clone slide node
+  const newSlide = deepClone(tmplSlide);
+  newSlide.guid = { sessionID: 1, localID: slideId };
+  newSlide.name = newName;
+  newSlide.phase = 'CREATED';
+  if (slideRowId) {
+    const activeCount = deck.getActiveSlides().length;
+    newSlide.parentIndex = {
+      guid: parseId(slideRowId),
+      position: positionChar(activeCount),
+    };
+  }
+  delete newSlide.prototypeInteractions;
+  delete newSlide.slideThumbnailHash;
+  delete newSlide.editInfo;
+
+  // Clone instance
+  const newInst = deepClone(tmplInst);
+  newInst.guid = { sessionID: 1, localID: instId };
+  newInst.name = newName;
+  newInst.phase = 'CREATED';
+  newInst.parentIndex = { guid: { sessionID: 1, localID: slideId }, position: '!' };
+  newInst.symbolData = {
+    symbolID: deepClone(tmplInst.symbolData?.symbolID),
+    symbolOverrides: [],
+    uniformScaleFactor: 1,
+  };
+  delete newInst.derivedSymbolData;
+  delete newInst.derivedSymbolDataLayoutVersion;
+  delete newInst.editInfo;
+
+  // Apply text overrides
+  for (const pair of sets) {
+    const eqIdx = pair.indexOf('=');
+    if (eqIdx < 0) continue;
+    const key = parseId(pair.substring(0, eqIdx));
+    let value = pair.substring(eqIdx + 1);
+    if (value === '') value = ' ';
+    newInst.symbolData.symbolOverrides.push({
+      guidPath: { guids: [key] },
+      textData: { characters: value },
+    });
+  }
+
+  // Apply image overrides
+  for (const pair of setImages) {
+    const eqIdx = pair.indexOf('=');
+    if (eqIdx < 0) continue;
+    const key = parseId(pair.substring(0, eqIdx));
+    const imgPath = resolve(pair.substring(eqIdx + 1));
+
+    const imgBuf = readFileSync(imgPath);
+    const imgHash = sha1Hex(imgBuf);
+    const { width: w, height: h } = await getImageDimensions(imgPath);
+
+    const tmpThumb = `/tmp/openfig_thumb_${Date.now()}.png`;
+    await generateThumbnail(imgPath, tmpThumb);
+    const thumbHash = sha1Hex(readFileSync(tmpThumb));
+
+    copyToImages(deck, imgHash, imgPath);
+    copyToImages(deck, thumbHash, tmpThumb);
+
+    newInst.symbolData.symbolOverrides.push(
+      imageOv(key, imgHash, thumbHash, w, h)
+    );
+  }
+
+  // Set slide position
+  const activeSlides = deck.getActiveSlides();
+  if (newSlide.transform) {
+    newSlide.transform.m02 = activeSlides.length * 2160;
+  }
+
+  // Push to nodeChanges
+  deck.message.nodeChanges.push(newSlide);
+  deck.message.nodeChanges.push(newInst);
+  deck.rebuildMaps();
+
+  console.log(`Cloned slide "${tmplSlide.name}" → "${newName}" (1:${slideId} + 1:${instId})`);
+  console.log(`  ${sets.length} text override(s), ${setImages.length} image override(s)`);
+
+  const bytes = await deck.saveDeck(outPath);
+  console.log(`Saved: ${outPath} (${bytes} bytes)`);
+}
+
+function copyToImages(deck, hash, srcPath) {
+  if (!deck.imagesDir) {
+    deck.imagesDir = `/tmp/openfig_images_${Date.now()}`;
+    mkdirSync(deck.imagesDir, { recursive: true });
+  }
+  const dest = join(deck.imagesDir, hash);
+  if (!existsSync(dest)) {
+    copyFileSync(srcPath, dest);
+  }
+}
+
+function findSlide(deck, ref) {
+  const byId = deck.getNode(ref);
+  if (byId?.type === 'SLIDE') return byId;
+  return deck.getSlides().find(s => s.name === ref);
+}

package/bin/commands/export.mjs

@@ -0,0 +1,83 @@
+/**
+ * export — Export slides from a .deck file to images.
+ *
+ * Usage:
+ *   openfig export <file.deck> [options]
+ *
+ * Options:
+ *   -o <dir>        Output directory (default: <deckname>/)
+ *   --slide <n>     Export only slide N (1-based). Omit to export all.
+ *   --scale <n>     Zoom factor: 1 = 1920×1080, 0.5 = 960×540 (default: 1)
+ *   --width <px>    Output width in pixels (height scales proportionally)
+ *   --format <fmt>  Output format: png, jpg, webp (default: png)
+ *   --fonts <dir>   Extra font directory to load (can repeat)
+ */
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { join, parse, resolve } from 'path';
+import { createInterface } from 'readline';
+import { FigDeck } from '../lib/core/fig-deck.mjs';
+import { renderDeck, registerFontDir } from '../lib/rasterizer/deck-rasterizer.mjs';
+import { resolveFonts } from '../lib/rasterizer/font-resolver.mjs';
+
+async function confirmOverwrite(dir) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    console.log(`Output directory "${dir}" already exists.`);
+    rl.question(`Delete and replace all contents? (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+export async function run(args, flags) {
+  const file = args[0];
+  if (!file) {
+    console.error('Usage: openfig export <file.deck> [options]\n');
+    console.error('Options:');
+    console.error('  -o <dir>        Output directory (default: <deckname>/)');
+    console.error('  --slide <n>     Export only slide N (1-based)');
+    console.error('  --scale <n>     Zoom factor: 1 = 1920×1080, 0.5 = 960×540 (default: 1)');
+    console.error('  --width <px>    Output width in pixels (height scales proportionally)');
+    console.error('  --format <fmt>  Output format: png, jpg, webp (default: png)');
+    console.error('  --fonts <dir>   Extra font directory to load');
+    process.exit(1);
+  }
+
+  const defaultOutDir = parse(file).name;
+  const outDir = resolve(flags.o ?? flags.output ?? defaultOutDir);
+
+  if (existsSync(outDir)) {
+    const confirmed = await confirmOverwrite(outDir);
+    if (!confirmed) {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+    rmSync(outDir, { recursive: true });
+  }
+
+  const renderOpts = {};
+  if (flags.width) renderOpts.width = parseInt(flags.width);
+  else if (flags.scale) renderOpts.scale = parseFloat(flags.scale);
+
+  const fontDirs = [].concat(flags.fonts ?? []);
+  for (const d of fontDirs) registerFontDir(resolve(d));
+
+  const deck = await FigDeck.fromDeckFile(file);
+  await resolveFonts(deck, { quiet: false });
+  mkdirSync(outDir, { recursive: true });
+
+  const slideFilter = flags.slide ? parseInt(flags.slide) : null;
+  const slides = await renderDeck(deck, renderOpts);
+
+  for (const { index, slideId, png } of slides) {
+    if (slideFilter && index + 1 !== slideFilter) continue;
+    const outFile = join(outDir, `slide_${String(index + 1).padStart(3, '0')}.png`);
+    writeFileSync(outFile, png);
+    console.log(`  slide ${index + 1}  →  ${outFile}`);
+  }
+
+  const count = slideFilter ? 1 : slides.length;
+  console.log(`\nExported ${count} slide(s) to ${outDir}`);
+}

package/bin/commands/insert-image.mjs

@@ -0,0 +1,90 @@
+/**
+ * insert-image — Apply an image fill override to a slide instance.
+ *
+ * Usage: node cli.mjs insert-image <file.deck> -o <output.deck> --slide <id|name> --key <overrideKey> --image <path.png> [--thumb <thumb.png>]
+ */
+import { FigDeck } from '../lib/core/fig-deck.mjs';
+import { nid, parseId } from '../lib/core/node-helpers.mjs';
+import { imageOv } from '../lib/core/image-helpers.mjs';
+import { readFileSync, copyFileSync, existsSync, mkdirSync } from 'fs';
+import { createHash } from 'crypto';
+import { join, resolve } from 'path';
+import { getImageDimensions, generateThumbnail } from '../lib/core/image-utils.mjs';
+
+function sha1Hex(buf) {
+  return createHash('sha1').update(buf).digest('hex');
+}
+
+export async function run(args, flags) {
+  const file = args[0];
+  const outPath = flags.o || flags.output;
+  const slideRef = flags.slide;
+  const keyStr = flags.key;
+  const imagePath = flags.image;
+  const thumbPath = flags.thumb || null;
+
+  if (!file || !outPath || !slideRef || !keyStr || !imagePath) {
+    console.error('Usage: insert-image <file.deck> -o <out.deck> --slide <id|name> --key <key> --image <path.png> [--thumb <thumb.png>]');
+    process.exit(1);
+  }
+
+  const deck = await FigDeck.fromDeckFile(file);
+
+  // Find slide
+  const slide = findSlide(deck, slideRef);
+  if (!slide) { console.error(`Slide not found: ${slideRef}`); process.exit(1); }
+
+  const inst = deck.getSlideInstance(nid(slide));
+  if (!inst) { console.error(`No instance on slide ${nid(slide)}`); process.exit(1); }
+
+  const imgBuf = readFileSync(resolve(imagePath));
+  const imgHash = sha1Hex(imgBuf);
+  const { width, height } = await getImageDimensions(resolve(imagePath));
+
+  let thumbHash;
+  if (thumbPath) {
+    const tBuf = readFileSync(resolve(thumbPath));
+    thumbHash = sha1Hex(tBuf);
+    copyToImages(deck, thumbHash, resolve(thumbPath));
+  } else {
+    const tmpThumb = `/tmp/openfig_thumb_${Date.now()}.png`;
+    await generateThumbnail(resolve(imagePath), tmpThumb);
+    thumbHash = sha1Hex(readFileSync(tmpThumb));
+    copyToImages(deck, thumbHash, tmpThumb);
+  }
+
+  // Copy full image to images dir
+  copyToImages(deck, imgHash, resolve(imagePath));
+
+  // Build and apply override
+  const key = parseId(keyStr);
+  const override = imageOv(key, imgHash, thumbHash, width, height);
+
+  if (!inst.symbolData) inst.symbolData = {};
+  if (!inst.symbolData.symbolOverrides) inst.symbolData.symbolOverrides = [];
+  inst.symbolData.symbolOverrides.push(override);
+
+  console.log(`Image: ${imgHash} (${width}×${height})`);
+  console.log(`Thumb: ${thumbHash}`);
+  console.log(`Applied to slide "${slide.name || nid(slide)}" key ${keyStr}`);
+
+  const bytes = await deck.saveDeck(outPath);
+  console.log(`Saved: ${outPath} (${bytes} bytes)`);
+}
+
+function copyToImages(deck, hash, srcPath) {
+  if (!deck.imagesDir) {
+    deck.imagesDir = `/tmp/openfig_images_${Date.now()}`;
+    mkdirSync(deck.imagesDir, { recursive: true });
+  }
+  const dest = join(deck.imagesDir, hash);
+  if (!existsSync(dest)) {
+    copyFileSync(srcPath, dest);
+  }
+}
+
+function findSlide(deck, ref) {
+  const byId = deck.getNode(ref);
+  if (byId?.type === 'SLIDE') return byId;
+  return deck.getActiveSlides().find(s => s.name === ref);
+}

package/bin/commands/inspect.mjs

@@ -0,0 +1,91 @@
+/**
+ * inspect — Show document structure (node hierarchy tree).
+ *
+ * Usage: node cli.mjs inspect <file.deck|file.fig> [--depth N] [--type TYPE] [--json]
+ */
+import { FigDeck } from '../lib/core/fig-deck.mjs';
+import { nid } from '../lib/core/node-helpers.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  if (!file) { console.error('Usage: inspect <file.deck|file.fig>'); process.exit(1); }
+
+  const maxDepth = flags.depth ? parseInt(flags.depth) : Infinity;
+  const filterType = flags.type || null;
+  const jsonOut = flags.json != null;
+
+  const deck = file.endsWith('.fig')
+    ? FigDeck.fromFigFile(file)
+    : await FigDeck.fromDeckFile(file);
+
+  // Find root nodes (no parentIndex or parent not in nodeMap)
+  const roots = deck.message.nodeChanges.filter(n => {
+    if (!n.parentIndex?.guid) return true;
+    const pid = `${n.parentIndex.guid.sessionID}:${n.parentIndex.guid.localID}`;
+    return !deck.nodeMap.has(pid);
+  });
+
+  if (jsonOut) {
+    const collect = [];
+    for (const root of roots) {
+      collectJson(deck, nid(root), 0, maxDepth, filterType, collect);
+    }
+    console.log(JSON.stringify(collect, null, 2));
+    return;
+  }
+
+  // Summary
+  const slides = deck.getSlides();
+  const active = deck.getActiveSlides();
+  console.log(`Nodes: ${deck.message.nodeChanges.length}  Slides: ${active.length} active / ${slides.length} total  Blobs: ${deck.message.blobs?.length || 0}`);
+  if (deck.deckMeta) console.log(`Deck name: ${deck.deckMeta.file_name || '(unknown)'}`);
+  console.log('');
+
+  for (const root of roots) {
+    printTree(deck, nid(root), 0, maxDepth, filterType);
+  }
+}
+
+function printTree(deck, id, depth, maxDepth, filterType) {
+  if (depth > maxDepth) return;
+  const node = deck.getNode(id);
+  if (!node) return;
+
+  const type = node.type || '?';
+  const show = !filterType || type === filterType;
+
+  if (show) {
+    const indent = '  '.repeat(depth);
+    const name = node.name ? `"${node.name}"` : '';
+    const removed = node.phase === 'REMOVED' ? ' [REMOVED]' : '';
+    const sym = node.symbolData?.symbolID
+      ? ` sym=${node.symbolData.symbolID.sessionID}:${node.symbolData.symbolID.localID}`
+      : '';
+    const ovCount = node.symbolData?.symbolOverrides?.length;
+    const ovs = ovCount ? ` overrides=${ovCount}` : '';
+    console.log(`${indent}${type} ${name} (${id})${removed}${sym}${ovs}`);
+  }
+
+  for (const child of deck.getChildren(id)) {
+    printTree(deck, nid(child), depth + 1, maxDepth, filterType);
+  }
+}
+
+function collectJson(deck, id, depth, maxDepth, filterType, out) {
+  if (depth > maxDepth) return;
+  const node = deck.getNode(id);
+  if (!node) return;
+  const type = node.type || '?';
+  if (!filterType || type === filterType) {
+    out.push({
+      id, type, name: node.name || null,
+      phase: node.phase || null,
+      symbolID: node.symbolData?.symbolID ? nid({ guid: node.symbolData.symbolID }) : null,
+      overrides: node.symbolData?.symbolOverrides?.length || 0,
+      depth,
+    });
+  }
+  for (const child of deck.getChildren(id)) {
+    collectJson(deck, nid(child), depth + 1, maxDepth, filterType, out);
+  }
+}