presently 0.20.1 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44f63b8a685dbff7a9d834076b6f3df8e68cb512376a97a4953dd37ebad18b3d
-  data.tar.gz: ec2b552b9f5b72952bfed56f2aecdc55743ed18128f67cc391e52d9ec0064748
+  metadata.gz: bceb99c19c4563f60e51fe3e17cce836c7176ebd9b695919af5737ccc87fd4ca
+  data.tar.gz: 102b2bbab9019d17c5aadb85c3f40044c1e94bdb2e587482c246d0c184f5fa36
 SHA512:
-  metadata.gz: 5a1e4f78672691afb74bb33b7a1f464dfec183d1b4e691dd3a159da961d3d1a5d7950745614880bc6cef8d4a2b9c0e10f66164e079abd357f5ee3a5aefa73735
-  data.tar.gz: aef5cd14d684f9dfa245bcac914d587d4889bd1a07661513e1e1cc87697c6e18ea11fd7e9ca151664af30c6bc234140ea173426da30cebfd57aeb918cba24bac
+  metadata.gz: 8edf0ac3857670ce3afe65522bdf9d560b2f909fb68a85a43161200047f6a8fe588be5bef3ee685ca007a927d47999b5afc7c0db65ae43896c78b018ec347ffc
+  data.tar.gz: b8cca4183e4494e9fdd2923e429bc3bdca75310f127eba5474f410214c90f2cd5a0b2d89bb03df1e887673d30b81ebb45320b3af5853b73f137e6fbe6c2554f7

data/bake/presently/rehearse.rb

@@ -82,7 +82,7 @@ def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: fa
 	offset = prior_records.length
 	slides.each_with_index do |slide, index|
 		relative_path = slide.path
-		headline = extract_headline(slide)
+		headline = slide.title
 		absolute = offset + index + 1
 		total = offset + slides.length
 		
@@ -199,14 +199,6 @@ private
 
 UPDATE_THRESHOLD = 1.0
 
-def extract_headline(slide)
-	body = slide.content["body"]
-	return slide.title unless body && !body.empty?
-	
-	first_line = body.to_commonmark.strip.lines.first.to_s.strip
-	first_line.empty? ? slide.title : first_line
-end
-
 def print_report(records, log_path)
 	planned_total = records.sum{|record| record[:planned]}
 	actual_total = records.sum{|record| record[:actual]}

data/context/animated-diagrams.md

@@ -192,7 +192,7 @@ Use semantic classes and CSS custom properties so that meaning remains separate
 .diagram-node {
   --node-color: var(--accent);
   border: 0.08em solid var(--node-color);
-  background: color-mix(in srgb, var(--node-color) 10%, var(--slide-bg));
+  background: color-mix(in srgb, var(--node-color) 10%, var(--slide-background));
 }
 
 .diagram-node[data-tone="storage"] {

data/context/getting-started.md

@@ -60,11 +60,7 @@ template: title
 duration: 30
 ---
 
-# Title
-
-Welcome to My Talk
-
-# Subtitle
+# Welcome to My Talk
 
 A presentation built with Presently
 
@@ -76,7 +72,7 @@ These are presenter notes — only visible in the presenter view.
 Each slide has three parts:
 
 1. **YAML frontmatter** between `---` markers at the top, specifying the template, duration, and other metadata.
-2. **Content** with Markdown headings that become named sections for the template.
+2. **Content** with an optional H1 title and any template placeholders written as H2 sections.
 3. **Presenter notes** after a `---` separator in the body (optional).
 
 ### Styling Slides
@@ -196,7 +192,7 @@ Templates define the visual layout of each slide. Select a template using the `t
 
 ### Default
 
-A general-purpose content slide. All content without a heading goes into the `body` section.
+A general-purpose content slide. An H1 becomes the slide title and the remaining document becomes its body.
 
 ``` markdown
 ---
@@ -204,6 +200,8 @@ template: default
 duration: 60
 ---
 
+# Key points
+
 - First point
 - Second point
 - Third point
@@ -211,7 +209,7 @@ duration: 60
 
 ### Title
 
-A large title with a subtitle, centered on the slide.
+A large title with a short body, centered on the slide.
 
 ``` markdown
 ---
@@ -219,18 +217,14 @@ template: title
 duration: 30
 ---
 
-# Title
-
-My Presentation Title
-
-# Subtitle
+# My Presentation Title
 
 A subtitle or tagline
 ```
 
 ### Section
 
-A section divider slide with a large heading and accent background.
+A section divider slide with a large heading, optional supporting body, and accent background.
 
 ``` markdown
 ---
@@ -238,9 +232,9 @@ template: section
 duration: 15
 ---
 
-# Heading
+# Part Two
 
-Part Two
+Architecture and design
 ```
 
 ### Two Column
@@ -253,14 +247,18 @@ template: two_column
 duration: 90
 ---
 
-# Left
+# Client and server responsibilities
+
+The application is split across two cooperating environments.
+
+## Left
 
 **Server Side**
 
 - Ruby + Lively
 - WebSocket connections
 
-# Right
+## Right
 
 **Client Side**
 
@@ -277,9 +275,10 @@ A syntax-highlighted code slide with optional focus regions for code walkthrough
 template: code
 duration: 60
 focus: 2-8
-title: Constructor
 ---
 
+# Constructor
+
 ```ruby
 class Presentation
   def initialize
@@ -298,7 +297,7 @@ Create animated walkthroughs by using multiple slides with the same code but dif
 
 ### Statement
 
-A prominent statement or quote, centered on the slide. Supports an optional `# Translation` section.
+A prominent statement or quote, centered on the slide. Supports an optional `## Translation` placeholder.
 
 ``` markdown
 ---
@@ -308,14 +307,14 @@ duration: 30
 
 The best way to predict the future is to create it.
 
-# Translation
+## Translation
 
 未来を予測する最善の方法は、それを創ることである。
 ```
 
 ### Translations
 
-All templates support an optional `# Translation` section. When present, the translation is displayed below the main content in a lighter style. This works with `title`, `section`, `statement`, and `image` templates.
+Templates can extract an optional `## Translation` section and position it independently from the main document. Every standard template displays it separately in a lighter style.
 
 ### Image
 
@@ -329,7 +328,7 @@ duration: 30
 
 ![Architecture diagram](/images/architecture.png)
 
-# Caption
+## Caption
 
 System architecture overview
 ```
@@ -344,11 +343,7 @@ template: diagram
 duration: 60
 ---
 
-# Title
-
-Request lifecycle
-
-# Body
+# Request lifecycle
 
 <div style="display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 2em; width: 80%;">
   <div>Browser</div>
@@ -420,7 +415,20 @@ service "presently" do
 end
 ```
 
-Templates receive a {ruby Presently::TemplateScope} with access to `self.slide` (the {ruby Presently::Slide} instance) and `self.section(name)` for retrieving named content sections.
+Templates receive a {ruby Presently::TemplateScope}. `self.slide_header` renders the semantic H1 title and optional section metadata, while `self.document` renders the remaining slide body. `self.extract(name)` removes an H2 placeholder with that exact heading text from the body and returns its rendered content. Extract placeholders before rendering the remaining document:
+
+``` xrb
+<?r translation = self.extract("Translation") ?>
+#{self.slide_header}
+<div class="slide-body">
+	#{self.document}
+</div>
+<?r if translation ?>
+	<div class="slide-translation">#{translation}</div>
+<?r end ?>
+```
+
+Extraction stops at the next heading of the same or a higher level, so lower-level headings remain inside the extracted fragment. Placeholder names are case-sensitive and must match the heading text exactly. Only placeholders requested by the template are removed; other headings remain ordinary document content.
 
 ## Customizing the Application
 

data/lib/presently/application.rb

@@ -72,10 +72,11 @@ module Presently
 		
 		# Create a Presently page with the presentation-specific stylesheets.
 		# @parameter view [Live::View] The root view for the page.
+		# @parameter interface [Symbol | Nil] The interface-specific stylesheet to load.
 		# @returns [Page] The presentation page.
-		def make_page(view)
+		def make_page(view, interface: nil)
 			stylesheets = controller.presentation.stylesheets.map(&:url)
-			Page.new(title: title, body: view, stylesheets: stylesheets)
+			Page.new(title: title, body: view, interface: interface, stylesheets: stylesheets)
 		end
 		
 		# Add Presently's application routes.
@@ -83,12 +84,12 @@ module Presently
 		def configure_routes(router)
 			router.get("/") do
 				body = resolver.root(HomeView)
-				Page.new(title: title, body: body).call
+				Page.new(title: title, body: body, interface: :home).call
 			end
 			
-			router.get("/display"){make_page(resolver.root(DisplayView)).call}
-			router.get("/presenter"){make_page(resolver.root(PresenterView)).call}
-			router.get("/record"){make_page(resolver.root(RecordingView)).call}
+			router.get("/display"){make_page(resolver.root(DisplayView), interface: :display).call}
+			router.get("/presenter"){make_page(resolver.root(PresenterView), interface: :presenter).call}
+			router.get("/record"){make_page(resolver.root(RecordingView), interface: :recorder).call}
 			
 			router.route("/recordings", methods: ["GET", "HEAD", "PUT"]) do |request|
 				handle_recording(request, request_parameters(request))

data/lib/presently/export.xrb

@@ -4,6 +4,8 @@
 		<meta charset="UTF-8" />
 		
 		<link rel="stylesheet" href="/_static/index.css" type="text/css" />
+		<link rel="stylesheet" href="/_static/slides.css" type="text/css" />
+		<link rel="stylesheet" href="/_static/export.css" type="text/css" />
 		<link rel="stylesheet" href="/_static/custom.css" type="text/css" />
 		<link rel="stylesheet" href="/_components/@socketry/syntax/themes/base/syntax.css" type="text/css" />
 		<?r self.stylesheets.each do |stylesheet| ?>

data/lib/presently/page.rb

@@ -13,8 +13,17 @@ module Presently
 	class Page < Lively::Page
 		ICON = "/_static/icon.png"
 		STYLESHEETS = [
-			{href: "/_static/site.css", media: "screen"}.freeze,
 			{href: "/_static/index.css", media: "screen"}.freeze,
+		].freeze
+		SLIDES_STYLESHEET = {href: "/_static/slides.css", media: "screen"}.freeze
+		INTERFACE_STYLESHEETS = {
+			home: [{href: "/_static/home.css", media: "screen"}.freeze].freeze,
+			display: [SLIDES_STYLESHEET, {href: "/_static/display.css", media: "screen"}.freeze].freeze,
+			presenter: [SLIDES_STYLESHEET, {href: "/_static/presenter.css", media: "screen"}.freeze].freeze,
+			recorder: [SLIDES_STYLESHEET, {href: "/_static/recorder.css", media: "screen"}.freeze].freeze,
+		}.freeze
+		DEFAULT_INTERFACE_STYLESHEETS = INTERFACE_STYLESHEETS.values.flatten.uniq.freeze
+		TRAILING_STYLESHEETS = [
 			{href: "/_static/custom.css", media: "screen"}.freeze,
 			{href: "/_components/@socketry/syntax/themes/base/syntax.css", media: "screen"}.freeze,
 		].freeze
@@ -31,13 +40,16 @@ module Presently
 		# Initialize a new page.
 		# @parameter title [String] The page title.
 		# @parameter body [Live::View | Nil] The Live view to embed in the page.
+		# @parameter interface [Symbol | Nil] The interface-specific stylesheets to load, or all interface stylesheets by default for compatibility.
 		# @parameter stylesheets [Array(String | Hash)] Presentation-specific stylesheets.
-		def initialize(title: "Presently", body: nil, stylesheets: [])
+		def initialize(title: "Presently", body: nil, interface: nil, stylesheets: [])
+			interface_stylesheets = interface ? INTERFACE_STYLESHEETS.fetch(interface) : DEFAULT_INTERFACE_STYLESHEETS
+			
 			super(
 				title: title,
 				body: body,
 				icon: ICON,
-				stylesheets: STYLESHEETS + stylesheets,
+				stylesheets: STYLESHEETS + interface_stylesheets + TRAILING_STYLESHEETS + stylesheets,
 				imports: IMPORTS,
 				modules: MODULES,
 			)

data/lib/presently/playback.xrb

@@ -7,8 +7,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1" />
 		
 		<link rel="icon" type="image/png" href="/_static/icon.png" />
-		<link rel="stylesheet" href="/_static/site.css" type="text/css" media="screen" />
 		<link rel="stylesheet" href="/_static/index.css" type="text/css" media="screen" />
+		<link rel="stylesheet" href="/_static/slides.css" type="text/css" media="screen" />
+		<link rel="stylesheet" href="/_static/playback.css" type="text/css" media="screen" />
 		<link rel="stylesheet" href="/_static/custom.css" type="text/css" media="screen" />
 		<link rel="stylesheet" href="/_components/@socketry/syntax/themes/base/syntax.css" type="text/css" media="screen" />
 		<?r self.stylesheets.each do |stylesheet| ?>

data/lib/presently/slide.rb

@@ -14,13 +14,13 @@ require_relative "stylesheet"
 module Presently
 	# A single slide parsed from a Markdown file.
 	#
-	# Each slide has YAML front_matter for metadata (template, duration, focus), content sections
-	# split by Markdown headings, and optional presenter notes separated by `---`.
+	# Each slide has YAML front_matter for metadata (template, duration, focus), a Markdown
+	# document, and optional presenter notes separated by `---`.
 	class Slide
 		# A fragment of a Markly AST document.
 		#
 		# Wraps a `Markly::Node` of type `:document` and provides rendering helpers.
-		# Used for both content sections and presenter notes so callers can choose
+		# Used for both slide documents 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.
@@ -35,6 +35,13 @@ module Presently
 			# @attribute [Markly::Node] The underlying AST document node.
 			attr :node
 			
+			# Duplicate this fragment and its underlying AST.
+			# @returns [Fragment] An independently mutable copy.
+			def initialize_copy(other)
+				super
+				@node = other.node.dup
+			end
+			
 			# Whether the fragment has no content.
 			# @returns [Boolean]
 			def empty?
@@ -47,6 +54,51 @@ module Presently
 				Markly::Renderer::HTML.new(flags: Markly::UNSAFE, extensions: EXTENSIONS).render(@node)
 			end
 			
+			# Extract the content belonging to a named H2 placeholder.
+			#
+			# The matching heading itself is removed. Following nodes are extracted up
+			# to the next heading of the same or a higher level. Lower-level headings
+			# remain part of the extracted content.
+			# @parameter name [String] The heading name to extract.
+			# @returns [Fragment | Nil] The extracted content, or `nil` when not found.
+			def extract(name)
+				heading = find_heading(name)
+				return unless heading
+				
+				level = heading.header_level
+				fragment = Markly::Node.new(:document)
+				node = heading.next
+				heading.delete
+				
+				while node
+					next_node = node.next
+					break if node.type == :header && node.header_level <= level
+					
+					fragment.append_child(node)
+					node = next_node
+				end
+				
+				Fragment.new(fragment)
+			end
+			
+			# Extract the first heading at the given level, retaining the heading node.
+			# @parameter level [Integer] The Markdown heading level.
+			# @returns [Fragment | Nil] A fragment containing the extracted heading.
+			def extract_heading(level = 1)
+				heading = nil
+				@node.each do |node|
+					if node.type == :header && node.header_level == level
+						heading = node
+						break
+					end
+				end
+				return unless heading
+				
+				fragment = Markly::Node.new(:document)
+				fragment.append_child(heading)
+				Fragment.new(fragment)
+			end
+			
 			# Render the fragment back to CommonMark Markdown.
 			# @returns [String] The CommonMark source.
 			def to_commonmark
@@ -54,6 +106,27 @@ module Presently
 			end
 			
 			alias to_s to_commonmark
+			
+			# Return the plain text of the first heading at the given level.
+			# @parameter level [Integer] The Markdown heading level.
+			# @returns [String | Nil] The heading text, or `nil` when not found.
+			def heading_text(level = 1)
+				@node.each do |node|
+					if node.type == :header && node.header_level == level
+						return node.dup.extract_children.to_plaintext
+					end
+				end
+			end
+			
+			private
+			
+			def find_heading(name)
+				@node.each do |node|
+					return node if node.type == :header && node.header_level == 2 && node.dup.extract_children.to_plaintext == name
+				end
+				
+				nil
+			end
 		end
 		
 		# Parses a Markdown slide file into structured data for {Slide}.
@@ -61,8 +134,17 @@ module Presently
 		# Handles YAML front_matter extraction, presenter note separation, and
 		# Markdown AST construction via Markly.
 		module Parser
+			FLAGS = Markly::UNSAFE | Markly::FRONT_MATTER | Markly::INLINE_CODE_INFO | Markly::HTML_BLOCK_BLANK_LINES
+			
 			module_function
 			
+			# Parse slide Markdown with the standard flags and extensions.
+			# @parameter source [String] The Markdown source.
+			# @returns [Markly::Node] The parsed document.
+			def parse(source)
+				Markly.parse(source, flags: FLAGS, extensions: Fragment::EXTENSIONS)
+			end
+			
 			# Parse the file and return a {Slide}.
 			# @parameter presentation [Presentation] The presentation which owns the slide.
 			# @parameter path [String] The slide path relative to the presentation root.
@@ -72,7 +154,7 @@ module Presently
 				raw = File.read(source_path)
 				
 				# Parse once, with native front matter support.
-				document = Markly.parse(raw, flags: Markly::UNSAFE | Markly::FRONT_MATTER | Markly::INLINE_CODE_INFO | Markly::HTML_BLOCK_BLANK_LINES, extensions: Fragment::EXTENSIONS)
+				document = parse(raw)
 				
 				expand_includes!(document, File.dirname(source_path), presentation.root)
 				rewrite_image_urls!(document, source_path, presentation.root)
@@ -109,14 +191,12 @@ module Presently
 						script_node.delete
 					end
 					
-					content = parse_sections(document)
 					notes = Fragment.new(notes_node)
 				else
-					content = parse_sections(document)
 					notes = nil
 				end
 				
-				Slide.new(presentation, path, front_matter: front_matter, content: content, notes: notes, scripts: scripts)
+				Slide.new(presentation, path, front_matter: front_matter, document: Fragment.new(document), notes: notes, scripts: scripts)
 			end
 			
 			# Extract reusable setup scripts from the expanded slide document.
@@ -169,7 +249,7 @@ module Presently
 				to_replace.each do |paragraph, relative_path|
 					included_path = File.expand_path(relative_path, base_dir)
 					included_raw = File.read(included_path)
-					included_document = Markly.parse(included_raw, flags: Markly::UNSAFE | Markly::FRONT_MATTER | Markly::INLINE_CODE_INFO | Markly::HTML_BLOCK_BLANK_LINES, extensions: Fragment::EXTENSIONS)
+					included_document = parse(included_raw)
 					
 					# Strip front matter from included file if present.
 					front_matter_node = included_document.first_child
@@ -211,31 +291,6 @@ module Presently
 				end
 			end
 			
-			# 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_node = Markly::Node.new(:document)
-				
-				document.each do |node|
-					if node.type == :header
-						sections[current_key] = Fragment.new(current_node) unless current_node.first_child.nil?
-						current_key = node.to_plaintext.strip.downcase.gsub(/\s+/, "_")
-						current_node = Markly::Node.new(:document)
-					else
-						current_node.append_child(node.dup)
-					end
-				end
-				
-				sections[current_key] = Fragment.new(current_node) unless current_node.first_child.nil?
-				
-				sections
-			end
 		end
 		
 		# Load and parse a slide from a Markdown file.
@@ -250,18 +305,16 @@ module Presently
 		# @parameter presentation [Presentation] The presentation which owns the slide.
 		# @parameter path [String] The slide path relative to the presentation root.
 		# @parameter front_matter [Hash | Nil] The parsed YAML front_matter.
-		# @parameter content [Hash(String, Fragment)] Content sections keyed by heading name.
+		# @parameter document [Fragment | Nil] The complete slide document.
 		# @parameter notes [Fragment | Nil] The presenter notes as a Markly AST fragment.
 		# @parameter scripts [Array(String)] JavaScript sources to execute after the slide renders.
-		# @parameter script [String | Nil] A single JavaScript source retained for compatibility.
-		def initialize(presentation, path, front_matter: nil, content: {}, notes: nil, scripts: [], script: nil)
+		def initialize(presentation, path, front_matter: nil, document: nil, notes: nil, scripts: [])
 			@presentation = presentation
 			@path = path
 			@front_matter = front_matter
-			@content = content
+			@document = document || Fragment.new(Markly::Node.new(:document))
 			@notes = notes
 			@scripts = scripts.dup
-			@scripts << script if script
 		end
 		
 		# @attribute [Presentation] The presentation which owns the slide.
@@ -279,8 +332,8 @@ module Presently
 		# @attribute [Hash | Nil] The parsed YAML front_matter.
 		attr :front_matter
 		
-		# @attribute [Hash(String, Fragment)] The content sections keyed by heading name.
-		attr :content
+		# @attribute [Fragment] The complete slide document.
+		attr :document
 		
 		# @attribute [Fragment | Nil] The presenter notes as a Markly AST fragment.
 		attr :notes
@@ -288,14 +341,6 @@ module Presently
 		# @attribute [Array(String)] JavaScript sources to execute after the slide renders on the display.
 		attr :scripts
 		
-		# All JavaScript sources combined into a single string.
-		# @returns [String | Nil] The combined JavaScript, or `nil` when the slide has no scripts.
-		def script
-			return if @scripts.empty?
-			
-			@scripts.join("\n\n")
-		end
-		
 		# The template to use for rendering this slide.
 		# @returns [String] The template name from front_matter, or `"default"`.
 		def template
@@ -309,9 +354,15 @@ module Presently
 		end
 		
 		# The title of this slide.
-		# @returns [String] The title from front_matter, or the filename without extension.
+		# @returns [String] The H1 text, front matter title, or filename without extension.
 		def title
-			@front_matter&.fetch("title", File.basename(@path, ".md")) || File.basename(@path, ".md")
+			@document.heading_text(1) || @front_matter&.fetch("title", nil) || File.basename(@path, ".md")
+		end
+		
+		# The section name for this slide.
+		# @returns [String | Nil] The section from front matter, or `nil` when it was not specified.
+		def section
+			@front_matter&.fetch("section", nil)
 		end
 		
 		# Whether this slide should be skipped in the presentation.

data/lib/presently/slide_renderer.rb

@@ -64,36 +64,75 @@ module Presently
 	
 	# Provides the scope for XRB template rendering.
 	#
-	# Templates access slide content via `self.section(name)` and slide metadata via `self.slide`.
+	# Templates selectively extract placeholders with `self.extract(name)` and render the remainder
+	# with `self.document`.
 	class TemplateScope
 		# Initialize a new template scope for the given slide.
 		# @parameter slide [Slide] The slide being rendered.
 		def initialize(slide)
 			@slide = slide
+			@document = slide.document.dup
+			@heading = @document.extract_heading(1)
+			@extracted = {}
 		end
 		
 		# @attribute [Slide] The slide being rendered.
 		attr :slide
 		
-		# The content sections of the slide.
-		# @returns [Hash(String, String)] Sections keyed by heading name.
-		def content
-			@slide.content
+		# Render the slide body after title and placeholder extraction.
+		# @returns [XRB::MarkupString] The remaining document as HTML.
+		def document
+			markup(@document)
 		end
 		
-		# Whether the named content section exists and has content.
-		# @parameter name [String] The section name (derived from the Markdown heading).
-		# @returns [Boolean]
-		def section?(name)
-			fragment = @slide.content[name]
-			fragment && !fragment.empty?
+		# Extract and render a named H2 placeholder from this render's document.
+		#
+		# Extraction is cached so a template can reference a placeholder more than
+		# once without mutating the document repeatedly.
+		# @parameter name [String] The heading name to extract.
+		# @returns [XRB::MarkupString | Nil] The extracted HTML, or `nil` when absent.
+		def extract(name)
+			fragment = extract_fragment(name)
+			return unless fragment && !fragment.empty?
+			
+			markup(fragment)
+		end
+		
+		# Render the slide header using semantic markup.
+		# @returns [XRB::MarkupString] The rendered header, or an empty string when no metadata is present.
+		def slide_header
+			section = @slide.section
+			
+			return XRB::MarkupString.raw("") unless present?(section) || @heading
+			
+			builder = XRB::Builder.new
+			builder.tag(:header, class: "slide-header") do
+				if present?(section)
+					builder.tag(:div, class: "slide-section-heading") do
+						builder.text(section.to_s)
+					end
+				end
+				
+				builder.raw(@heading.to_html) if @heading
+			end
+			
+			XRB::MarkupString.raw(builder.to_s)
+		end
+		
+		private
+		
+		def extract_fragment(name)
+			return @extracted[name] if @extracted.key?(name)
+			
+			@extracted[name] = @document.extract(name)
+		end
+		
+		def markup(fragment)
+			XRB::MarkupString.raw(fragment&.to_html || "")
 		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]&.to_html || "")
+		def present?(value)
+			value && !value.to_s.empty?
 		end
 	end
 end