feat: presentation-framework integration for PDF/slide export

[hugolytics]

Problem

Teams using DiaScope to align legal + technical stakeholders need a compliance paper trail — a static, portable document (PDF or slides) that can be stored in Confluence, Notion, Google Drive, or emailed. The interactive HTML viewer cannot satisfy this use case on its own.

Constraints

No custom PDF layout engine. Building or maintaining a bespoke PDF renderer is out of scope. The solution must integrate with an existing framework that provides PDF export out of the box.

Proposed approach: presentation framework integration

Integrate with one or more established presentation frameworks that:

• handle their own layout and PDF export
• provide a customization escape hatch so users can control rendering
• are widely used and maintained

Candidates to evaluate:

• Slidev — Markdown + Vue, excellent PDF export, highly customizable
• Reveal.js — HTML/Markdown, print-to-PDF via its own print stylesheet
• LaTeX / Beamer — maximum layout control, good institutional fit
• Marp — Markdown-first, lean, good PDF output

The integration would likely mean DiaScope emitting a format that the target framework consumes (e.g. a Markdown file, a Slidev deck .md, a Reveal.js HTML structure) rather than DiaScope owning the PDF pipeline itself.

Required behavior in the exported output

Step pages

• One page/slide per story step
• Diagram rendered (SVG strongly preferred — stays sharp at any zoom)
• Highlighted elements baked in at export time (no dynamic highlight)
• Context mode always on: non-highlighted components are greyed out, not hidden
• Narration text for that step present on the page

Navigation

• PDF outline/bookmarks (clickable step index in the PDF sidebar)
• Internal link from each step page to the full-diagram/legend page
• Internal links from the full-diagram page back to each step

Full diagram page

• The complete diagram with all components visible and ungreyed
• Legend (if the story defines one), co-located or on an adjacent page
• Links back to individual step pages

Legend

• Treated as a separate page/slide
• Linked from step pages
• No expectation of a reliable "back" button (PDF navigation is one-way; rely on PDF viewer navigation or page numbers)

Customization escape hatch

• Because the output passes through the presentation framework, users can modify the generated deck/markdown to control layout, fonts, branding, etc. before exporting to PDF

Out of scope (for this ticket)

• Hover tooltips (unreliable across PDF viewers outside Acrobat)
• Interactive folding/collapsing
• A built-in DiaScope print stylesheet
• Building or maintaining a PDF layout engine

Open questions

• Which framework should be the primary integration target?
• Should DiaScope emit a single multi-format output (e.g. a Slidev deck that also exports to PDF), or separate outputs per framework?
• How do we handle stories with a large number of steps (page count, file size)?

[hugolytics]

After reading the current implementation, I think Slidev should be the primary integration target.

Why Slidev is actually a natural fit for DiaScope

DiaScope is already structurally very close to a deck compiler:

• The canonical content model is already an ordered StoryFile.steps[] sequence with tag, title, body, and nodes.
• storyToViewerOptions() already adapts that story model into a presentation-like runtime shape.
• The current HTML output is not a generic app shell; it is already a story shell with:
  • step navigation pills
  • a step title/body panel
  • prev/next navigation
  • arrow-key stepping
  • one persistent diagram canvas plus one persistent narration panel
• goStep() is effectively slide navigation semantics: update active step, update title/body, apply highlight, auto-zoom to relevant nodes.

In other words: DiaScope already behaves like a deck engine with an interactive shared stage. The current target just happens to be a single self-contained HTML viewer.

That makes Slidev much less of a bolt-on than I initially assumed. It looks like a fairly direct second renderer for the story model.

Recommendation

Primary target

Slidev

Renderer strategy

Do not make DiaScope own a multi-format PDF layout engine.

Instead:

• keep the existing StoryFile as the canonical IR
• keep the current interactive HTML build path
• add a new export renderer that emits a Slidev deck + assets

So the architecture becomes:

• StoryFile + D2 -> interactive HTML viewer (existing)
• StoryFile + D2 -> Slidev deck (new)

This fits the issue constraints well:

• no bespoke PDF renderer
• strong customization escape hatch
• good path to PDF/slides
• clean separation between DiaScope story semantics and framework-specific layout/export

Why Slidev over the other candidates

Slidev

Best fit with the current codebase because DiaScope already has:

• ordered story steps
• deck-like navigation
• a stable JS/TS pipeline
• HTML/SVG-first rendering assumptions

Also gives us:

• reusable layouts/components
• Markdown as editable output
• a clean place to encode internal links, full-diagram pages, legend pages, branding, etc.

Marp

Still a reasonable fallback, but better if DiaScope were only generating simple static slides.
The current implementation already has richer semantics than “Markdown + image + text”, so Marp likely leaves useful structure on the floor.

Reveal.js

Possible, but less compelling than Slidev for a generated artifact pipeline.
Feels closer to “browser presentation app” than “clean deck export target”.

Beamer

Could be a later secondary renderer for highly formal/legal/institutional PDF output, but it is not the most natural next step from the current TS/HTML/SVG implementation.

Important design decision

The right boundary is not “export the current viewer HTML into PDF somehow”.

The right boundary is:

1. keep StoryFile as the source of truth
2. create a small export model for slide generation
3. render that export model into Slidev

That avoids coupling the export path to the current interactive viewer shell.

Proposed implementation shape

1. Add a dedicated export pipeline

Introduce something like:

• src/export/types.ts
• src/export/slidev.ts
• src/export/svg-frames.ts

With an intermediate structure along these lines:

• DeckMeta
• StepPage[]
• FullDiagramPage
• LegendPage
• AssetManifest

Where each StepPage contains:

• step id
• tag/title/body
• highlighted SVG asset path
• anchor name
• links to full diagram / legend

2. Pre-render static SVG per step

This is the core export problem regardless of framework.

For each step:

• start from the full D2-rendered SVG
• bake in the highlight state statically
• keep context mode on
• grey out non-active nodes/edges
• do not hide non-active nodes/edges
• produce one SVG per step

Also produce:

• one full, ungreyed diagram SVG
• optionally one legend artifact/page if the story defines one

This is the real bridge from the current dynamic viewer behavior to printable export.

3. Emit a Slidev deck

Generate a .md deck plus asset folder.

Suggested slide structure:

• title / intro slide
• one slide per step
• one full-diagram slide
• one legend slide

Each step slide should include:

• step tag/title
• narration body
• static highlighted SVG
• link to full diagram
• link to legend

The full-diagram slide should include:

• full diagram SVG
• links back to step slides

The legend slide should be separate, per the issue requirements.

4. Use Slidev for layout, not DiaScope

DiaScope should generate:

• content
• anchors
• links
• asset references
• maybe a thin default theme/layout

But the final page composition belongs to Slidev.

That preserves the customization escape hatch and keeps DiaScope out of the PDF layout business.

Recommended CLI/API shape

I would prefer an explicit new command rather than overloading the current HTML build path too early.

Something like:

• diascope export slidev <diagram.d2> <story.yaml> -o deck.md
• assets emitted into a sibling folder

Possible later:

• diascope export marp ...
• diascope export beamer ...

This is cleaner than pretending there is one universal export format from day one.

Open questions: my answers

Which framework should be the primary integration target?

Slidev

Because the current viewer is already deck-like in structure and semantics.

Single multi-format output or separate outputs per framework?

Separate renderers per framework, sharing one canonical DiaScope story/export model.

Not one universal lowest-common-denominator output.

How do we handle large numbers of steps?

Start simple:

• one slide per step
• accept that long stories produce long decks
• make the deck navigable via outline/bookmarks and internal links

Later improvements can include:

• optional chaptering/sections
• optional condensed mode
• optional splitting into multiple decks

But I would not complicate v1 with aggressive pagination heuristics.

Suggested scope for v1

In scope

• Slidev exporter
• one slide per step
• static per-step SVGs with baked highlighting
• full-diagram slide
• legend slide
• internal links
• editable generated deck

Out of scope for v1

• trying to preserve interactive pan/zoom behavior
• trying to export the current HTML viewer directly
• multi-framework support in the first pass
• perfect handling of extremely large stories

Concrete implication for implementation

The current viewer should remain the interactive runtime.

The new export path should be a parallel renderer that reuses:

• StoryFile
• step ordering
• step metadata
• node targeting semantics

but does not depend on runtime goStep() behavior at export time.

That keeps the architecture clean:

• interactive narration stays interactive
• compliance/export narration becomes static, printable, and editable

Bottom line

Reading the implementation changed my view:

Slidev is not a weird integration here.
It is probably the most natural first export target because DiaScope is already conceptually a narrated deck system whose current renderer happens to be a single interactive HTML page.

So my recommendation is:

1. keep StoryFile as canonical IR
2. add a dedicated static export pipeline
3. emit Slidev as the first export target
4. consider Marp / Beamer later as additional renderers, not as the primary path