Excalidraw Use

Excalidraw: images onto a board

Excalidraw is a whiteboard people draw on live. This skill covers the part that is fiddly to do by hand: getting a lot of existing images onto a board, laid out so nobody has to drag them apart afterwards.

It does not generate diagrams from prose. If the request is "draw the architecture" or "make a flowchart", that is a diagram-generation job — several tools and skills do it, including a diagram skill in the gstack suite if the user has it installed.

Which job is this?

Job 1 — build a pick tray of images

python3 scripts/build_scene.py \
  --out tray.excalidraw \
  --cols 6 \
  --template-from ~/path/to/their-board.excalidraw \
  --exclude already-placed.png \
  images/*.png

Expected output — if you do not see the verified: line, the file is not usable:

verified: 30 image element(s), hashes match, no overlap
placed 30 image(s), 6 x 5 grid, min gap 600
wrote tray.excalidraw (3.5 MB)

Hand the user the file plus how to get it onto their board. That second half is where this goes wrong: at excalidraw.com, both Open and drag-and-drop replace the entire current scene. Telling someone to "open this file" when they have a live board is telling them to lose it. The additive route is the clipboard — full instructions and the reasoning in references/paste_workflow.md. Read it before you write the hand-off message.

Three decisions worth making deliberately:

• --template-from whenever they have an existing board. Excalidraw's published JSON schema documents the top-level shape and the files map, but not the image element's own fields (fileId, status, scale, crop), so copying a live element from their board is the only way to be sure the field set matches the build they actually run. Without it a reasonable default is used, which has worked but is one observed field set, not a spec. references/scene_file_format.md has the field-by-field breakdown, keeping what the official docs state separate from what was read off a real file — open it when you need to hand-build or repair a scene rather than let the script write one.
• --exclude anything already on their board. The check is by image content, not filename, so a renamed copy is still caught. Skipping this is how someone ends up with the same picture twice and has to delete one by hand.
• Spacing. --cell is the longest side each image is scaled to; --pitch is the distance between cell centres. The gap is pitch - cell, and the defaults (800 / 1400 → 600) are deliberately generous. If a user has ever said "don't make me fix the spacing again", raise --pitch, don't lower it.

If the scene is more than ~15 MB, split it — the clipboard is where a large scene stalls:

python3 scripts/split_scene.py --scene tray.excalidraw --out-dir parts/ --chunks 4

Job 2 — turn a slide deck into clean images

For Vite/React decks whose slides are registered in a src/slides/index.ts with entries shaped { id: 'intro', component: S01, fragmentCount: 3 }.

# 1. Build the deck FROM SOURCE and serve that build (not a dev server).
cd <deck>; npx vite build --outDir /tmp/deck-dist --emptyOutDir
cd /tmp/deck-dist && python3 -m http.server 8080 &

# 2. Shoot it.
node scripts/shoot_deck.mjs \
  --index <deck>/src/slides/index.ts \
  --url http://127.0.0.1:8080/index.html \
  --out shots/ \
  --advance pdf     # or: keys

Expected output:

30 slides (7 with fragments), advance=pdf
30/30 captured, 32 inline chrome element(s) hidden -> shots/
all .fragment elements rendered visible (opacity check)

That last line is the one that matters. If instead you see WARNING: N slide(s) have fragments that never revealed, those screenshots are missing content — do not feed them into Job 1. Read references/deck_screenshot_pitfalls.md; the usual cause is that the build being served is older than the source.

puppeteer must be resolvable from wherever you run the script. Decks that generate their own PDFs usually already have it — run the script from that project, or symlink its node_modules next to the script. npx puppeteer does not install a resolvable module for an ESM import.

Picking --advance: grep the deck's Deck component for pdf. If it reads a ?pdf=1 query, use pdf; otherwise keys. Never both — under ?pdf=1 the fragment index is already at maximum, so extra key presses move to the next slide and you silently capture the wrong content.

Add --strict to make unrevealed fragments a non-zero exit when this runs inside a pipeline. It stays a warning by default so a deck that legitimately keeps a .fragment hidden does not fail the whole run.