Markdown slideshows: deck design system and present mode

[HamptonMakes]

Markdown slideshows, foundation through present mode. A deck is a rendering convention over the plan's single markdown blob — nothing new is persisted, so versioning, diffs, and comment anchoring keep working unchanged. Design doc: CoPlan plan 01a01696-aad6-762b-ad66-7681bbadd98c (rev 6).

Phase 1 — foundation

Plan-type behavior. Plan types gain a behavior column (document / slideshow, string enum + inclusion validator), and Plan#slideshow? delegates to it — retyping a plan is what converts a document into a deck and back. Ships a Presentation default type (installable via coplan:plan_types:install_defaults) whose template teaches the authoring conventions, plus admin support, a presentation icon, and seeded showcase decks.

Slideshows::Split. Splits markdown into slides at top-level --- thematic breaks, AST-driven so a --- inside a code fence, blockquote, or setext heading never splits, and ***/___ stay visible rules. Extracts <!-- notes: ... --> speaker notes and gathers footnote/link-reference definitions as positioned blocks so slides can render in isolation. Link-definition candidates are validated by a parser round-trip (parse the candidate alone; it must be fully consumed), which is what keeps [looks]: like-a-definition prose from being hoisted onto every slide.

SlideshowsHelper#render_slideshow. Renders each slide through the standard document pipeline — same sanitization, mention chips, interactive checkboxes — inside section.deck-slide wrappers. Checkbox data-line stays document-absolute via a new line_offset param on render_markdown. Footnote sections are excluded per slide and marks are renumbered to match the document-wide References back matter, including document-mode fnref ids so every ↩ backref resolves.

Phase 2 — the deck design system

docs/SLIDE_SPEC.md is the product boundary, and its fenced conformance examples ARE the test suite: spec/services/slideshows/conformance_spec.rb executes every fixture in the document, so the spec cannot drift from the implementation, and a future implementation in another language proves itself against the same fixtures.

Slideshows::Classify. A pure function assigning each slide a layout pattern (title, stage, code, quote, table, columns, split, content) and one of four type-scale steps, from content shape alone — no layout syntax, no measurement, no AI in the layout path. Authors and agents move an image in the source to move it on the slide.

deck.css + three token themes (coplan, graphite, poster): 16:9 cards sized in container-query units so a slide is the same design at any width, per-pattern art direction (title canvas + accent bar, staged media, oversized pull quotes, side-by-side panes via grid with zero DOM reordering), and discrete type steps instead of shrink-to-fit. Themes are validated custom-property sets applied by data-deck-theme; user CSS is never accepted. Slide chrome (numbers, kickers, quote marks) is CSS-generated, invisible to the visible-text counts comment anchoring relies on.

Markup decoration. After the deck/document parity passes, the renderer applies the spec's markup contract: the neutral .deck-content name and, on split slides, the .deck-media/.deck-body panes — skipped entirely on any classified-shape/DOM mismatch (sanitized-away raw HTML), so the stylesheet degrades to the content layout rather than wrap the wrong node.

Present mode, the directory pattern, and full-canvas stage media

Present mode. p or the Present button runs the deck as a fullscreen 16:9 show — what a Zoom/Meet screen-share needs. The deck itself is promoted to the top layer (popover API, plus native fullscreen on the wrapper), which is the load-bearing choice: the plan card's glass backdrop-filter makes it the containing block for position: fixed, so a merely-fixed overlay would render at card size inside the card's stacking context. Top-layer elements always position against the viewport. Arrows/space/page keys/Backspace/Home/End/clicks navigate (links and checkboxes on slides still work); Escape or leaving fullscreen ends the show; #present-N resumes; the "N / total" counter is CSS attr() chrome. The presenter wrapper sits outside the live-update swap target and re-applies show state via a childList observer, so a collaborator's edit landing mid-show swaps slides under the presenter without ending it. The show tears down on turbo:before-cache (a cached snapshot would otherwise restore a closed-popover, display: none deck), and the Present toolbar lives outside the text-selection content target so its label never enters the comment-anchor text model.

directory pattern. One list of ≥15 short entries (one paragraph, ≤60 chars, no images/breaks — comment-only blocks inside an entry don't count, comments never influence layout) is an inventory, not an argument: it flows into two balanced CSS columns and bills at ⌈units/2⌉ for the type scale, so a forty-project list lands as two readable columns instead of one column running off the canvas.

Stage sizing. Stage slides now give the visual the whole canvas: thinner padding, media up to 44cqi, and mermaid's inline natural-size max-width overridden so small diagrams scale up to the slide instead of rendering as thumbnails.

RENDER_CACHE_VERSION → 11.

Notes for reviewers

• Definitions are prepended per slide, not appended: an unclosed code fence on a slide would swallow an appended block into visible text, and prepending makes the document's first definition of a duplicated key win everywhere, matching document mode.
• Commonmarker quirk worth knowing: a fragment containing a duplicated footnote definition gets its whole body swallowed into the footnotes section. The per-slide preamble therefore skips footnote keys the slide defines itself (fold-normalized) and never gathers unreferenced footnote definitions as link blocks.
• Deck-specific code is deliberately isolated (Slideshows:: services, own helper, deck-* class namespace, spec + stylesheets with no host-CSS reliance) so the layout engine can be extracted as a standalone package later.
• Verified with four adversarial multi-agent review rounds (phase 1: parity/rendering; phase 2: spec-drift, deck/document parity, and step-sanity attackers with in-browser geometry measurement; present-mode round: classifier/presenter/CSS lenses with two independent refuters per finding). All 33 confirmed findings are fixed and pinned — the phase-2 round hardened the spec itself: image alt text counts for nothing (accessible descriptions no longer shrink type), comment boundaries follow the HTML parser in both malformed directions, split wrapping can never reorder visible text, the unit model is calibrated against what the stylesheet actually renders, and overflowing slides scroll from the top instead of clipping it. The present-mode round caught the backdrop-filter containing-block trap, the Turbo snapshot restoring a mid-show deck as display: none, toolbar text entering the comment-anchor occurrence model, and a nested speaker note flipping a directory slide to single-column.
• Full suite: 1697 examples, 0 failures; 31 conformance fixtures.

Still to come (separate PRs): deck review loop (slide rail, changed-slides, theme picker), speaker-notes drawer + /present deep link, agent fit report.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 40c45e1283

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".