presently 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57754e7cc66ec20e3ef797b20afbe147fda8979e96aafc14cdb9c35eaedb5495
-  data.tar.gz: 242278bc2177efc35609ece981bb3f6cb5fed099e628894d6c8ed9dcf77ce020
+  metadata.gz: d8b031e64df9f01cd66eb315891ac4bf2b851f78355025afdf3f849a3a7513e5
+  data.tar.gz: 860837d5f75beaa2d814e388b401a297ce0af0ec4eb8e96eb99459fd79fa5460
 SHA512:
-  metadata.gz: 206d33b334f6d1ed9f4b7df2b328022bb5b332a43a53932840be6bd5c00a5b1a41d8df262b441309d04a17d0fc74bdf6120449f4ff1ec0f84228385856d3df9e
-  data.tar.gz: 42f72ece55c0c02160fd12b90006651f0cd3cb1d2b4a95fa12516dbc1d88172652d76afd5639a3ff7c7b8edd6e57eb7d7ba6fb6a6303a90109bcff005aefdb2a
+  metadata.gz: 62a0c52ebb93318dd390592ea580b1fa4883891b36d66339669bdbb98dc8e202af97517f375d463fac720034ec90e2b36f62ef1f5784fba29103e49eb57c4b55
+  data.tar.gz: f93b4b3b5a00275be37ec3a1a4d4760c41e270193a501a8f9a3030849e0765dcf6dab04cc3c7f92519fdc80b7950a52b259e9864f583e09b397dcbc6cd102a1c

data/context/getting-started.md

@@ -188,173 +188,9 @@ The defaults are 1920×1080 at up to 30 frames per second. The exporter starts a
 
 ## Templates
 
-Templates define the visual layout of each slide. Select a template using the `template` field in the frontmatter.
+Templates define the visual layout of each slide. Select one with the `template` field in the frontmatter; slides without it use `default`. Common choices include `title` for an opening slide, `two_column` for comparisons, and `code` for code walkthroughs.
 
-### Default
-
-A general-purpose content slide. An H1 becomes the slide title and the remaining document becomes its body.
-
-``` markdown
----
-template: default
-duration: 60
----
-
-# Key points
-
-- First point
-- Second point
-- Third point
-```
-
-### Title
-
-A large title with a short body, centered on the slide.
-
-``` markdown
----
-template: title
-duration: 30
----
-
-# My Presentation Title
-
-A subtitle or tagline
-```
-
-### Section
-
-A section divider slide with a large heading, optional supporting body, and accent background.
-
-``` markdown
----
-template: section
-duration: 15
----
-
-# Part Two
-
-Architecture and design
-```
-
-### Two Column
-
-A side-by-side layout with `left` and `right` sections.
-
-``` markdown
----
-template: two_column
-duration: 90
----
-
-# Client and server responsibilities
-
-The application is split across two cooperating environments.
-
-## Left
-
-**Server Side**
-
-- Ruby + Lively
-- WebSocket connections
-
-## Right
-
-**Client Side**
-
-- Live DOM updates
-- CSS animations
-```
-
-### Code
-
-A syntax-highlighted code slide with optional focus regions for code walkthroughs. Use the `focus` frontmatter to specify which lines to highlight (1-based). Lines outside the focus range are dimmed, and the code scrolls to center the focused region.
-
-``` markdown
----
-template: code
-duration: 60
-focus: 2-8
----
-
-# Constructor
-
-```ruby
-class Presentation
-  def initialize
-    @slides = []
-    @current_index = 0
-  end
-
-  def advance!
-    @current_index += 1
-  end
-end
-​```
-```
-
-Create animated walkthroughs by using multiple slides with the same code but different `focus` ranges. The transition between them smoothly scrolls and shifts the dim overlays.
-
-### Statement
-
-A prominent statement or quote, centered on the slide. Supports an optional `## Translation` placeholder.
-
-``` markdown
----
-template: statement
-duration: 30
----
-
-The best way to predict the future is to create it.
-
-## Translation
-
-未来を予測する最善の方法は、それを創ることである。
-```
-
-### Translations
-
-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
-
-A centered image with an optional caption.
-
-``` markdown
----
-template: image
-duration: 30
----
-
-![Architecture diagram](/images/architecture.png)
-
-## Caption
-
-System architecture overview
-```
-
-### Diagram
-
-A centered canvas for diagrams and other custom visual layouts, with an optional title. A single grid or flex container is usually enough to create a diagram that remains centered as the slide scales:
-
-``` markdown
----
-template: diagram
-duration: 60
----
-
-# Request lifecycle
-
-<div style="display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 2em; width: 80%;">
-  <div>Browser</div>
-  <div>→</div>
-  <div>Server</div>
-</div>
-```
-
-For coordinate-based layouts, wrap the elements in `<div class="diagram-freeform">`. The wrapper fills the canvas and absolutely positions each direct child.
-
-All other templates also support absolutely positioned overlays since the slide container is `position: relative`. This lets you add callouts, badges, or annotations on top of any template's normal content.
+See the [Templates guide](../templates/index) for built-in layouts, examples, translations, and custom templates.
 
 ## Transitions
 
@@ -395,40 +231,62 @@ The presenter view at `/presenter` provides:
 
 - **Current and next slide previews** — see what's coming without switching windows.
 - **Presenter notes** — notes from the slide's `---` separator section.
-- **Timer controls** — Start, Pause, Resume, and Reset buttons.
+- **Timer controls** — Start when ready, Pause while running, and Resume or Reset while paused.
 - **Pacing indicator** — shows whether you're on time, ahead, or behind based on per-slide `duration` metadata.
 - **Progress bar** — visual indicator of time consumed for the current slide.
 - **Reload button** — reload slides from disk without restarting the server.
 
-## Custom Templates
+### Timer Controls
 
-You can provide your own `.xrb` template files by configuring the templates root:
+Pause the timer before changing its elapsed time, whether you are rehearsing a section or preparing for another presentation.
 
-``` ruby
-# In your environment configuration:
-service "presently" do
-  include Presently::Environment::Application
+A **ready** timer is waiting to start from its current timestamp. It can be ready at `0:00` or at a later position after Reset.
 
-  def templates_root
-    File.expand_path("templates", self.root)
-  end
-end
-```
+| Timer state | Available controls |
+|---|---|
+| Ready | **Start** begins timing, or **Auto-start** indicates that advancing will begin timing. |
+| Running | **Pause** freezes elapsed time. |
+| Paused | **Resume** continues timing, and **Reset** prepares the current slide to begin again. |
+
+**Reset** always sets elapsed time to the sum of durations before the current slide. It normally leaves the timer paused; press **Resume** when ready to continue. On a slide with `timer: start`, Reset returns the timer to the ready state at that same timestamp, so advancing starts from the slide's expected time. Reset leaves the current slide unchanged and is only available while paused.
+
+After a rehearsal, return to your waiting slide, pause, and press **Reset**. Advancing from that `timer: start` slide starts timing from its expected timestamp, regardless of its position in the deck. For example, a waiting slide after five minutes of allocated content resets to `5:00`, waits, and starts from `5:00` when you advance. The timestamp and ready state are also preserved when saving and restoring the presentation.
+
+For slides with recognized timer metadata and a following slide, the **Next** tooltip describes what advancing will actually do. For example, a manually paused `timer: start` slide shows “Timer is paused. Advancing will leave it paused.” After Reset, the tooltip changes to “Advancing will start the timer.” The tooltip also reflects pause and resume actions, including when they would leave the clock unchanged.
+
+While the timer is ready, an **Auto-start** indicator replaces **Start** on a `timer: start` slide with a following slide. Its play icon gently pulses, and its tooltip says “Advancing will start the timer.” Advance to begin timing; **Pause** and **Resume** are available while running and paused respectively. The animation respects reduced-motion preferences.
 
-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 ?>
+### Starting the Timer from a Title Slide
+
+A title slide can stay on screen while the audience settles. Add `timer: start` to its frontmatter to start the presentation timer when you advance to the next slide:
+
+``` markdown
+---
+template: title
+duration: 0
+timer: start
+---
+
+# My Presentation
+
+We'll begin shortly.
 ```
 
-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.
+The timer stays ready while the title is displayed. Advancing from it in `/presenter` or `/display` starts the timer before showing the next slide. Setting `duration: 0` excludes the waiting slide from the expected presentation duration and pacing calculations. The `title` template itself does not control the timer.
+
+Durations are read as floating-point seconds, including numeric strings. Negative, invalid, or non-finite values are treated as `0.0`. An unspecified or null duration defaults to `0.0` seconds, meaning no time has been allocated to that slide. Set explicit durations, or apply recorded narration durations, to establish a pacing schedule. When the total allocated duration is zero, the presenter shows elapsed time without pacing indicators, a progress bar, or a remaining-time estimate.
+
+The `timer` field supports these actions:
+
+| Value | Effect when advancing from this slide |
+|---|---|
+| `start` | Starts a ready timer from its current timestamp. Revisiting the slide does not reset elapsed time or resume a manually paused timer. |
+| `pause` | Pauses the timer, preserving elapsed time. Has no effect while ready. |
+| `resume` | Resumes a paused timer, preserving elapsed time. Has no effect while ready or already running. |
+
+For a break, put `timer: pause` on the slide immediately before the break slide, and `timer: resume` on the break slide itself. Give the break slide `duration: 0` to exclude the break from pacing calculations. Advancing into the break pauses timing; advancing out resumes it.
+
+Timer actions run only when **Next** successfully moves to another slide. Going backwards, jumping directly to a slide, reloading, reconnecting, and restoring saved state do not trigger them. Neither does navigation in `/record`, or recorded playback. Slides without a recognized timer action leave the timer unchanged; the manual timer controls remain available.
 
 ## Customizing the Application
 
@@ -438,8 +296,8 @@ For advanced customization, create an `application.rb` and run with `presently a
 #!/usr/bin/env presently
 
 class Application < Presently::Application
-  def title
-    "My Conference Talk"
-  end
+	def title
+		"My Conference Talk"
+	end
 end
 ```

data/context/index.yaml

@@ -10,6 +10,10 @@ files:
   title: Getting Started
   description: This guide explains how to use `presently` to create and deliver web-based
     presentations using Markdown slides.
+- path: templates.md
+  title: Templates
+  description: This guide explains how to choose slide templates and create custom
+    layouts in Presently.
 - path: animating-slides.md
   title: Animating Slides
   description: This guide explains how to animate content within slides using the

data/context/templates.md

@@ -0,0 +1,207 @@
+# Templates
+
+This guide explains how to choose slide templates and create custom layouts in Presently.
+
+## Built-in Templates
+
+Templates define the visual layout of each slide. Select a template using the `template` field in the frontmatter.
+
+### Default
+
+A general-purpose content slide. An H1 becomes the slide title and the remaining document becomes its body.
+
+``` markdown
+---
+template: default
+duration: 60
+---
+
+# Key points
+
+- First point
+- Second point
+- Third point
+```
+
+### Title
+
+A large title with a short body, centered on the slide.
+
+``` markdown
+---
+template: title
+duration: 30
+---
+
+# My Presentation Title
+
+A subtitle or tagline
+```
+
+### Section
+
+A section divider slide with a large heading, optional supporting body, and accent background.
+
+``` markdown
+---
+template: section
+duration: 15
+---
+
+# Part Two
+
+Architecture and design
+```
+
+### Two Column
+
+A side-by-side layout with `left` and `right` sections.
+
+``` markdown
+---
+template: two_column
+duration: 90
+---
+
+# Client and server responsibilities
+
+The application is split across two cooperating environments.
+
+## Left
+
+**Server Side**
+
+- Ruby + Lively
+- WebSocket connections
+
+## Right
+
+**Client Side**
+
+- Live DOM updates
+- CSS animations
+```
+
+### Code
+
+A syntax-highlighted code slide with optional focus regions for code walkthroughs. Use the `focus` frontmatter to specify which lines to highlight (1-based). Lines outside the focus range are dimmed, and the code scrolls to center the focused region.
+
+```` markdown
+---
+template: code
+duration: 60
+focus: 2-8
+---
+
+# Constructor
+
+```ruby
+class Presentation
+  def initialize
+    @slides = []
+    @current_index = 0
+  end
+
+  def advance!
+    @current_index += 1
+  end
+end
+```
+````
+
+Create animated walkthroughs by using multiple slides with the same code but different `focus` ranges. The transition between them smoothly scrolls and shifts the dim overlays.
+
+### Statement
+
+A prominent statement or quote, centered on the slide. Supports an optional `## Translation` placeholder.
+
+``` markdown
+---
+template: statement
+duration: 30
+---
+
+The best way to predict the future is to create it.
+
+## Translation
+
+未来を予測する最善の方法は、それを創ることである。
+```
+
+### Image
+
+A centered image with an optional caption.
+
+``` markdown
+---
+template: image
+duration: 30
+---
+
+![Architecture diagram](/images/architecture.png)
+
+## Caption
+
+System architecture overview
+```
+
+### Diagram
+
+A centered canvas for diagrams and other custom visual layouts, with an optional title. A single grid or flex container is usually enough to create a diagram that remains centered as the slide scales:
+
+``` markdown
+---
+template: diagram
+duration: 60
+---
+
+# Request lifecycle
+
+<div style="display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 2em; width: 80%;">
+  <div>Browser</div>
+  <div>→</div>
+  <div>Server</div>
+</div>
+```
+
+For coordinate-based layouts, wrap the elements in `<div class="diagram-freeform">`. The wrapper fills the canvas and absolutely positions each direct child.
+
+All other templates also support absolutely positioned overlays since the slide container is `position: relative`. This lets you add callouts, badges, or annotations on top of any template's normal content.
+
+## Translations
+
+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.
+
+## Custom Templates
+
+For layouts specific to your presentation, put `.xrb` files in a `templates/` directory alongside `slides/`. Presently searches this directory before its bundled templates, so you can add new layouts or override individual built-in templates.
+
+To search additional directories, configure `templates_roots`, which returns an ordered array of paths:
+
+``` ruby
+# In your environment configuration:
+service "presently" do
+	include Presently::Environment::Application
+	
+	def templates_roots
+		[File.expand_path("shared-templates", self.root)] + super
+	end
+end
+```
+
+For example, save the following template as `templates/custom.xrb` and select it with `template: custom` in a slide's frontmatter.
+
+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.

data/lib/presently/clock.rb

@@ -6,9 +6,10 @@
 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.
+	# A ready clock waits to start at its current elapsed time. It accumulates time
+	# while running and freezes it when paused.
 	class Clock
-		# Initialize a new clock in the stopped state.
+		# Initialize a new clock in the ready state at zero.
 		def initialize
 			@elapsed = 0
 			@started = false
@@ -16,7 +17,7 @@ module Presently
 			@last_tick = nil
 		end
 		
-		# Whether the clock has been started at least once.
+		# Whether the clock is running or paused; false when ready.
 		# @returns [Boolean]
 		def started?
 			@started
@@ -35,7 +36,7 @@ module Presently
 		end
 		
 		# The total elapsed time in seconds.
-		# Includes time accumulated up to now if running, or frozen time if paused.
+		# Includes time accumulated up to now if running, or frozen time if paused or ready.
 		# @returns [Numeric] The elapsed time in seconds.
 		def elapsed
 			if @running
@@ -78,12 +79,16 @@ module Presently
 			@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
+		# Reset the clock to its initial, ready state, or set its elapsed time.
+		# A numeric value preserves whether the clock is running; a ready clock becomes paused.
+		# Pass `started: false` to make the clock ready at the given elapsed time.
+		# @parameter elapsed [Numeric | Nil] The elapsed time in seconds, or `nil` to clear the clock.
+		# @parameter started [Boolean] Whether the clock is running or paused at the reset position; false makes it ready.
+		def reset!(elapsed = nil, started: !elapsed.nil?)
+			@elapsed = elapsed || 0
+			@started = started
+			@running = @started && @running
+			@last_tick = @running ? Time.now : nil
 		end
 	end
 end

data/lib/presently/presentation_controller.rb

@@ -105,9 +105,14 @@ module Presently
 			end
 		end
 		
-		# Reset the timer so that elapsed time matches the expected time for the current slide.
+		# Reset a paused timer to begin the current slide again.
+		# All slides reset to their expected start time. A `timer: start` slide becomes
+		# ready to start when advancing; other slides remain paused.
 		def reset_timer!
-			@clock.reset!(@presentation.expected_time_at(@current_index))
+			return unless @clock.paused? && current_slide
+			
+			@clock.reset!(@presentation.expected_time_at(@current_index), started: current_slide.timer != "start")
+			
 			notify_listeners!
 		end
 		
@@ -133,8 +138,6 @@ module Presently
 		# 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

data/lib/presently/presenter_view.rb

@@ -21,6 +21,7 @@ module Presently
 			super(id, data)
 			@controller = controller
 			@clock_task = nil
+			@timing_state = nil
 			@preview_renderer = SlideRenderer.new(css_class: "slide preview-slide", templates: controller.templates)
 		end
 		
@@ -51,11 +52,22 @@ module Presently
 			self.render_slide!
 		end
 		
-		# Push an update to just the timing section.
+		# Update the timing section and the Next tooltip when the clock state changes.
+		# Leave unchanged, paused controls in place to preserve keyboard focus.
 		def update_timing!
+			clock = @controller.clock
+			state_changed = @timing_state != [clock.started?, clock.running?]
+			return unless clock.running? || state_changed
+			
 			replace(".timing") do |builder|
 				render_timing(builder, @controller.current_slide)
 			end
+			
+			if state_changed
+				replace(".next-button") do |builder|
+					render_next_button(builder)
+				end
+			end
 		end
 		
 		# Handle an event from the client.
@@ -77,6 +89,7 @@ module Presently
 					@controller.clock.pause!
 				end
 				@controller.save_state!
+				update_timing! if @page
 			when "reset"
 				@controller.reset_timer!
 			when "reload"
@@ -96,13 +109,53 @@ module Presently
 			Editor.url_for(path, line)
 		end
 		
+		# Describe the actual effect of the outgoing slide's timer metadata.
+		# @returns [String | Nil] The hint, or `nil` when there is no timer action or next slide.
+		def timer_action_hint
+			return unless @controller.next_slide
+			
+			clock = @controller.clock
+			case @controller.current_slide.timer
+			when "start"
+				return "Advancing will start the timer." unless clock.started?
+			when "pause"
+				return "Advancing will pause the timer." if clock.running?
+			when "resume"
+				return "Advancing will resume the timer." if clock.paused?
+			else
+				return
+			end
+			
+			if clock.running?
+				"Advancing will leave the timer running."
+			elsif clock.paused?
+				"Timer is paused. Advancing will leave it paused."
+			else
+				"Advancing will leave the timer stopped."
+			end
+		end
+		
+		# Render the Next button with a tooltip describing its timer action.
+		# @parameter builder [XRB::Builder] The HTML builder.
+		def render_next_button(builder)
+			builder.tag(:button,
+				class: "next-button",
+				title: timer_action_hint,
+				onClick: forward_event(action: "next")
+			) do
+				builder.text("Next →")
+			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)
+			@timing_state = [@controller.clock.started?, @controller.clock.running?]
 			pacing = @controller.pacing
 			progress = pacing ? (@controller.slide_progress * 100).round(1) : 0.0
 			next_slide = @controller.next_slide
+			wait_for_advance = !@controller.clock.started? && slide&.timer == "start" && !!next_slide
 			builder.tag(:div, class: "timing", style: "--slide-progress: #{progress}%") do
 				pacing_class = case pacing
 				when :behind then "behind"
@@ -111,25 +164,45 @@ module Presently
 				end
 				
 				builder.tag(:div, class: "toolbar 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"
+					if wait_for_advance
+						builder.tag(:span,
+							class: "auto-start",
+							role: "status",
+							title: "Advancing will start the timer."
+						) do
+							builder.tag(:span, class: "auto-start-icon", "aria-hidden": "true"){builder.text("▶")}
+							builder.text("Auto-start")
+						end
+					else
+						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.text(label)
 					end
 					
-					builder.tag(:button,
-						class: "pause-button",
-						onClick: forward_event(action: "reset")
-					) do
-						builder.text("↺ Reset")
+					if @controller.clock.paused? && slide
+						title = if slide.timer == "start"
+							"Reset to this slide's timestamp and wait to start"
+						else
+							"Reset to this slide's timestamp and stay paused"
+						end
+						
+						builder.tag(:button,
+							class: "pause-button",
+							title: title,
+							onClick: forward_event(action: "reset")
+						) do
+							builder.text("↺ Reset")
+						end
 					end
 					
 					builder.tag(:span, class: "elapsed") do
@@ -200,11 +273,7 @@ module Presently
 						builder.text("← Previous")
 					end
 					
-					builder.tag(:button,
-						onClick: forward_event(action: "next")
-					) do
-						builder.text("Next →")
-					end
+					render_next_button(builder)
 					
 					builder.tag(:span, class: "slide-info") do
 						builder.tag(:span, class: "slide-position") do

data/lib/presently/state.rb

@@ -9,7 +9,7 @@ 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.
+	# Tracks the current slide index, clock elapsed time, and whether it is ready, running, or paused.
 	# This allows the presentation to survive server restarts without losing position.
 	class State
 		# The default state file path.
@@ -54,6 +54,8 @@ module Presently
 			# Restore clock state:
 			if data[:started]
 				controller.clock.restore!(data[:elapsed].to_f, running: data[:running])
+			else
+				controller.clock.reset!(data[:elapsed].to_f, started: false)
 			end
 		rescue => error
 			Console.warn(self, "Failed to restore state", exception: error)

data/lib/presently/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Presently
-	VERSION = "0.26.0"
+	VERSION = "0.27.0"
 end

data/public/_static/presenter.css

@@ -106,6 +106,35 @@
 	background: var(--accent);
 }
 
+.timing-info .auto-start {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.5rem;
+	height: 2.25rem;
+	padding: 0.3rem 0.75rem;
+	border: 1px solid rgba(233, 69, 96, 0.35);
+	border-radius: 6px;
+	background: rgba(233, 69, 96, 0.08);
+	color: var(--accent-light);
+	font-size: 0.9rem;
+	white-space: nowrap;
+}
+
+.auto-start-icon {
+	animation: auto-start-pulse 2.4s ease-in-out infinite;
+}
+
+@keyframes auto-start-pulse {
+	0%, 100% { opacity: 0.5; transform: scale(0.9); }
+	50% { opacity: 1; transform: scale(1.1); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.auto-start-icon {
+		animation: none;
+	}
+}
+
 .timing-info .elapsed {
 	font-variant-numeric: tabular-nums;
 }

data/readme.md

@@ -26,6 +26,8 @@ Please see the [project documentation](https://socketry.github.io/presently/) fo
 
   - [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.
 
+  - [Templates](https://socketry.github.io/presently/guides/templates/index) - This guide explains how to choose slide templates and create custom layouts in Presently.
+
   - [Animating Slides](https://socketry.github.io/presently/guides/animating-slides/index) - This guide explains how to animate content within slides using the slide scripting system.
 
   - [Animated Diagrams](https://socketry.github.io/presently/guides/animated-diagrams/index) - This guide explains how to design responsive, lifecycle-safe animated diagrams in Presently using semantic markup, slide-specific CSS, and Anime.js choreography.
@@ -67,6 +69,12 @@ The task records the presentation at 1920×1080 and 30 frames per second by defa
 
 Please see the [project releases](https://socketry.github.io/presently/releases/index) for all releases.
 
+### v0.27.0
+
+  - Show **Reset** only while paused. Reset always sets elapsed time to the current slide's expected start. It stays paused on ordinary slides, or becomes ready at that timestamp on a `timer: start` slide. Advancing starts from the preserved timestamp, which also survives saving and restoring the presentation.
+  - Describe the effect of slide timer metadata in the **Next** tooltip. Show an animated **Auto-start** indicator when advancing from the current slide will start the timer, with a tooltip explaining how to begin.
+  - Make `Clock#reset!` (or `reset!(nil)`) clear the clock to its initial, ready state. Passing a numeric elapsed time preserves whether it is running, or puts a ready clock into the paused state. Pass `started: false` to make the clock ready at a nonzero elapsed time.
+
 ### v0.26.0
 
   - Add `timer: start`, `timer: pause`, and `timer: resume` slide metadata, applied when advancing away from a slide in the presenter or display.
@@ -120,10 +128,6 @@ Please see the [project releases](https://socketry.github.io/presently/releases/
   - Truncate long slide paths responsively while preserving their filenames in presenter controls.
   - Preserve the complete saved presentation state when restoring the controller.
 
-### v0.17.2
-
-  - Fix slide rendering events for generated view identifiers that begin with a digit.
-
 ## See Also
 
   - [lively](https://github.com/socketry/lively) — The real-time application framework that powers Presently.

data/releases.md

@@ -1,5 +1,11 @@
 # Releases
 
+## v0.27.0
+
+  - Show **Reset** only while paused. Reset always sets elapsed time to the current slide's expected start. It stays paused on ordinary slides, or becomes ready at that timestamp on a `timer: start` slide. Advancing starts from the preserved timestamp, which also survives saving and restoring the presentation.
+  - Describe the effect of slide timer metadata in the **Next** tooltip. Show an animated **Auto-start** indicator when advancing from the current slide will start the timer, with a tooltip explaining how to begin.
+  - Make `Clock#reset!` (or `reset!(nil)`) clear the clock to its initial, ready state. Passing a numeric elapsed time preserves whether it is running, or puts a ready clock into the paused state. Pass `started: false` to make the clock ready at a nonzero elapsed time.
+
 ## v0.26.0
 
   - Add `timer: start`, `timer: pause`, and `timer: resume` slide metadata, applied when advancing away from a slide in the presenter or display.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: presently
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -122,6 +122,7 @@ files:
 - context/animating-slides.md
 - context/getting-started.md
 - context/index.yaml
+- context/templates.md
 - lib/presently.rb
 - lib/presently/application.rb
 - lib/presently/clock.rb