presently 0.16.0 → 0.17.0

data/lib/presently/display_view.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "live"
+require_relative "slide_view"
 require_relative "slide_renderer"
 
 module Presently
@@ -11,15 +11,15 @@ module Presently
 	#
 	# Connects to the {PresentationController} as a listener and updates
 	# whenever the slide changes. Pushes the current state on WebSocket reconnect.
-	class DisplayView < Live::View
+	class DisplayView < SlideView
 		# Initialize a new display view.
 		# @parameter id [String] The unique element identifier.
 		# @parameter data [Hash] The element data attributes.
-		# @parameter controller [PresentationController | Nil] The shared presentation controller.
-		def initialize(id = Live::Element.unique_id, data = {}, controller: nil)
+		# @parameter controller [PresentationController] The shared presentation controller.
+		def initialize(id, data, controller:)
 			super(id, data)
 			@controller = controller
-			@slide_renderer = SlideRenderer.new(css_class: "slide current", templates: controller&.templates)
+			@slide_renderer = SlideRenderer.new(css_class: "slide current", templates: controller.templates)
 		end
 		
 		# Bind this view to a page and register as a listener.
@@ -28,7 +28,7 @@ module Presently
 		def bind(page)
 			super
 			@controller.add_listener(self)
-			self.update!
+			self.render_slide!(transition: @controller.current_slide&.transition)
 		end
 		
 		# Close this view and unregister as a listener.
@@ -39,7 +39,7 @@ module Presently
 		
 		# Called by the controller when the slide changes.
 		def slide_changed!
-			self.update!
+			self.render_slide!(transition: @controller.current_slide&.transition)
 		end
 		
 		# Handle an event from the client.

data/lib/presently/environment/application.rb

@@ -30,6 +30,18 @@ module Presently
 				[File.expand_path("templates", self.root)].select{|d| File.directory?(d)}
 			end
 			
+			# The root directory where per-slide narration recordings are stored.
+			# @returns [String] Absolute path to the recording root.
+			def recordings_root
+				File.expand_path("audio", self.root)
+			end
+			
+			# The root directory containing normalized narration used for playback.
+			# @returns [String] Absolute path to the playback recording root.
+			def playback_recordings_root
+				File.expand_path("audio-normalized", self.root)
+			end
+			
 			# The application class to use.
 			# @returns [Class] The Presently application class.
 			def application
@@ -42,6 +54,8 @@ module Presently
 				application = self.application
 				slides_root = self.slides_root
 				templates_roots = self.templates_roots
+				recordings_root = self.recordings_root
+				playback_recordings_root = self.playback_recordings_root
 				root = self.root
 				
 				::Protocol::HTTP::Middleware.build do |builder|
@@ -56,7 +70,9 @@ module Presently
 					
 					builder.use application,
 						slides_root: slides_root,
-						templates_roots: templates_roots
+						templates_roots: templates_roots,
+						recordings_root: recordings_root,
+						playback_recordings_root: playback_recordings_root
 				end
 			end
 		end

data/lib/presently/export.rb

@@ -3,7 +3,6 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "uri"
 require "xrb/template"
 require "xrb/markup"
 
@@ -37,24 +36,22 @@ module Presently
 		
 		TEMPLATE = XRB::Template.load_file(File.expand_path("export.xrb", __dir__))
 		
-		# Parse export options from a URL query string.
-		# @parameter query [String | Nil] The raw query string, e.g. `"notes=true&speaker=true"`.
+		# Extract export options from decoded query parameters.
+		# @parameter parameters [Hash] The decoded query parameters.
 		# @returns [Hash] Options suitable for passing to {.new}.
-		def self.options_from_query(query)
-			return {} unless query
-			
-			params = URI.decode_www_form(query).to_h
+		def self.options_from_parameters(parameters)
+			return {} if parameters.empty?
 			
 			page_size = PageSize.new(
-				slide_width_px:  (params["slide_width_px"]  || PageSize::DEFAULT.slide_width_px).to_i,
-				slide_height_px: (params["slide_height_px"] || PageSize::DEFAULT.slide_height_px).to_i,
-				notes_height_px: (params["notes_height_px"] || PageSize::DEFAULT.notes_height_px).to_i,
+				slide_width_px:  (parameters["slide_width_px"]  || PageSize::DEFAULT.slide_width_px).to_i,
+				slide_height_px: (parameters["slide_height_px"] || PageSize::DEFAULT.slide_height_px).to_i,
+				notes_height_px: (parameters["notes_height_px"] || PageSize::DEFAULT.notes_height_px).to_i,
 			)
 			
 			{
-				notes:     params["notes"]   != "false",
-				speaker:   params["speaker"] != "false",
-				timing:    params["timing"]  != "false",
+				notes:     parameters["notes"]   != "false",
+				speaker:   parameters["speaker"] != "false",
+				timing:    parameters["timing"]  != "false",
 				page_size: page_size,
 			}
 		end
@@ -85,6 +82,11 @@ module Presently
 		# @attribute [Boolean] Whether slide timing is included.
 		attr :timing
 		
+		# @returns [Array(Stylesheet)] The ordered presentation stylesheets.
+		def stylesheets
+			@presentation.stylesheets
+		end
+		
 		# Render a single slide to an HTML string.
 		# @parameter slide [Slide] The slide to render.
 		# @returns [XRB::MarkupString]

data/lib/presently/export.xrb

@@ -6,10 +6,14 @@
 		<link rel="stylesheet" href="/_static/index.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| ?>
+		<link rel="stylesheet" href="#{stylesheet.url}" type="text/css" />
+		<?r end ?>
 		
 		<script type="importmap">
 		{
 			"imports": {
+				"@socketry/presently": "/_components/@socketry/presently/Presently.js",
 				"@socketry/syntax": "/_components/@socketry/syntax/Syntax.js"
 			}
 		}

data/lib/presently/home_view.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "live"
+
+module Presently
+	# The home view which links to each presentation interface.
+	class HomeView < Live::View
+		INTERFACES = [
+			{
+				href: "/display",
+				title: "Audience Display",
+				description: "Show the synchronized presentation full-screen for the audience.",
+			},
+			{
+				href: "/presenter",
+				title: "Presenter Console",
+				description: "Control the presentation with speaker notes, timing, and slide previews.",
+			},
+			{
+				href: "/record",
+				title: "Narration Recorder",
+				description: "Record, review, and save narration for each slide.",
+			},
+			{
+				href: "/playback",
+				title: "Narrated Playback",
+				description: "Review the complete presentation with its recorded narration.",
+			},
+		].map(&:freeze).freeze
+		
+		# Initialize the home view.
+		# @parameter id [String] The unique element identifier.
+		# @parameter data [Hash] The element data attributes.
+		# @parameter controller [PresentationController] The shared presentation controller.
+		def initialize(id, data, controller:)
+			super(id, data)
+		end
+		
+		# Render links to the available presentation interfaces.
+		# @parameter builder [XRB::Builder] The HTML builder.
+		def render(builder)
+			builder.tag(:main, class: "home") do
+				builder.tag(:div, class: "home-heading") do
+					builder.tag(:p, class: "home-kicker"){builder.text("Presently")}
+					builder.tag(:h1){builder.text("Presentation interfaces")}
+					builder.tag(:p, class: "home-introduction") do
+						builder.text("Choose an interface to present, control, record, or review your presentation.")
+					end
+				end
+				
+				builder.tag(:nav, class: "home-interfaces", "aria-label": "Presentation interfaces") do
+					INTERFACES.each do |interface|
+						builder.tag(:a, class: "home-interface", href: interface[:href]) do
+							builder.tag(:strong){builder.text(interface[:title])}
+							builder.tag(:span){builder.text(interface[:description])}
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/presently/page.rb

@@ -3,36 +3,43 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "xrb/template"
+require "lively/page"
 
 module Presently
 	# The HTML page shell for a Presently view.
 	#
-	# Renders the initial HTML page with the import map, stylesheets, and the
-	# embedded Live view component. Uses a custom XRB template that includes
-	# Presently's assets (syntax highlighting, etc.).
-	class Page
-		# The compiled XRB template for the page shell.
-		TEMPLATE = XRB::Template.load_file(File.expand_path("page.xrb", __dir__))
+	# Configures Lively's generic page with Presently's assets and embedded Live
+	# view component.
+	class Page < Lively::Page
+		ICON = "/_static/icon.png"
+		STYLESHEETS = [
+			{href: "/_static/site.css", media: "screen"}.freeze,
+			{href: "/_static/index.css", media: "screen"}.freeze,
+			{href: "/_static/custom.css", media: "screen"}.freeze,
+			{href: "/_components/@socketry/syntax/themes/base/syntax.css", media: "screen"}.freeze,
+		].freeze
+		IMPORTS = {
+			"live" => "/_components/@socketry/live/Live.js",
+			"live-audio" => "/_components/@socketry/live-audio/Live/Audio.js",
+			"morphdom" => "/_components/morphdom/morphdom-esm.js",
+			"@socketry/presently" => "/_components/@socketry/presently/Presently.js",
+			"@socketry/syntax" => "/_components/@socketry/syntax/Syntax.js",
+		}.freeze
+		MODULES = ["/application.js"].freeze
 		
 		# Initialize a new page.
 		# @parameter title [String] The page title.
 		# @parameter body [Live::View | Nil] The Live view to embed in the page.
-		def initialize(title: "Presently", body: nil)
-			@title = title
-			@body = body
-		end
-		
-		# @attribute [String] The page title.
-		attr :title
-		
-		# @attribute [Live::View | Nil] The Live view to embed.
-		attr :body
-		
-		# Render the page to an HTML string.
-		# @returns [String] The rendered HTML.
-		def call
-			TEMPLATE.to_string(self)
+		# @parameter stylesheets [Array(String | Hash)] Presentation-specific stylesheets.
+		def initialize(title: "Presently", body: nil, stylesheets: [])
+			super(
+				title: title,
+				body: body,
+				icon: ICON,
+				stylesheets: STYLESHEETS + stylesheets,
+				imports: IMPORTS,
+				modules: MODULES,
+			)
 		end
 	end
 end

data/lib/presently/playback.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "xrb/template"
+
+require_relative "slide_renderer"
+
+module Presently
+	# Renders an isolated, narrated presentation for review and video capture.
+	#
+	# Unlike the live display, playback owns its current slide entirely in the
+	# browser and does not update the shared presentation controller.
+	class Playback
+		TEMPLATE = XRB::Template.load_file(File.expand_path("playback.xrb", __dir__))
+		
+		# Extract playback options from decoded query parameters.
+		# @parameter parameters [Hash] The decoded query parameters.
+		# @returns [Hash] Options suitable for passing to {.new}.
+		def self.options_from_parameters(parameters)
+			{
+				autoplay: parameters["autoplay"] == "true",
+				controls: parameters["controls"] != "false",
+			}
+		end
+		
+		# @parameter presentation [Presentation] The presentation to play.
+		# @parameter recording_urls [Array(String | Nil)] Narration URL for each slide.
+		# @parameter autoplay [Boolean] Whether playback should begin when ready.
+		# @parameter controls [Boolean] Whether playback controls should be visible.
+		def initialize(presentation:, recording_urls:, autoplay: false, controls: true)
+			@presentation = presentation
+			@recording_urls = recording_urls
+			@autoplay = autoplay
+			@controls = controls
+			@renderer = SlideRenderer.new(templates: presentation.templates)
+		end
+		
+		attr :autoplay
+		attr :controls
+		
+		# @returns [Array(Stylesheet)] The ordered presentation stylesheets.
+		def stylesheets
+			@presentation.stylesheets
+		end
+		
+		# @returns [Array(Slide)] The slides in playback order.
+		def slides
+			@presentation.slides
+		end
+		
+		# @returns [String | Nil] The narration URL for a slide index.
+		def recording_url(index)
+			@recording_urls[index]
+		end
+		
+		# Render one slide as HTML.
+		# @parameter slide [Slide] The slide to render.
+		# @returns [XRB::MarkupString]
+		def render_slide(slide)
+			@renderer.render_to_html(slide)
+		end
+		
+		# Render the complete playback page.
+		# @returns [String]
+		def call
+			TEMPLATE.to_string(self)
+		end
+	end
+end

data/lib/presently/playback.xrb

@@ -0,0 +1,59 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<title>Presently Playback</title>
+		
+		<meta charset="UTF-8" />
+		<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/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| ?>
+		<link rel="stylesheet" href="#{stylesheet.url}" type="text/css" media="screen" />
+		<?r end ?>
+		
+		<script type="importmap">
+		{
+			"imports": {
+				"@socketry/presently": "/_components/@socketry/presently/Presently.js",
+				"@socketry/syntax": "/_components/@socketry/syntax/Syntax.js"
+			}
+		}
+		</script>
+		
+		<script type="module" src="/playback.js"></script>
+	</head>
+	
+	<body class="playback" data-autoplay="#{self.autoplay}" data-controls="#{self.controls}">
+		<main class="playback-stage">
+			<?r self.slides.each_with_index do |slide, index| ?>
+			<div class="playback-frame" data-index="#{index}" data-transition="#{slide.transition}" data-duration="#{slide.duration}"<?r if index != 0 ?> hidden<?r end ?>>
+				#{self.render_slide(slide)}
+			</div>
+			<?r end ?>
+		</main>
+		
+		<div class="playback-audio" hidden>
+			<?r self.slides.each_with_index do |slide, index| ?>
+				<?r if recording_url = self.recording_url(index) ?>
+				<audio data-index="#{index}" preload="auto" src="#{recording_url}"></audio>
+				<?r end ?>
+			<?r end ?>
+		</div>
+		
+		<div class="playback-start-screen">
+			<button class="playback-start" type="button" disabled>▶ Start presentation</button>
+			<p class="playback-status">Preparing presentation…</p>
+		</div>
+		
+		<nav class="playback-controls" aria-label="Playback controls">
+			<button class="playback-previous" type="button" title="Previous slide">◀</button>
+			<button class="playback-toggle" type="button" title="Play or pause">▶</button>
+			<button class="playback-next" type="button" title="Next slide">▶|</button>
+			<span class="playback-counter">1 / #{self.slides.length}</span>
+		</nav>
+	</body>
+</html>

data/lib/presently/presentation.rb

@@ -4,6 +4,7 @@
 # Copyright, 2026, by Samuel Williams.
 
 require_relative "slide"
+require_relative "stylesheet"
 require_relative "templates"
 
 module Presently
@@ -28,6 +29,7 @@ module Presently
 			@root = File.expand_path(root)
 			@templates = templates
 			@slides = load_slides
+			@stylesheets = Stylesheet.discover(@root, @slides)
 		end
 		
 		# @attribute [String] The absolute root directory containing slide files.
@@ -36,6 +38,9 @@ module Presently
 		# @attribute [Array(Slide)] The ordered list of slides.
 		attr :slides
 		
+		# @attribute [Array(Stylesheet)] The ordered presentation stylesheets.
+		attr :stylesheets
+		
 		# @attribute [Templates] The template resolver.
 		attr :templates
 		

data/lib/presently/presenter_view.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "live"
+require_relative "slide_view"
 require_relative "slide_renderer"
 require_relative "editor"
 
@@ -12,16 +12,16 @@ module Presently
 	#
 	# Shows the current slide, next slide preview, presenter notes, timing controls,
 	# and pacing indicators. Updates the timing display every second via a background task.
-	class PresenterView < Live::View
+	class PresenterView < SlideView
 		# Initialize a new presenter view.
 		# @parameter id [String] The unique element identifier.
 		# @parameter data [Hash] The element data attributes.
-		# @parameter controller [PresentationController | Nil] The shared presentation controller.
-		def initialize(id = Live::Element.unique_id, data = {}, controller: nil)
+		# @parameter controller [PresentationController] The shared presentation controller.
+		def initialize(id, data, controller:)
 			super(id, data)
 			@controller = controller
 			@clock_task = nil
-			@preview_renderer = SlideRenderer.new(css_class: "slide preview-slide", templates: controller&.templates)
+			@preview_renderer = SlideRenderer.new(css_class: "slide preview-slide", templates: controller.templates)
 		end
 		
 		# Bind this view to a page and start the timing update loop.
@@ -48,7 +48,7 @@ module Presently
 		
 		# Called by the controller when the slide changes.
 		def slide_changed!
-			self.update!
+			self.render_slide!
 		end
 		
 		# Push an update to just the timing section.

data/lib/presently/recording_view.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "editor"
+require_relative "slide_view"
+require_relative "slide_renderer"
+
+module Presently
+	# A dedicated interface for recording one narration track per slide.
+	#
+	# Recording is intentionally separate from {PresenterView}: presenting is a
+	# live performance interface, while recording is an authoring workflow with
+	# retakes, playback, and explicit saving.
+	class RecordingView < SlideView
+		# Initialize a recording view.
+		# @parameter id [String] The unique element identifier.
+		# @parameter data [Hash] The element data attributes.
+		# @parameter controller [PresentationController] The shared presentation controller.
+		def initialize(id, data, controller:)
+			super(id, data)
+			@controller = controller
+			@slide_renderer = SlideRenderer.new(css_class: "slide recording-slide", templates: controller.templates)
+		end
+		
+		# Bind this view to a page and register for slide changes.
+		# @parameter page [Live::Page] The page this view is bound to.
+		def bind(page)
+			super
+			@controller.add_listener(self)
+		end
+		
+		# Close this view and unregister it from the controller.
+		def close
+			@controller.remove_listener(self)
+			super
+		end
+		
+		# Update the recording interface when the current slide changes.
+		def slide_changed!
+			self.render_slide!
+		end
+		
+		# Handle navigation events from the recording interface.
+		# @parameter event [Hash] The forwarded browser event.
+		def handle(event)
+			case event.dig(:detail, :action)
+			when "next"
+				@controller.advance!
+			when "previous"
+				@controller.retreat!
+			when "reload"
+				@controller.reload!
+			when "jump"
+				if index = event.dig(:detail, :index)
+					@controller.go_to(index.to_i)
+				end
+			end
+		end
+		
+		# Generate an editor URL for the given file path.
+		# @parameter path [String] The file path.
+		# @parameter line [Integer] The line number.
+		# @returns [String | Nil]
+		def editor_url_for(path, line = 1)
+			Editor.url_for(path, line)
+		end
+		
+		# Render the recording interface.
+		# @parameter builder [XRB::Builder] The HTML builder.
+		def render(builder)
+			slide = @controller.current_slide
+			return unless slide
+			
+			index = @controller.current_index
+			recording_url = "/recordings?index=#{index}"
+			
+			builder.tag(:div, class: "recorder") do
+				render_navigation(builder, slide)
+				
+				builder.tag(:div, class: "recording-workspace") do
+					builder.tag(:div, class: "recording-preview") do
+						@slide_renderer.render(builder, slide)
+					end
+					
+					builder.tag(:aside, class: "recording-sidebar") do
+						builder.tag(:section, class: "recording-panel") do
+							builder.tag(:h2){builder.text("Narration")}
+							builder.tag(:p){builder.text("Record, review, and save one audio track for this slide.")}
+							
+							builder.tag("presently-recorder",
+								id: "presently-recorder-#{index}",
+								"data-recording-url": recording_url
+							) do
+								builder.tag(:div, class: "recording-actions") do
+									builder.tag(:button, class: "recording-toggle", type: "button"){builder.text("● Record")}
+									builder.tag(:button, class: "recording-save", type: "button", disabled: true){builder.text("Save")}
+									builder.tag(:span, class: "recording-indicator", "aria-hidden": "true"){}
+									builder.tag(:span, class: "recording-time"){builder.text("0:00")}
+								end
+								
+								builder.tag(:audio, class: "recording-playback", controls: true, preload: "metadata", hidden: true){}
+								builder.tag(:p, class: "recording-status", role: "status"){builder.text("Checking for an existing recording…")}
+							end
+						end
+						
+						builder.tag(:section, class: "recording-notes") do
+							builder.tag(:h2){builder.text("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
+						end
+					end
+				end
+			end
+		end
+		
+		private
+		
+		# Render navigation controls for the recording interface.
+		# @parameter builder [XRB::Builder] The HTML builder.
+		# @parameter slide [Slide] The current slide.
+		def render_navigation(builder, slide)
+			builder.tag(:div, class: "controls recording-navigation") do
+				builder.tag(:button, onClick: forward_event(action: "previous")){builder.text("← Previous")}
+				
+				builder.tag(:span, class: "slide-info") do
+					builder.text("Slide #{@controller.current_index + 1} of #{@controller.slide_count} · ")
+					builder.tag(:code, class: "slide-path"){builder.text(slide.path)}
+					
+					if editor_url = editor_url_for(slide.source_path)
+						builder.tag(:a, href: editor_url, class: "edit-link"){builder.text("✎")}
+					end
+				end
+				
+				builder.tag(:button, onClick: forward_event(action: "next")){builder.text("Next →")}
+				
+				markers = @controller.slides.each_with_index.filter_map do |candidate, index|
+					[index, candidate.marker] if candidate.marker
+				end
+				
+				unless markers.empty?
+					builder.tag(:select, class: "jump-to", "data-live-id": @id) do
+						builder.tag(:option, value: "", disabled: true, selected: true){builder.text("Jump to…")}
+						markers.each do |index, label|
+							builder.tag(:option, value: index){builder.text(label)}
+						end
+					end
+				end
+				
+				builder.tag(:button, onClick: forward_event(action: "reload"), class: "reload"){builder.text("↻ Reload")}
+			end
+		end
+	end
+end