presently 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b7e990c7b6d2f4ef66e333bc95793d0682011102614d92bf02c0278053a42c9
-  data.tar.gz: 4f7ec48d87c12425dd4ecf02d7cf6c3530a9bdd1199ef030b0ab2fb8ed31e669
+  metadata.gz: 3991c95331fdcabd96b64dd78833690a52468f2a1e570eddf3234fd5e9bfa7ac
+  data.tar.gz: 816e1de43c33929e12424659455e116891294d79dcc3d2ea41cc8df9b13317dd
 SHA512:
-  metadata.gz: 9d9629f50e5827eaf97d0fed33b01b1abfcece8f31a2232fc4c98ca765c3538e389fbb8a6f877a6ead1b9131e0a10ddabbfaf8d4b034c964012e86cad1c960c4
-  data.tar.gz: 0f867425bd65d0d39d6252dabef8ffad6d9b952316b7305ed76397fae7561d07cea7656031ad153bd6fa42194e213beae69a65f2168b0599dbda3f74e3686a85
+  metadata.gz: bc5afae0aaeb288b51b4ccd6c8e66a562acd44898a49a3777299865ccff1a400258e88dd1fa3950071db8949b107fa076eac2d5042ccdd847e11d8d395801892
+  data.tar.gz: e0b1a9f6e5743beecdb4745469335c5ed8ad154e74bd5fdf2c745f54ce83532c1d81af3014c67ff8c9480e878b09a21e0df50cf73805e2a5676c0516a8ef807a

checksums.yaml.gz.sig

@@ -0,0 +1,5 @@
+(�e���3UQ��;��p9Vq+�r>���;���K�~��F,�4�ı1$cTq36�̾;���b�t>P�gB
+�+��5����y�RV���_��
+@Ԣ�l/��VbS��քz5`S4��7���HsI$~�P��(w
+
dq����88�lj�]5E���)�5��C#��Ч�gA�+]��l���nG�Uc8�s�*�ih5��:����8���e�%U�5���}>�f:��ntǓ���Y˶�F7��h6R�쎣�ߡ�{
+/��b�

data/bake/presently/slides.rb

@@ -9,6 +9,30 @@ def initialize(context)
 	require "fileutils"
 end
 
+# Extract all presenter notes and print them to stdout.
+#
+# Loads every slide in the slides directory using the Presently API and
+# prints each slide's presenter notes to stdout. Each slide's notes are
+# preceded by a `##` heading with the slide file path.
+#
+# @parameter slides_root [String] The slides directory. Default: `slides`.
+def notes(slides_root: "slides")
+	require "presently"
+	
+	presentation = Presently::Presentation.load(slides_root)
+	
+	presentation.slides.each do |slide|
+		next unless slide.notes
+		
+		puts "## #{slide.path}"
+		puts
+		puts slide.notes.to_commonmark
+		puts
+	end
+	
+	return nil
+end
+
 # Renumber slide files sequentially with a consistent step size.
 #
 # Renames all `.md` files in the slides directory to have sequential

data/lib/presently/presenter_view.rb

@@ -270,8 +270,8 @@ module Presently
 				builder.tag(:div, class: "notes") do
 					builder.tag(:h3){builder.text("Notes")}
 					builder.tag(:div, class: "notes-content") do
-						if slide&.notes
-							builder.raw(slide.notes)
+						if notes = slide&.notes
+							builder.raw(notes.to_html)
 						else
 							builder.tag(:p, class: "no-notes"){builder.text("No presenter notes for this slide.")}
 						end

data/lib/presently/slide.rb

@@ -14,14 +14,52 @@ module Presently
 	# Each slide has YAML front_matter for metadata (template, duration, focus), content sections
 	# split by Markdown headings, and optional presenter notes separated by `---`.
 	class Slide
-		# Parses a Markdown slide file into structured data for {Slide}.
+		# A fragment of a Markly AST document.
 		#
-		# Handles YAML front_matter extraction, presenter note separation, and
-		# Markdown-to-HTML rendering using the Markly AST.
-		module Parser
+		# Wraps a `Markly::Node` of type `:document` and provides rendering helpers.
+		# Used for both content sections and presenter notes so callers can choose
+		# their output format without the parser pre-committing to one.
+		class Fragment
 			# Markly extensions enabled for all slide Markdown rendering.
 			EXTENSIONS = [:table, :tasklist, :strikethrough, :autolink]
 			
+			# Initialize a fragment from a Markly document node.
+			# @parameter node [Markly::Node] A document node containing the fragment content.
+			def initialize(node)
+				@node = node
+			end
+			
+			# @attribute [Markly::Node] The underlying AST document node.
+			attr :node
+			
+			# Whether the fragment has no content.
+			# @returns [Boolean]
+			def empty?
+				@node.first_child.nil?
+			end
+			
+			# Render the fragment to HTML using the Presently renderer.
+			#
+			# Mermaid fenced code blocks are rendered as `<mermaid-diagram>` elements.
+			# @returns [String] The rendered HTML.
+			def to_html
+				Renderer.new(flags: Markly::UNSAFE, extensions: EXTENSIONS).render(@node)
+			end
+			
+			# Render the fragment back to CommonMark Markdown.
+			# @returns [String] The CommonMark source.
+			def to_commonmark
+				@node.to_commonmark
+			end
+			
+			alias to_s to_commonmark
+		end
+		
+		# Parses a Markdown slide file into structured data for {Slide}.
+		#
+		# Handles YAML front_matter extraction, presenter note separation, and
+		# Markdown AST construction via Markly.
+		module Parser
 			module_function
 			
 			# Parse the file and return a {Slide}.
@@ -31,7 +69,7 @@ module Presently
 				raw = File.read(path)
 				
 				# Parse once, with native front matter support.
-				document = Markly.parse(raw, flags: Markly::UNSAFE | Markly::FRONT_MATTER, extensions: EXTENSIONS)
+				document = Markly.parse(raw, flags: Markly::UNSAFE | Markly::FRONT_MATTER, extensions: Fragment::EXTENSIONS)
 				
 				# Extract front matter from the first AST node if present.
 				front_matter = nil
@@ -45,56 +83,62 @@ module Presently
 				document.each{|node| last_hrule = node if node.type == :hrule}
 				
 				if last_hrule
-					notes_fragment = Markly::Node.new(:document)
+					notes_node = Markly::Node.new(:document)
 					while child = last_hrule.next
-						notes_fragment.append_child(child)
+						notes_node.append_child(child)
 					end
 					last_hrule.delete
 					
-					content = parse_sections(document.each)
-					notes = render_nodes(notes_fragment.each)
+					# Extract the last javascript code block from the notes as the slide script.
+					script_node = nil
+					notes_node.each do |node|
+						if node.type == :code_block && node.fence_info.to_s.strip == "javascript"
+							script_node = node
+						end
+					end
+					
+					script = nil
+					if script_node
+						script = script_node.string_content
+						script_node.delete
+					end
+					
+					content = parse_sections(document)
+					notes = Fragment.new(notes_node)
 				else
-					content = parse_sections(document.each)
+					content = parse_sections(document)
 					notes = nil
+					script = nil
 				end
 				
-				Slide.new(path, front_matter: front_matter, content: content, notes: notes)
+				Slide.new(path, front_matter: front_matter, content: content, notes: notes, script: script)
 			end
 			
-			# Parse a list of AST nodes into sections based on top-level Markdown headings.
-			# Each heading becomes a named key; content before the first heading
-			# is collected under `"body"`. Headings inside code blocks are invisible
-			# to this method as they never appear as top-level AST nodes.
-			# @parameter nodes [Array(Markly::Node)] The nodes to parse into sections.
-			# @returns [Hash(String, String)] Sections keyed by heading name, with rendered HTML values.
-			def parse_sections(nodes)
+			# Parse a Markly document into content sections based on top-level headings.
+			#
+			# Each heading becomes a named key; content before the first heading is
+			# collected under `"body"`. Each value is a {Fragment} wrapping a document node.
+			# @parameter document [Markly::Node] The document to parse.
+			# @returns [Hash(String, Fragment)] Sections keyed by heading name.
+			def parse_sections(document)
 				sections = {}
 				current_key = "body"
-				current_nodes = []
+				current_node = Markly::Node.new(:document)
 				
-				nodes.each do |node|
+				document.each do |node|
 					if node.type == :header
-						sections[current_key] = render_nodes(current_nodes) unless current_nodes.empty?
+						sections[current_key] = Fragment.new(current_node) unless current_node.first_child.nil?
 						current_key = node.to_plaintext.strip.downcase.gsub(/\s+/, "_")
-						current_nodes = []
+						current_node = Markly::Node.new(:document)
 					else
-						current_nodes << node
+						current_node.append_child(node.dup)
 					end
 				end
 				
-				sections[current_key] = render_nodes(current_nodes) unless current_nodes.empty?
+				sections[current_key] = Fragment.new(current_node) unless current_node.first_child.nil?
 				
 				sections
 			end
-			
-			# Render a list of AST nodes to HTML via a temporary document.
-			# @parameter nodes [Array(Markly::Node)] The nodes to render.
-			# @returns [String] The rendered HTML.
-			def render_nodes(nodes)
-				doc = Markly::Node.new(:document)
-				nodes.each{|node| doc.append_child(node.dup)}
-				Renderer.new(flags: Markly::UNSAFE, extensions: EXTENSIONS).render(doc)
-			end
 		end
 		
 		# Load and parse a slide from a Markdown file.
@@ -107,13 +151,15 @@ module Presently
 		# Initialize a slide with pre-parsed data.
 		# @parameter path [String] The file path of the slide.
 		# @parameter front_matter [Hash | Nil] The parsed YAML front_matter.
-		# @parameter content [Hash(String, String)] Content sections keyed by heading name.
-		# @parameter notes [String | Nil] The rendered HTML presenter notes.
-		def initialize(path, front_matter: nil, content: {}, notes: nil)
+		# @parameter content [Hash(String, Fragment)] Content sections keyed by heading name.
+		# @parameter notes [Fragment | Nil] The presenter notes as a Markly AST fragment.
+		# @parameter script [String | Nil] JavaScript to execute after the slide renders.
+		def initialize(path, front_matter: nil, content: {}, notes: nil, script: nil)
 			@path = path
 			@front_matter = front_matter
 			@content = content
 			@notes = notes
+			@script = script
 		end
 		
 		# @attribute [String] The file path of the slide.
@@ -122,12 +168,15 @@ module Presently
 		# @attribute [Hash | Nil] The parsed YAML front_matter.
 		attr :front_matter
 		
-		# @attribute [Hash(String, String)] The content sections keyed by heading name.
+		# @attribute [Hash(String, Fragment)] The content sections keyed by heading name.
 		attr :content
 		
-		# @attribute [String | Nil] The rendered HTML presenter notes.
+		# @attribute [Fragment | Nil] The presenter notes as a Markly AST fragment.
 		attr :notes
 		
+		# @attribute [String | Nil] JavaScript to execute after the slide renders on the display.
+		attr :script
+		
 		# The template to use for rendering this slide.
 		# @returns [String] The template name from front_matter, or `"default"`.
 		def template
@@ -159,7 +208,7 @@ module Presently
 		end
 		
 		# The transition type for animating into this slide.
-		# @returns [String | Nil] The transition name (e.g. `"fade"`, `"slide-left"`, `"magic-move"`), or `nil` for instant swap.
+		# @returns [String | Nil] The transition name (e.g. `"fade"`, `"slide-left"`, `"morph"`), or `nil` for instant swap.
 		def transition
 			@front_matter&.fetch("transition", nil)
 		end

data/lib/presently/slide_renderer.rb

@@ -36,6 +36,11 @@ module Presently
 			classes = [@css_class, extra_class].compact.join(" ")
 			builder.tag(:div, class: classes, data: {template: slide.template}) do
 				builder.raw(html)
+				if slide.script
+					builder.tag(:script, type: "text/slide-script") do
+						builder.raw(slide.script)
+					end
+				end
 			end
 		end
 	end
@@ -63,14 +68,15 @@ module Presently
 		# @parameter name [String] The section name (derived from the Markdown heading).
 		# @returns [Boolean]
 		def section?(name)
-			!(@slide.content[name] || "").empty?
+			fragment = @slide.content[name]
+			fragment && !fragment.empty?
 		end
 		
 		# Get a named content section as raw HTML markup.
 		# @parameter name [String] The section name (derived from the Markdown heading).
 		# @returns [XRB::MarkupString] The rendered HTML content, safe for embedding.
 		def section(name)
-			XRB::MarkupString.raw(@slide.content[name] || "")
+			XRB::MarkupString.raw(@slide.content[name]&.to_html || "")
 		end
 	end
 end

data/lib/presently/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Presently
-	VERSION = "0.2.0"
+	VERSION = "0.4.0"
 end

data/public/_static/index.css

@@ -40,6 +40,7 @@ html, body {
 }
 
 .slide-inner {
+	position: relative;
 	width: 100%;
 	height: 100%;
 	display: flex;
@@ -63,6 +64,14 @@ html, body {
 
 .default-template .slide-body li {
 	margin-bottom: 0.5em;
+	transition: opacity 0.4s ease, transform 0.4s ease;
+}
+
+@starting-style {
+	.default-template .slide-body li {
+		opacity: 0;
+		transform: translateX(-0.5em);
+	}
 }
 
 /* Title template */
@@ -125,6 +134,16 @@ html, body {
 	margin-bottom: 0.4em;
 }
 
+/* Diagram template */
+.diagram-template {
+	padding: 0;
+}
+
+.diagram-template .slide-body > div {
+	position: absolute;
+	box-sizing: border-box;
+}
+
 /* Image template */
 .image-template .slide-caption {
 	font-size: 1.6rem;
@@ -353,12 +372,12 @@ html[data-transition="slide-right"]::view-transition-new(slide-container) {
 /* Magic move — the browser interpolates position/size for matched
    view-transition-name elements. No cross-fade on the container
    to avoid background dimming. */
-html[data-transition="magic-move"]::view-transition-old(slide-container) {
+html[data-transition="morph"]::view-transition-old(slide-container) {
 	animation: none;
 	opacity: 0;
 }
 
-html[data-transition="magic-move"]::view-transition-new(slide-container) {
+html[data-transition="morph"]::view-transition-new(slide-container) {
 	animation: none;
 }
 
@@ -392,6 +411,72 @@ html[data-transition="magic-move"]::view-transition-new(slide-container) {
 	to { transform: translateX(0); opacity: 1; }
 }
 
+/* ========================
+   BUILD EFFECTS
+   ======================== */
+
+/* Suppress both pseudo-elements for hidden build elements so they
+   neither crossfade in nor crossfade out during the transition. */
+::view-transition-old(.build-hidden),
+::view-transition-new(.build-hidden) {
+	display: none;
+}
+
+/* Fade */
+::view-transition-new(.build-fade) {
+	animation: vt-fade-in 0.4s ease;
+}
+
+/* Fly in from left */
+@keyframes build-fly-in-left {
+	from { transform: translateX(-2rem); opacity: 0; }
+	to { transform: translateX(0); opacity: 1; }
+}
+
+::view-transition-new(.build-fly-left) {
+	animation: build-fly-in-left 0.4s ease;
+}
+
+/* Fly in from right */
+@keyframes build-fly-in-right {
+	from { transform: translateX(2rem); opacity: 0; }
+	to { transform: translateX(0); opacity: 1; }
+}
+
+::view-transition-new(.build-fly-right) {
+	animation: build-fly-in-right 0.4s ease;
+}
+
+/* Fly in from bottom */
+@keyframes build-fly-in-up {
+	from { transform: translateY(2rem); opacity: 0; }
+	to { transform: translateY(0); opacity: 1; }
+}
+
+::view-transition-new(.build-fly-up) {
+	animation: build-fly-in-up 0.4s ease;
+}
+
+/* Fly in from top */
+@keyframes build-fly-in-down {
+	from { transform: translateY(-2rem); opacity: 0; }
+	to { transform: translateY(0); opacity: 1; }
+}
+
+::view-transition-new(.build-fly-down) {
+	animation: build-fly-in-down 0.4s ease;
+}
+
+/* Scale in */
+@keyframes build-scale-in {
+	from { transform: scale(0.8); opacity: 0; }
+	to { transform: scale(1); opacity: 1; }
+}
+
+::view-transition-new(.build-scale) {
+	animation: build-scale-in 0.4s ease;
+}
+
 /* ========================
    PRESENTER VIEW
    ======================== */
@@ -617,6 +702,10 @@ html[data-transition="magic-move"]::view-transition-new(slide-container) {
 	margin: 0.3em 0;
 }
 
+.notes-content em {
+	color: var(--ahead);
+}
+
 .notes .no-notes {
 	opacity: 0.4;
 	font-style: italic;

data/public/application.js

@@ -1,5 +1,6 @@
 import { Live } from 'live';
 import Syntax from '@socketry/syntax';
+import { Slide } from './slide.js';
 
 const live = Live.start();
 
@@ -65,6 +66,29 @@ function applyCodeFocus() {
 	});
 }
 
+// Run the script for a single slide element.
+// Wrapped in try/catch so syntax errors don't crash the presentation.
+function runScript(slideEl) {
+	const scriptEl = slideEl.querySelector('script[type="text/slide-script"]');
+	if (!scriptEl) return;
+
+	const container = slideEl.querySelector('.slide-body') ?? slideEl;
+	const slide = new Slide(container);
+
+	try {
+		const fn = new Function('slide', scriptEl.textContent);
+		fn(slide);
+	} catch (error) {
+		console.error('Slide script error:', error);
+	}
+}
+
+// Run scripts for all slide elements currently in the DOM.
+function runSlideScripts() {
+	document.querySelectorAll('.slide').forEach(runScript);
+}
+
+
 // Detect the transition type from the incoming HTML before morphdom applies it.
 function detectTransition(html) {
 	const match = html.match(/data-transition="([^"]+)"/);
@@ -82,11 +106,12 @@ live.update = function(id, html, options) {
 	
 	if (transition && document.startViewTransition && !activeTransition) {
 		document.documentElement.dataset.transition = transition;
-		
+
 		activeTransition = document.startViewTransition(() => {
 			originalUpdate(id, html, options);
+			runSlideScripts();
 		});
-		
+
 		activeTransition.finished.finally(() => {
 			delete document.documentElement.dataset.transition;
 			activeTransition = null;
@@ -95,6 +120,7 @@ live.update = function(id, html, options) {
 		});
 	} else {
 		originalUpdate(id, html, options);
+		runSlideScripts();
 		Syntax.highlight();
 		applyCodeFocus();
 	}
@@ -108,8 +134,9 @@ const observer = new MutationObserver(() => {
 });
 observer.observe(document.body, { childList: true, subtree: true });
 
-// Initial focus application:
+// Initial focus and script application:
 applyCodeFocus();
+runSlideScripts();
 
 // Jump-to select: forward the selected slide index to the presenter view.
 document.addEventListener('change', (event) => {

data/public/slide.js

@@ -0,0 +1,52 @@
+// Represents a collection of elements within a slide to be revealed sequentially.
+// Has no side effects until build() is called.
+export class SlideElements {
+	constructor(elements) {
+		this._elements = elements;
+	}
+
+	// Show the first n elements and hide the rest.
+	// Assigns view-transition-names and applies build visibility in one step.
+	// @parameter n [Integer] Number of elements to show.
+	// @parameter options [Object]
+	//   group: prefix for view-transition-name (default: "build")
+	//   effect: "fade", "fly-up", "fly-down", "fly-left", "fly-right", "scale"
+	build(n, options = {}) {
+		const prefix = options.group || 'build';
+
+		this._elements.forEach((element, index) => {
+			element.style.viewTransitionName = `${prefix}-${index + 1}`;
+
+			if (index < n) {
+				element.style.visibility = 'visible';
+				// Newly revealed element: apply the enter effect.
+				// Already-visible elements: clear any class so they morph normally.
+				element.style.viewTransitionClass = (index === n - 1 && options.effect)
+					? `build-${options.effect}`
+					: '';
+			} else {
+				element.style.visibility = 'hidden';
+				// Hidden elements: suppress both pseudo-elements so they don't
+				// crossfade in or out during the transition.
+				element.style.viewTransitionClass = 'build-hidden';
+			}
+		});
+	}
+}
+
+// The scripting context passed to each slide's javascript block.
+// Scopes element queries to the slide body.
+export class Slide {
+	constructor(container) {
+		this._container = container;
+	}
+
+	// Find elements within this slide matching the given CSS selector.
+	// Use comma-separated selectors to combine multiple element types, e.g. "h2, li".
+	// @parameter selector [String] A CSS selector scoped to the slide body.
+	// @returns [SlideElements]
+	find(selector) {
+		const elements = Array.from(this._container.querySelectorAll(selector));
+		return new SlideElements(elements);
+	}
+}

data/readme.md

@@ -2,6 +2,8 @@
 
 A web-based presentation tool built with [Lively](https://github.com/socketry/lively). Write your slides in Markdown, present them in the browser, and control everything from a separate presenter display.
 
+![Presenter Display](presenter.png)
+
 [![Development Status](https://github.com/socketry/presently/workflows/Test/badge.svg)](https://github.com/socketry/presently/actions?workflow=Test)
 
 ## Features
@@ -17,13 +19,32 @@ A web-based presentation tool built with [Lively](https://github.com/socketry/li
 
 ## Usage
 
-Please see the [project documentation](https://github.com/socketry/presently) for more details.
+Please see the [project documentation](https://socketry.github.io/presently/) for more details.
+
+  - [Getting Started](https://socketry.github.io/presently/guides/getting-started/index) - This guide explains how to use `presently` to create and deliver web-based presentations using Markdown slides.
 
-  - [Getting Started](https://github.com/socketry/presentlyguides/getting-started/index) - This guide explains how to use `presently` to create and deliver web-based presentations using Markdown slides.
+  - [Animating Slides](https://socketry.github.io/presently/guides/animating-slides/index) - This guide explains how to animate content within slides using the `morph` transition and the slide scripting system.
 
 ## Releases
 
-Please see the [project releases](https://github.com/socketry/presentlyreleases/index) for all releases.
+Please see the [project releases](https://socketry.github.io/presently/releases/index) for all releases.
+
+### v0.4.0
+
+  - Add `bake presently:slides:notes` task to extract all presenter notes into a single Markdown document, with each slide's file path as a heading. Useful for reviewing or sharing speaker notes outside of the presentation.
+  - Presenter notes are now kept as a Markdown AST internally and rendered to HTML on demand, so the notes you write are faithfully round-tripped rather than converted to HTML at parse time.
+
+### v0.3.0
+
+  - Add `diagram` template with a `position: relative` container — direct `<div>` children are `position: absolute` by default for free-form layouts.
+  - All slide templates now have `position: relative` on the slide inner container, allowing absolutely positioned overlays in any template.
+  - Add slide scripting: a fenced ` ```javascript ``` ` block at the end of presenter notes is extracted and executed in the browser after each slide renders. The script receives a `slide` object scoped to the slide body.
+  - Add `Slide#find(selector)` — a pure CSS selector query returning a `SlideElements` collection with no side effects.
+  - Add `SlideElements#build(n, options)` — shows the first `n` matched elements, hides the rest, and assigns `view-transition-name` for morph transition matching. Accepts `group` (name prefix) and `effect` (entry animation) options.
+  - Add build effects via `view-transition-class`: `fade`, `fly-left`, `fly-right`, `fly-up`, `fly-down`, `scale`. Requires Chromium 125+; degrades gracefully to instant appear in other browsers.
+  - Rename `magic-move` transition to `morph`.
+  - Italic text in presenter notes is styled in amber to distinguish stage directions from spoken words.
+  - Add transitions guide and animating slides guide to documentation.
 
 ### v0.2.0
 

data/releases.md

@@ -1,5 +1,22 @@
 # Releases
 
+## v0.4.0
+
+  - Add `bake presently:slides:notes` task to extract all presenter notes into a single Markdown document, with each slide's file path as a heading. Useful for reviewing or sharing speaker notes outside of the presentation.
+  - Presenter notes are now kept as a Markdown AST internally and rendered to HTML on demand, so the notes you write are faithfully round-tripped rather than converted to HTML at parse time.
+
+## v0.3.0
+
+  - Add `diagram` template with a `position: relative` container — direct `<div>` children are `position: absolute` by default for free-form layouts.
+  - All slide templates now have `position: relative` on the slide inner container, allowing absolutely positioned overlays in any template.
+  - Add slide scripting: a fenced ` ```javascript ``` ` block at the end of presenter notes is extracted and executed in the browser after each slide renders. The script receives a `slide` object scoped to the slide body.
+  - Add `Slide#find(selector)` — a pure CSS selector query returning a `SlideElements` collection with no side effects.
+  - Add `SlideElements#build(n, options)` — shows the first `n` matched elements, hides the rest, and assigns `view-transition-name` for morph transition matching. Accepts `group` (name prefix) and `effect` (entry animation) options.
+  - Add build effects via `view-transition-class`: `fade`, `fly-left`, `fly-right`, `fly-up`, `fly-down`, `scale`. Requires Chromium 125+; degrades gracefully to instant appear in other browsers.
+  - Rename `magic-move` transition to `morph`.
+  - Italic text in presenter notes is styled in amber to distinguish stage directions from spoken words.
+  - Add transitions guide and animating slides guide to documentation.
+
 ## v0.2.0
 
   - Use Markly's native front matter parser (`Markly::FRONT_MATTER`) instead of manual string splitting, parsing each slide document once and extracting front matter directly from the AST.

data/templates/diagram.xrb

@@ -0,0 +1,5 @@
+<div class="slide-inner diagram-template">
+	<div class="slide-body">
+		#{self.section("body")}
+	</div>
+</div>

metadata

@@ -1,12 +1,41 @@
 --- !ruby/object:Gem::Specification
 name: presently
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Samuel Williams
 bindir: bin
-cert_chain: []
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
@@ -1029,10 +1058,12 @@ files:
 - public/_static/index.css
 - public/application.js
 - public/mermaid-diagram.js
+- public/slide.js
 - readme.md
 - releases.md
 - templates/code.xrb
 - templates/default.xrb
+- templates/diagram.xrb
 - templates/fill.xrb
 - templates/image.xrb
 - templates/section.xrb
@@ -1043,6 +1074,7 @@ homepage: https://github.com/socketry/presently
 licenses:
 - MIT
 metadata:
+  documentation_uri: https://socketry.github.io/presently/
   source_code_uri: https://github.com/socketry/presently.git
 rdoc_options: []
 require_paths: