presently 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 474e433100802366e483635b1255b07c3f6b287eb5d7d5a8e9e4a4300bba02c1
+  data.tar.gz: 79318b1e1f04856ca57dcde476c1bae8921e261ab018c7d75c1d8637dbecf06e
+SHA512:
+  metadata.gz: 4d8b7743fe9f90c69f69a8905a93604d251ab4f64617a319cd26e223c8a3c750a712d3ed06a5d21c1554d5cb480345a0d008e6669c18b7ced1ef9f68e0fba813
+  data.tar.gz: 016f73a329b50181cb044a2561a097c48f3b5e8b504295d25577f034c712e0199a55251436ba7475d80b10843798be823888d5c648411a3f819899c7a647e1d5

data/bin/presently

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "async/service"
+require_relative "../lib/presently/environment/application"
+
+configuration = Async::Service::Configuration.build do
+	service "presently" do
+		include Presently::Environment::Application
+	end
+end
+
+Async::Service::Controller.run(configuration)

data/lib/presently/application.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "live"
+require "lively"
+
+require_relative "presentation"
+require_relative "presentation_controller"
+require_relative "state"
+require_relative "display_view"
+require_relative "presenter_view"
+require_relative "page"
+
+module Presently
+	# Extends {Live::Resolver} to pass shared state to views on construction.
+	#
+	# When the browser reconnects via WebSocket, the resolver creates new view
+	# instances with the shared {PresentationController} so all clients stay in sync.
+	class Resolver < Live::Resolver
+		# Initialize a new resolver with shared state.
+		# @parameter state [Hash] Key-value pairs to pass to view constructors.
+		def initialize(**state)
+			super()
+			@state = state
+		end
+		
+		# @attribute [Hash] The shared state passed to view constructors.
+		attr :state
+		
+		# Resolve a client-side element to a server-side instance with shared state.
+		# @parameter id [String] The unique element identifier.
+		# @parameter data [Hash] The element data attributes.
+		# @returns [Live::Element | Nil] The resolved element, or `nil`.
+		def call(id, data)
+			if klass = @allowed[data[:class]]
+				return klass.new(id, data, **@state)
+			end
+		end
+	end
+	
+	# The main Presently application middleware.
+	#
+	# Handles routing for the display view (`/`), presenter view (`/presenter`),
+	# and WebSocket connections (`/live`). Creates a shared {PresentationController}
+	# that keeps all connected clients in sync.
+	class Application < Lively::Application
+		# Initialize a new Presently application.
+		# @parameter delegate [Protocol::HTTP::Middleware] The next middleware in the chain.
+		# @parameter slides_root [String] The directory containing slide files.
+		# @parameter templates_root [String | Nil] The directory containing custom templates.
+		# @parameter options [Hash] Additional options passed to the parent.
+		def initialize(delegate, slides_root: "slides", templates_root: nil, **options)
+			presentation = Presentation.load(slides_root, templates_root: templates_root)
+			
+			state = State.new
+			
+			resolver = Resolver.new(
+				controller: PresentationController.new(presentation, state: state),
+			).tap do |resolver|
+				resolver.allow(DisplayView, PresenterView)
+			end
+			
+			super(delegate, resolver: resolver, **options)
+		end
+		
+		# The shared presentation controller.
+		# @returns [PresentationController] The controller instance.
+		def controller
+			resolver.state[:controller]
+		end
+		
+		# The application title shown in the browser.
+		# @returns [String] The page title.
+		def title
+			"Presently"
+		end
+		
+		# Create the body view for the given request path.
+		# @parameter request [Protocol::HTTP::Request] The incoming request.
+		# @returns [Live::View | Nil] The view for the path, or `nil` for unknown paths.
+		def body(request)
+			case request.path
+			when "/"
+				DisplayView.new(controller: controller)
+			when "/presenter"
+				PresenterView.new(controller: controller)
+			end
+		end
+		
+		# Handle an HTTP request by rendering the appropriate page.
+		# @parameter request [Protocol::HTTP::Request] The incoming request.
+		# @returns [Protocol::HTTP::Response] The HTTP response.
+		def handle(request)
+			if body = self.body(request)
+				page = Page.new(title: title, body: body)
+				return Protocol::HTTP::Response[200, [], [page.call]]
+			else
+				return Protocol::HTTP::Response[404, [], ["Not Found"]]
+			end
+		end
+	end
+end

data/lib/presently/clock.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Presently
+	# A simple clock that tracks elapsed time with start, pause, resume, and reset.
+	#
+	# The clock accumulates elapsed time while running and freezes it when paused.
+	class Clock
+		# Initialize a new clock in the stopped state.
+		def initialize
+			@elapsed = 0
+			@running = false
+			@last_tick = nil
+		end
+		
+		# Whether the clock has been started at least once.
+		# @returns [Boolean]
+		def started?
+			!@last_tick.nil?
+		end
+		
+		# Whether the clock is currently running and accumulating time.
+		# @returns [Boolean]
+		def running?
+			@running
+		end
+		
+		# Whether the clock has been started but is currently paused.
+		# @returns [Boolean]
+		def paused?
+			started? && !@running
+		end
+		
+		# The total elapsed time in seconds.
+		# Includes time accumulated up to now if running, or frozen time if paused.
+		# @returns [Numeric] The elapsed time in seconds.
+		def elapsed
+			if @running
+				@elapsed + (Time.now - @last_tick)
+			else
+				@elapsed
+			end
+		end
+		
+		# Start the clock. Begins accumulating time from now.
+		def start!
+			@running = true
+			@last_tick = Time.now
+		end
+		
+		# Pause the clock. Freezes the elapsed time at the current value.
+		def pause!
+			return unless @running
+			
+			@elapsed += Time.now - @last_tick
+			@running = false
+		end
+		
+		# Resume the clock after a pause. Continues accumulating time from now.
+		def resume!
+			return if @running
+			
+			@running = true
+			@last_tick = Time.now
+		end
+		
+		# Reset the elapsed time to the given value.
+		# If running, continues from the new value. If paused, sets the frozen value.
+		# @parameter elapsed [Numeric] The new elapsed time in seconds.
+		def reset!(elapsed = 0)
+			@elapsed = elapsed
+			@last_tick = Time.now if @running
+		end
+	end
+end

data/lib/presently/display_view.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "live"
+require_relative "slide_view"
+
+module Presently
+	# The audience-facing display view that renders the current slide full-screen.
+	#
+	# Connects to the {PresentationController} as a listener and updates
+	# whenever the slide changes. Pushes the current state on WebSocket reconnect.
+	class DisplayView < Live::View
+		# 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)
+			super(id, data)
+			@controller = controller
+			@slide_renderer = SlideView.new(css_class: "slide current", controller: controller)
+		end
+		
+		# Bind this view to a page and register as a listener.
+		# Immediately pushes the current state to the client.
+		# @parameter page [Live::Page] The page this view is bound to.
+		def bind(page)
+			super
+			@controller.add_listener(self)
+			self.update!
+		end
+		
+		# Close this view and unregister as a listener.
+		def close
+			@controller.remove_listener(self)
+			super
+		end
+		
+		# Called by the controller when the slide changes.
+		def slide_changed!
+			self.update!
+		end
+		
+		# Handle an event from the client.
+		# @parameter event [Hash] The event data with `:detail` containing the action.
+		def handle(event)
+			case event.dig(:detail, :action)
+			when "next"
+				@controller.advance!
+			when "previous"
+				@controller.retreat!
+			end
+		end
+		
+		# Render the display view.
+		# @parameter builder [XRB::Builder] The HTML builder.
+		def render(builder)
+			slide = @controller.current_slide
+			return unless slide
+			
+			builder.tag(:div, class: "display", data: {transition: slide.transition}) do
+				builder.tag(:div, class: "slide-container") do
+					@slide_renderer.render_slide(builder, slide)
+				end
+				
+				builder.tag(:div, class: "slide-counter") do
+					builder.text("#{@controller.current_index + 1} / #{@controller.slide_count}")
+				end
+			end
+		end
+	end
+end

data/lib/presently/environment/application.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../application"
+require "lively/environment/application"
+
+module Presently
+	module Environment
+		# The environment configuration for a Presently application server.
+		#
+		# Extends the Lively environment with Presently-specific middleware and configuration.
+		# Override {#slides_root} and {#templates_root} to customize paths.
+		module Application
+			include Lively::Environment::Application
+			
+			# The root directory containing slide Markdown files.
+			# @returns [String] Absolute path to the slides root.
+			def slides_root
+				File.expand_path("slides", self.root)
+			end
+			
+			# The root directory containing slide templates.
+			# Defaults to the gem's bundled templates.
+			# @returns [String] Absolute path to the templates root.
+			def templates_root
+				File.expand_path("../../../templates", __dir__)
+			end
+			
+			# The application class to use.
+			# @returns [Class] The Presently application class.
+			def application
+				Presently::Application
+			end
+			
+			# Build the middleware stack with Presently's public assets.
+			# @returns [Protocol::HTTP::Middleware] The complete middleware stack.
+			def middleware
+				application = self.application
+				slides_root = self.slides_root
+				templates_root = self.templates_root
+				root = self.root
+				
+				::Protocol::HTTP::Middleware.build do |builder|
+					# Serve assets from the user's public directory:
+					builder.use Lively::Assets, root: File.expand_path("public", root)
+					
+					# Serve Presently's bundled assets (syntax-js, CSS, etc.):
+					builder.use Lively::Assets, root: File.expand_path("../../../public", __dir__)
+					
+					# Serve Lively's built-in assets (Live.js, morphdom, etc.):
+					builder.use Lively::Assets, root: File.expand_path("public", Gem.loaded_specs["lively"].full_gem_path)
+					
+					builder.use application,
+						slides_root: slides_root,
+						templates_root: templates_root
+				end
+			end
+		end
+	end
+end

data/lib/presently/page.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "xrb/template"
+
+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__))
+		
+		# 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)
+		end
+	end
+end

data/lib/presently/page.xrb

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<title>#{self.title}</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="/_components/@socketry/syntax/themes/base/syntax.css" type="text/css" media="screen" />
+		
+		<script type="importmap">
+		{
+			"imports": {
+				"live": "/_components/@socketry/live/Live.js",
+				"live-audio": "/_components/@socketry/live-audio/Live/Audio.js",
+				"morphdom": "/_components/morphdom/morphdom-esm.js",
+				"@socketry/syntax": "/_components/@socketry/syntax/Syntax.js"
+			}
+		}
+		</script>
+		
+		<script type="module" src="/application.js"></script>
+	</head>
+	
+	<body>
+		#{self.body&.to_html || "No body specified!"}
+	</body>
+</html>

data/lib/presently/presentation.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "slide"
+
+module Presently
+	# An immutable collection of slides with configuration.
+	#
+	# Use {.load} to create a presentation from a directory of Markdown files,
+	# or initialize directly with an array of {Slide} instances.
+	class Presentation
+		# Load a presentation from a directory of Markdown slide files.
+		# @parameter slides_root [String] The directory containing `.md` slide files.
+		# @parameter options [Hash] Additional options passed to {#initialize}.
+		# @returns [Presentation] A new presentation with slides loaded from the directory.
+		def self.load(slides_root = "slides", **options)
+			pattern = File.join(slides_root, "*.md")
+			slides = Dir.glob(pattern).sort.map{|path| Slide.new(path)}
+			
+			new(slides, slides_root: slides_root, **options)
+		end
+		
+		# Initialize a new presentation.
+		# @parameter slides [Array(Slide)] The ordered list of slides.
+		# @parameter slides_root [String | Nil] The directory slides were loaded from, used by {#reload!}.
+		# @parameter templates_root [String | Nil] The directory containing custom `.xrb` templates.
+		def initialize(slides = [], slides_root: nil, templates_root: nil)
+			@slides = slides
+			@slides_root = slides_root
+			@templates_root = templates_root
+		end
+		
+		# @attribute [Array(Slide)] The ordered list of slides.
+		attr :slides
+		
+		# @attribute [String | Nil] The directory slides were loaded from.
+		attr :slides_root
+		
+		# @attribute [String | Nil] The directory containing custom templates.
+		attr :templates_root
+		
+		# The number of slides in the presentation.
+		# @returns [Integer] The slide count.
+		def slide_count
+			@slides.length
+		end
+		
+		# The total expected duration of the presentation in seconds.
+		# @returns [Numeric] The sum of all slide durations.
+		def total_duration
+			@slides.sum(&:duration)
+		end
+		
+		# Calculate the expected elapsed time for slides up to the given index.
+		# @parameter index [Integer] The slide index (exclusive).
+		# @returns [Numeric] The sum of durations for slides before the given index.
+		def expected_time_at(index)
+			@slides[0...index].sum(&:duration)
+		end
+		
+		# Reload slides from the original directory.
+		# Only works if the presentation was created with {.load}.
+		def reload!
+			if @slides_root
+				pattern = File.join(@slides_root, "*.md")
+				@slides = Dir.glob(pattern).sort.map{|path| Slide.new(path)}
+			end
+		end
+	end
+end

data/lib/presently/presentation_controller.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "clock"
+require_relative "presentation"
+require_relative "state"
+
+module Presently
+	# Manages the mutable state of a presentation: current slide, clock, and listeners.
+	#
+	# Wraps an immutable {Presentation} and provides navigation, timing, and listener notification.
+	# Multiple views (display, presenter) can register as listeners to receive updates.
+	class PresentationController
+		# Initialize a new controller for the given presentation.
+		# @parameter presentation [Presentation] The presentation to control.
+		# @parameter state [State | Nil] The state persistence object. If provided, state is saved on changes and restored on initialization.
+		def initialize(presentation, state: nil)
+			@presentation = presentation
+			@current_index = 0
+			@clock = Clock.new
+			@listeners = []
+			@state = state
+			
+			@state&.load(self)
+		end
+		
+		# @attribute [Presentation] The underlying presentation data.
+		attr :presentation
+		
+		# @attribute [Integer] The index of the current slide.
+		attr :current_index
+		
+		# @attribute [Clock] The presentation timer.
+		attr :clock
+		
+		# The templates root directory, delegated to the presentation.
+		# @returns [String | Nil] The templates root path.
+		def templates_root
+			@presentation.templates_root
+		end
+		
+		# The ordered list of slides, delegated to the presentation.
+		# @returns [Array(Slide)] The slides.
+		def slides
+			@presentation.slides
+		end
+		
+		# The currently displayed slide.
+		# @returns [Slide | Nil] The current slide, or `nil` if no slides are loaded.
+		def current_slide
+			@presentation.slides[@current_index]
+		end
+		
+		# The slide following the current one.
+		# @returns [Slide | Nil] The next slide, or `nil` if on the last slide.
+		def next_slide
+			@presentation.slides[@current_index + 1]
+		end
+		
+		# The slide preceding the current one.
+		# @returns [Slide | Nil] The previous slide, or `nil` if on the first slide.
+		def previous_slide
+			@presentation.slides[@current_index - 1] if @current_index > 0
+		end
+		
+		# The total number of slides.
+		# @returns [Integer] The slide count.
+		def slide_count
+			@presentation.slide_count
+		end
+		
+		# The total expected duration of the presentation.
+		# @returns [Numeric] The total duration in seconds.
+		def total_duration
+			@presentation.total_duration
+		end
+		
+		# The progress through the current slide's allocated time.
+		# @returns [Float] A value between 0.0 and 1.0.
+		def slide_progress
+			return 0.0 unless @clock.started?
+			
+			slide = current_slide
+			return 0.0 unless slide
+			
+			time_into_slide = @clock.elapsed - @presentation.expected_time_at(@current_index)
+			(time_into_slide / slide.duration).clamp(0.0, 1.0)
+		end
+		
+		# Reset the timer so that elapsed time matches the expected time for the current slide.
+		def reset_timer!
+			@clock.reset!(@presentation.expected_time_at(@current_index))
+			notify_listeners!
+		end
+		
+		# The current pacing status relative to the slide timing.
+		# @returns [Symbol] One of `:on_time`, `:ahead`, or `:behind`.
+		def pacing
+			return :on_time unless @clock.started?
+			
+			elapsed = @clock.elapsed
+			slide_start = @presentation.expected_time_at(@current_index)
+			slide_end = @presentation.expected_time_at(@current_index + 1)
+			
+			if elapsed > slide_end
+				:behind
+			elsif elapsed < slide_start
+				:ahead
+			else
+				:on_time
+			end
+		end
+		
+		# The estimated time remaining in the presentation.
+		# @returns [Numeric] The remaining time in seconds.
+		def time_remaining
+			return total_duration unless @clock.started?
+			
+			expected_remaining = @presentation.expected_time_at(slide_count) - @clock.elapsed
+			
+			[expected_remaining, 0].max
+		end
+		
+		# Navigate to a specific slide by index.
+		# Ignores out-of-bounds indices. Notifies listeners on change.
+		# @parameter index [Integer] The slide index to navigate to.
+		def go_to(index)
+			return if index < 0 || index >= slide_count
+			
+			@current_index = index
+			notify_listeners!
+		end
+		
+		# Advance to the next slide.
+		def advance!
+			go_to(@current_index + 1)
+		end
+		
+		# Go back to the previous slide.
+		def retreat!
+			go_to(@current_index - 1)
+		end
+		
+		# Register a listener to be notified when the slide changes.
+		# The listener must respond to `#slide_changed!`.
+		# @parameter listener [Object] The listener to add.
+		def add_listener(listener)
+			@listeners << listener
+		end
+		
+		# Remove a previously registered listener.
+		# @parameter listener [Object] The listener to remove.
+		def remove_listener(listener)
+			@listeners.delete(listener)
+		end
+		
+		# Reload slides from disk and notify listeners.
+		def reload!
+			@presentation.reload!
+			notify_listeners!
+		end
+		
+		# Persist the current state to disk.
+		def save_state!
+			@state&.save(self)
+		end
+		
+		private
+		
+		# Notify all registered listeners that the slide has changed, and persist state.
+		def notify_listeners!
+			@state&.save(self)
+			
+			@listeners.each do |listener|
+				listener.slide_changed! rescue nil
+			end
+		end
+	end
+end