Deck3d

deck3d

Turn a Markdown outline into one self-contained, offline deck.html: extruded 3D titles, harvested mermaid diagrams built as 3D objects, animated backgrounds, and an optional glTF prop. The converter code is deterministic; you tune the result by writing overrides in deck.json, never by editing the HTML.

When to use

• The user has a Markdown outline (headings + bullets + ```mermaid blocks) and wants a presentation they can open offline in a browser.
• You need to tune placement, legibility, mode, effects or props of an existing deck.json.

Markdown grammar

• --- front-matter: deck defaults (mode, palette, material, quality, transition, …).
• # Title starts a slide. Zero headings ⇒ one slide id slide.
• The first paragraph after the heading (before bullets) is the subtitle.
• - bullet lines are body bullets.
• A fenced ```mermaid flowchart / sequenceDiagram block becomes the slide's diagram (harvested in headless chromium). Any other diagram type ⇒ warn + no diagram.
• <!-- deck3d: {...} --> inline overrides win over deck.json and warn on clobber.
• Pin a slide id with # Final {#outro} so renames never orphan tuning.

The tune loop

Interactive authoring path: deck3d serve talk.md [--check]. Watches sources, rebuilds on change, reloads in place, re-pins local fx hashes, and lets the configurator save or apply overrides directly.

Manual headless / agent / CI path:

1. deck3d parse talk.md → talk.json (derived IR + empty overrides).
2. deck3d validate talk.json → schema + derived-edit + orphan/prop warnings.
3. deck3d build talk.md -o talk.html → talk.json + talk.html; runs check and prints style: <n>/<N> slides styled.
4. Style — mandatory, and the step that decides whether the deck looks designed. deck3d check talk.html --style warns style-defaults for every slide still running only what parse chose. For each one:
   • pick a corpus effect (deck3d fx list --topic geo, --kind background; the stylistic set — clipped-solids, extruded-shapes, volume-cloud, curve-flow, … — is never auto-picked, so it is always an explicit choice) or write a per-deck one with deck3d fx scaffold <name> --for <slideId>;
   • give a content slide without a mermaid block a built topology (overrides.slides["<id>"].diagram.kind + data);
   • illustrate the section: deck3d props search <kw> --role hero, --role illustration, and props search --role ambient for low-triangle background instances;
   • if extruded titles read as a solid block, set titleEdge: "contrast" (deck default, or per slide) — it outlines every character in the palette text colour;
   • for a deck that wants a horizon, set overrides.deck.floor: "water" (one global surface; per-slide is not a thing);
   • the floor reflects the backgrounds too; overrides.deck.reflectBackdrop: false limits the reflection to slide content (one less backdrop pass per frame), and overrides.deck.floorMatte (0-1) roughens it — 0 is a perfect mirror, ~0.35 reads as polished concrete, ~0.85 as scattered stone (the ⚙ panel drags it on a slider), while overrides.deck.floorReflectivity (0-1, default 1) sets how STRONG the reflection is; all deck-scope only;
   • grade the frame with a post card (deck3d fx list --kind post): add { "id": "outline", "params": { "parts": "diagram" } } (or selective-bloom, god-rays, depth-of-field, pixelate, ascii, …) to the slide's effects[]. One or two per slide; they stack in a fixed order, and check flags declared conflicts.
5. Read the check findings. Fix only the suggested key (e.g. overrides.slides["arch"].diagram.scale), then re-run step 3.
6. deck3d snapshot talk.html --slide 5 -o s5.png to eyeball one slide.
7. Repeat until check is clean and the style line accounts for every slide you meant to design.

Tune by writing deck.json's overrides only:

overrides: {
  deck:    { ...defaults knobs... },
  effects: [{ id, params? }],
  props:   [{ source, id, licence, author, sha256, slide, role, size?, count?, restyle?, anim? }],
  slides:  { "<slideId>": { mode?, palette?, material?, scene?, quality?,
             diagram: { scale?, offset? }, camera: { distance? }, labels: { size? },
             check: { ignore? }, effects? } },
  nodes:   { "<slideId>/<nodeId>": { shape?, label?, position?, size?, material? } },
  edges:   { "<slideId>/<edgeId>": { kind?, material? } }
}

Objects deep-merge; arrays replace (an effects/props list is the whole list); diagram.data replaces as a whole object so labels and values never mix provenance. Full field list: reference/ir-fields.md.

The deck's ⚙ configurator (C key, or the gear) tries knobs live. Its Effects block ticks composed effects off and adds any corpus or local: card from the add effect… picker; both rebuild the slide immediately. Under deck3d serve, Apply to deck.json merges straight into talk.json and rebuilds; Save overrides.json writes overrides.json beside the deck. In unserved decks or headless workflows, Export writes an overrides.json in exactly this grammar. Merge it manually with:

deck3d overrides apply talk.json overrides.json

It deep-merges, re-validates, and refuses to write on a validation error. Note that markdown inline overrides win over anything in that file, and an exported effects list pins that scope's whole list.

Styling with effects

deck3d fx list [--kind k] [--tag t] [--json] prints the catalogue; reference/effects.md has params and licences.

• parse assigns deterministic defaults (title→swarm, flowchart→tokens, sequence→rings, security→glyph-rain, data→data-columns), then routes the rest by topic (deck3d fx list --topic <t>; ai agents geo trust security compute data money work timeline sales process). autoStyle: false restores the plain v1 fallback.
• Replace them with overrides.slides["<id>"].effects = [{ id, params? }].

Video on a slide

video-screen puts a looping clip on a framed screen standing in the scene:

{ "id": "video-screen", "params": { "src": "video/demo.mp4", "width": 7.5, "x": 5, "y": 1, "tilt": -0.25 } }

The clip MUST be same-origin, or the browser taints the canvas and the frame never renders. Two ways to satisfy that:

• deck3d serve serves media sitting beside the deck (video/demo.mp4), which is the authoring path.
• deck3d render deck.json -o deck.html --embed-video inlines clips as data: URLs for ONE portable file. Opt-in, because base64 costs ~33% on top of the clip's own size.

A bare file://deck.html next to a video/ folder does NOT work — that clip is cross-origin. Playback freezes during transitions and runs only while the slide is settled, so check and snapshot stay deterministic.