presently 0.26.1 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc69b4f81a2143dbbccc8d591c1fb675bb447057b77ffde4420f1ad1d7b3819a
-  data.tar.gz: b49c223f245c7949d72d8510d41d59f3e43efd6eb33b22bfe931bc84c0e1473d
+  metadata.gz: d8b031e64df9f01cd66eb315891ac4bf2b851f78355025afdf3f849a3a7513e5
+  data.tar.gz: 860837d5f75beaa2d814e388b401a297ce0af0ec4eb8e96eb99459fd79fa5460
 SHA512:
-  metadata.gz: '00686d6b384cdbbd81b27cc96e33e5301222c4b14a54c18f9221c2795f2b1eb0175ca4fbfc8caf10c3f2bb463df7ea85ba169b76b9b9e7c75049b419663b8be6'
-  data.tar.gz: d5348d5212bdde155fd4dcd7ea284606ff893716144fa8b04f202f3c18f0f18688431fe7ca59320c32c521baab047419b80170e31950fc57fe9dbcbaa545f95f
+  metadata.gz: 62a0c52ebb93318dd390592ea580b1fa4883891b36d66339669bdbb98dc8e202af97517f375d463fac720034ec90e2b36f62ef1f5784fba29103e49eb57c4b55
+  data.tar.gz: f93b4b3b5a00275be37ec3a1a4d4760c41e270193a501a8f9a3030849e0765dcf6dab04cc3c7f92519fdc80b7950a52b259e9864f583e09b397dcbc6cd102a1c

checksums.yaml.gz.sig

@@ -1,3 +1 @@
-������13Z���NJO�ԥA�˺lIyH#)�|�2�p��[��Y�M�lZ�+E��t
�B�Y�~���K�0/HgPX������c���CD���ۣ_���:��!.N:�Q�`�[W7�̜�S]�v�ZAaL�f"�\Ĭ��t|�,a�r�d�4��k�����M�Nҍ\�~��������$���K?�6�]5���)	���g^���ZO���$�*p�
���T�sX�to��.^�gk�`��J�}Q(X��^54���ͻ�׌3�\V�(��Y.�χ�
-�w�K���u�;[M%Qa�kUZ0�U{�y���,]��ӥ�0�H�՟pܙ�4�F"u���	vk�Y�r4�u:Dr�2�a��"�<�
-edL
+:]��*�Ր�J�c4�b_�+����;R���,�Z?m1u�Qp�W�ϑ���.M��M�ȶ��zFm�=R�tJy/{�r�T�E-�~��u�N��"����5��`��b/f�J�u��&؈��=�I�23w>}�A�H�g��H���![O�|�~\��AF����_w�=K��}�ڠXƖ�w�@~>��#싑�|癛NB�\��iv�=�|��6���@x���c�M�l2��e��˪c͡I�^�M3ef�n�M�`�֛ƺ��=�{���%��dk�}G7�:��S�|:Cb�(؊X�M|D�_|�|�𡎡�7m `�����L�Y�[�9|�E���K�[GX����~g�$t}rҊ1 ԊN#W�`Hq

data/context/getting-started.md

@@ -231,11 +231,31 @@ 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.
 
+### Timer Controls
+
+Pause the timer before changing its elapsed time, whether you are rehearsing a section or preparing for another presentation.
+
+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.
+
+| 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.
+
 ### 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:
@@ -252,7 +272,7 @@ timer: start
 We'll begin shortly.
 ```
 
-The timer stays stopped 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.
+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.
 
@@ -260,9 +280,9 @@ The `timer` field supports these actions:
 
 | Value | Effect when advancing from this slide |
 |---|---|
-| `start` | Starts the timer only if it has never started. Revisiting the slide does not reset elapsed time or resume a manually paused timer. |
-| `pause` | Pauses the timer, preserving elapsed time. Has no effect before the timer starts. |
-| `resume` | Resumes a started timer, preserving elapsed time. Has no effect before the timer starts or while it is already running. |
+| `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.
 

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.1"
+	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

@@ -69,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.
@@ -122,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.1
+  version: 0.27.0
 platform: ruby
 authors:
 - Samuel Williams