presently 0.1.0

data/lib/presently/presenter_view.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "live"
+require_relative "slide_view"
+
+module Presently
+	# The presenter-facing view with notes, timing, and slide previews.
+	#
+	# 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
+		# 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)
+			super(id, data)
+			@controller = controller
+			@clock_task = nil
+		end
+		
+		# Bind this view to a page and start the timing update loop.
+		# @parameter page [Live::Page] The page this view is bound to.
+		def bind(page)
+			super
+			@controller.add_listener(self)
+			
+			# Update only the timing section every second.
+			@clock_task = Async do
+				while true
+					update_timing!
+					sleep 1
+				end
+			end
+		end
+		
+		# Close this view and stop the timing update loop.
+		def close
+			@clock_task&.stop
+			@controller.remove_listener(self)
+			super
+		end
+		
+		# Called by the controller when the slide changes.
+		def slide_changed!
+			self.update!
+		end
+		
+		# Push an update to just the timing section.
+		def update_timing!
+			replace(".timing") do |builder|
+				render_timing(builder, @controller.current_slide)
+			end
+		end
+		
+		# Handle an event from the client.
+		# @parameter event [Hash] The event data with `:detail` containing the action.
+		def handle(event)
+			action = event.dig(:detail, :action)
+			
+			case action
+			when "next"
+				@controller.advance!
+			when "previous"
+				@controller.retreat!
+			when "pause"
+				if !@controller.clock.started?
+					@controller.clock.start!
+				elsif @controller.clock.paused?
+					@controller.clock.resume!
+				else
+					@controller.clock.pause!
+				end
+				@controller.save_state!
+			when "reset"
+				@controller.reset_timer!
+			when "reload"
+				@controller.reload!
+			when "jump"
+				if index = event.dig(:detail, :index)
+					@controller.go_to(index.to_i)
+				end
+			end
+		end
+		
+		# Render the timing bar with controls, elapsed/remaining time, and pacing.
+		# @parameter builder [XRB::Builder] The HTML builder.
+		# @parameter slide [Slide | Nil] The current slide.
+		def render_timing(builder, slide)
+			progress = (@controller.slide_progress * 100).round(1)
+			builder.tag(:div, class: "timing", style: "--slide-progress: #{progress}%") do
+				pacing = @controller.pacing
+				pacing_class = case pacing
+				when :behind then "behind"
+				when :ahead then "ahead"
+				else "on-time"
+				end
+				
+				builder.tag(:div, class: "timing-info #{pacing_class}") do
+					builder.tag(:button,
+						class: "pause-button",
+						onClick: forward_event(action: "pause")
+					) do
+						label = if !@controller.clock.started?
+							"▶ Start"
+						elsif @controller.clock.paused?
+							"▶ Resume"
+						else
+							"⏸ Pause"
+						end
+						builder.text(label)
+					end
+					
+					builder.tag(:button,
+						class: "pause-button",
+						onClick: forward_event(action: "reset")
+					) do
+						builder.text("↺ Reset")
+					end
+					
+					builder.tag(:span, class: "elapsed") do
+						builder.text("Elapsed: #{format_duration(@controller.clock.elapsed)}")
+					end
+					
+					builder.tag(:span, class: "remaining") do
+						builder.text("Remaining: #{format_duration(@controller.time_remaining)}")
+					end
+					
+					builder.tag(:span, class: "pacing-indicator") do
+						indicator = case pacing
+						when :behind then "⏩ Speed up"
+						when :ahead then "⏪ Slow down"
+						else "✓ On time"
+						end
+						builder.text(indicator)
+					end
+					
+					if slide
+						builder.tag(:span, class: "slide-duration") do
+							builder.text("Slide: #{format_duration(slide.duration)}")
+						end
+					end
+				end
+			end
+		end
+		
+		# Format a duration in seconds as `M:SS`.
+		# @parameter seconds [Numeric] The duration in seconds.
+		# @returns [String] The formatted duration string.
+		def format_duration(seconds)
+			seconds = seconds.to_i
+			minutes = seconds / 60
+			secs = seconds % 60
+			format("%d:%02d", minutes, secs)
+		end
+		
+		# Render the full presenter view.
+		# @parameter builder [XRB::Builder] The HTML builder.
+		def render(builder)
+			slide = @controller.current_slide
+			next_slide = @controller.next_slide
+			
+			builder.tag(:div, class: "presenter") do
+				# Controls bar
+				builder.tag(:div, class: "controls") do
+					builder.tag(:button,
+						onClick: forward_event(action: "previous")
+					) do
+						builder.text("← Previous")
+					end
+					
+					builder.tag(:span, class: "slide-info") do
+						builder.text("Slide #{@controller.current_index + 1} of #{@controller.slide_count}")
+					end
+					
+					builder.tag(:button,
+						onClick: forward_event(action: "next")
+					) do
+						builder.text("Next →")
+					end
+					
+					# Jump-to dropdown for marked slides
+					markers = []
+					@controller.slides.each_with_index do |s, i|
+						if s.marker
+							markers << [i, s.marker]
+						end
+					end
+					
+					unless markers.empty?
+						builder.tag(:select,
+							class: "jump-to",
+							onChange: "live.forwardEvent(#{JSON.dump(@id)}, event, {action: 'jump', index: parseInt(this.value)}); this.value = '';"
+						) do
+							builder.tag(:option, value: "", disabled: true, selected: true) do
+								builder.text("Jump to…")
+							end
+							
+							markers.each do |index, label|
+								builder.tag(:option, value: index) do
+									builder.text(label)
+								end
+							end
+						end
+					end
+					
+					builder.tag(:button,
+						onClick: forward_event(action: "reload"),
+						class: "reload"
+					) do
+						builder.text("↻ Reload")
+					end
+				end
+				
+				# Slide previews
+				builder.tag(:div, class: "previews") do
+					# Current slide
+					builder.tag(:div, class: "preview current-preview") do
+						builder.tag(:h3){builder.text("Current")}
+						builder.tag(:div, class: "preview-frame") do
+							if slide
+								renderer = SlideView.new(css_class: "slide preview-slide", controller: @controller)
+								renderer.render_slide(builder, slide)
+							end
+						end
+					end
+					
+					# Next slide
+					builder.tag(:div, class: "preview next-preview") do
+						builder.tag(:h3){builder.text("Next")}
+						builder.tag(:div, class: "preview-frame") do
+							if next_slide
+								renderer = SlideView.new(css_class: "slide preview-slide", controller: @controller)
+								renderer.render_slide(builder, next_slide)
+							else
+								builder.tag(:div, class: "no-slide") do
+									builder.text("End of presentation")
+								end
+							end
+						end
+					end
+				end
+				
+				# Timing
+				render_timing(builder, slide)
+				
+				# Presenter notes
+				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)
+						else
+							builder.tag(:p, class: "no-notes"){builder.text("No presenter notes for this slide.")}
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/presently/slide.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "yaml"
+require "markly"
+
+module Presently
+	# A single slide parsed from a Markdown file.
+	#
+	# Each slide has YAML frontmatter for metadata (template, duration, focus), content sections
+	# split by Markdown headings, and optional presenter notes separated by `---`.
+	class Slide
+		# Initialize a new slide by parsing the given Markdown file.
+		# @parameter path [String] The file path to the Markdown slide.
+		def initialize(path)
+			@path = path
+			@frontmatter = nil
+			@content = nil
+			@notes = nil
+			
+			parse!
+		end
+		
+		# @attribute [String] The file path of the slide.
+		attr :path
+		
+		# @attribute [Hash | Nil] The parsed YAML frontmatter.
+		attr :frontmatter
+		
+		# @attribute [Hash(String, String)] The content sections keyed by heading name.
+		attr :content
+		
+		# @attribute [String | Nil] The rendered HTML presenter notes.
+		attr :notes
+		
+		# The template to use for rendering this slide.
+		# @returns [String] The template name from frontmatter, or `"default"`.
+		def template
+			@frontmatter&.fetch("template", "default") || "default"
+		end
+		
+		# The expected duration of this slide in seconds.
+		# @returns [Integer] The duration from frontmatter, or `60`.
+		def duration
+			@frontmatter&.fetch("duration", 60) || 60
+		end
+		
+		# The title of this slide.
+		# @returns [String] The title from frontmatter, or the filename without extension.
+		def title
+			@frontmatter&.fetch("title", File.basename(@path, ".md")) || File.basename(@path, ".md")
+		end
+		
+		# The navigation marker for this slide, used in the presenter's jump-to dropdown.
+		# @returns [String | Nil] The marker label, or `nil` if not marked.
+		def marker
+			@frontmatter&.fetch("marker", nil)
+		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.
+		def transition
+			@frontmatter&.fetch("transition", nil)
+		end
+		
+		# The line range to focus on for code slides.
+		# @returns [Array(Integer, Integer) | Nil] The `[start, end]` line numbers (1-based), or `nil`.
+		def focus
+			if range = @frontmatter&.fetch("focus", nil)
+				parts = range.to_s.split("-").map(&:to_i)
+				parts.length == 2 ? parts : nil
+			end
+		end
+		
+		private
+		
+		# Parse the Markdown file into frontmatter, content sections, and notes.
+		def parse!
+			raw = File.read(@path)
+			
+			# Extract YAML frontmatter:
+			if raw.start_with?("---\n")
+				parts = raw.split("---\n", 3)
+				if parts.length >= 3
+					@frontmatter = YAML.safe_load(parts[1])
+					body = parts[2]
+				else
+					body = raw
+				end
+			else
+				body = raw
+			end
+			
+			# Split content and presenter notes (notes come after "---" on its own line):
+			if body.include?("\n---\n")
+				content_part, notes_part = body.split("\n---\n", 2)
+				@content = parse_sections(content_part.strip)
+				@notes = render_markdown(notes_part.strip)
+			else
+				@content = parse_sections(body.strip)
+				@notes = nil
+			end
+		end
+		
+		# Parse content into sections based on Markdown headings.
+		# Each heading becomes a named key for the template.
+		# @parameter text [String] The Markdown content to parse.
+		# @returns [Hash(String, String)] Sections keyed by heading name, with rendered HTML values.
+		def parse_sections(text)
+			sections = {}
+			current_key = "body"
+			current_content = []
+			
+			text.each_line do |line|
+				if line.match?(/\A#+\s+/)
+					# Save previous section:
+					unless current_content.empty?
+						sections[current_key] = render_markdown(current_content.join)
+					end
+					
+					# Extract heading text as the key:
+					heading_text = line.sub(/\A#+\s+/, "").strip.downcase.gsub(/\s+/, "_")
+					current_key = heading_text
+					current_content = []
+				else
+					current_content << line
+				end
+			end
+			
+			# Save last section:
+			unless current_content.empty?
+				sections[current_key] = render_markdown(current_content.join)
+			end
+			
+			sections
+		end
+		
+		# Render Markdown text to HTML.
+		# @parameter text [String] The Markdown text.
+		# @returns [String] The rendered HTML.
+		def render_markdown(text)
+			return "" if text.nil? || text.empty?
+			Markly.render_html(text, flags: Markly::UNSAFE)
+		end
+	end
+end

data/lib/presently/slide_view.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "live"
+require "xrb/template"
+require "xrb/markup"
+
+module Presently
+	# The default directory containing bundled slide templates.
+	DEFAULT_TEMPLATES_ROOT = File.expand_path("../../templates", __dir__)
+	
+	# Renders a single slide using its XRB template.
+	#
+	# Loads templates from the configured templates root and renders slides
+	# by passing their content sections to the template via {TemplateScope}.
+	class SlideView < Live::View
+		# Initialize a new slide view.
+		# @parameter id [String] The unique element identifier.
+		# @parameter data [Hash] The element data attributes.
+		# @parameter css_class [String] The CSS class for the slide container.
+		# @parameter controller [PresentationController | Nil] The controller to get the templates root from.
+		def initialize(id = Live::Element.unique_id, data = {}, css_class: "slide", controller: nil)
+			super(id, data)
+			@css_class = css_class
+			@templates_root = controller&.templates_root || DEFAULT_TEMPLATES_ROOT
+			@templates = {}
+		end
+		
+		# Load and cache a template by name.
+		# @parameter name [String] The template name (without extension).
+		# @returns [XRB::Template] The loaded template.
+		def template_for(name)
+			@templates[name] ||= begin
+				path = File.join(@templates_root, "#{name}.xrb")
+				XRB::Template.load_file(path)
+			end
+		end
+		
+		# Render a slide using its template into the builder.
+		# @parameter builder [XRB::Builder] The HTML builder.
+		# @parameter slide [Slide] The slide to render.
+		# @parameter extra_class [String | Nil] An additional CSS class for the container.
+		def render_slide(builder, slide, extra_class: nil)
+			return unless slide
+			
+			template = template_for(slide.template)
+			scope = TemplateScope.new(slide)
+			html = template.to_string(scope)
+			
+			classes = [@css_class, extra_class].compact.join(" ")
+			builder.tag(:div, class: classes, data: {template: slide.template}) do
+				builder.raw(html)
+			end
+		end
+		
+		# Render the current slide.
+		# @parameter builder [XRB::Builder] The HTML builder.
+		def render(builder)
+			slide = nil
+			render_slide(builder, slide)
+		end
+	end
+	
+	# Provides the scope for XRB template rendering.
+	#
+	# Templates access slide content via `self.section(name)` and slide metadata via `self.slide`.
+	class TemplateScope
+		# Initialize a new template scope for the given slide.
+		# @parameter slide [Slide] The slide being rendered.
+		def initialize(slide)
+			@slide = slide
+		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
+		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] || "")
+		end
+	end
+end

data/lib/presently/state.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "json"
+
+module Presently
+	# Persists and restores presentation controller state to/from a JSON file.
+	#
+	# Tracks the current slide index, clock elapsed time, and clock running state.
+	# This allows the presentation to survive server restarts without losing position.
+	class State
+		# The default state file path.
+		DEFAULT_PATH = ".presently.json"
+		
+		# Initialize a new state instance.
+		# @parameter path [String] The file path for the state file.
+		def initialize(path = DEFAULT_PATH)
+			@path = path
+		end
+		
+		# @attribute [String] The file path for the state file.
+		attr :path
+		
+		# Save the controller's current state to disk.
+		# @parameter controller [PresentationController] The controller to save.
+		def save(controller)
+			data = {
+				current_index: controller.current_index,
+				elapsed: controller.clock.elapsed,
+				running: controller.clock.running?,
+				started: controller.clock.started?,
+			}
+			
+			File.write(@path, JSON.pretty_generate(data))
+		rescue => error
+			Console.warn(self, "Failed to save state", error: error)
+		end
+		
+		# Restore state into the given controller.
+		# @parameter controller [PresentationController] The controller to restore into.
+		def load(controller)
+			return unless File.exist?(@path)
+			
+			data = JSON.parse(File.read(@path), symbolize_names: true)
+			
+			# Restore slide position:
+			if index = data[:current_index]
+				controller.go_to(index.to_i)
+			end
+			
+			# Restore clock state:
+			if data[:started]
+				controller.clock.start!
+				controller.clock.reset!(data[:elapsed].to_f)
+				
+				unless data[:running]
+					controller.clock.pause!
+				end
+			end
+		rescue => error
+			Console.warn(self, "Failed to load state", error: error)
+		end
+	end
+end

data/lib/presently/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+# @namespace
+module Presently
+	VERSION = "0.1.0"
+end

data/lib/presently.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "presently/version"
+
+require_relative "presently/application"
+require_relative "presently/environment/application"

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2026, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.