presently 0.23.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38ca14929dc4ebe84fefad98f34e153f3c6423b9cbb147d73d08a84c2c64e4c2
-  data.tar.gz: b3efe32e93f81c0857d2109231e149d67d510a1d46c3117d0ef862b52f3a6b04
+  metadata.gz: ff7fb5b5f79f21fe8d6ebae384ee3e8454fe85012c209568d244b40840898774
+  data.tar.gz: ba3b8d4703af77058b4abfc2343032cc778ce61487f52b70ef6cb7643547001a
 SHA512:
-  metadata.gz: 1104e8b67d9ff964735a644cbbedb1f9616522af673cf0903bef63cced829e61312cea822cab9cc77a3b84a812e653fb19970582f23726cb846d5f92aa594c51
-  data.tar.gz: d4ae5680354d4b51b1f3d6451a0cf224e03f36dd05255b8d2c9f630b63276dd420c5573b7bed72633e5377af479f1eca18856347c999c364809cae42f505cce5
+  metadata.gz: d75218dd736c68eb3022142ea6bb3305a0db487f823a915175f11f8774b01ef5a6cba0b2cfa4cabb2f881367896d5c9d331a944a1d5e09295d86c5237066f918
+  data.tar.gz: 13c3042a25f7f664efec66a0be216e38edd3d8a087248d3236727d35e509c9d3787e50698b06984e6cde3a3ec52e876c894a1a6110e5cca8d48aed812a096270

data/context/animating-slides.md

@@ -29,6 +29,20 @@ The script receives a `slide` object — an instance of the `Slide` class export
 
 If the script contains a syntax error or throws an exception, the error is logged to the browser console and the presentation continues unaffected.
 
+## Flicker-Free Initial State
+
+Presently keeps a scripted slide hidden until its scripts have run. Any visibility or styling that defines the slide's initial state must therefore be applied synchronously at the top level of the script:
+
+``` javascript
+const bullets = slide.find("li").builder({effect: "fade"})
+bullets.show(0)
+bullets.play(500)
+```
+
+Use `slide.after()`, `setTimeout()`, promises, and `requestAnimationFrame()` only for changes that occur after the initial state is established. Deferring the initial `show()` call allows the slide to become visible before the callback runs and can expose its uninitialized content for a frame.
+
+Integrations using `SlideRendering#render(update)` have the same requirement: `update` must mutate the supplied view synchronously. Presently runs the new slide's scripts immediately after that update, before yielding to asynchronous syntax highlighting or code-focus preparation.
+
 ## The Slide API
 
 ### `slide.find(selector)`

data/lib/presently/application.rb

@@ -11,7 +11,7 @@ require_relative "presentation_controller"
 require_relative "home_view"
 require_relative "display_view"
 require_relative "presenter_view"
-require_relative "recording_view"
+require_relative "recorder_view"
 require_relative "recordings"
 require_relative "slide_assets"
 require_relative "playback"
@@ -44,7 +44,7 @@ module Presently
 		# The view classes that this application allows.
 		# @returns [Array(Class)] The allowed view classes.
 		def allowed_views
-			[HomeView, DisplayView, PresenterView, RecordingView]
+			[HomeView, DisplayView, PresenterView, RecorderView, RecordingControlsView]
 		end
 		
 		# The shared state passed to all views via the resolver.
@@ -60,7 +60,7 @@ module Presently
 				templates = Templates.for(@templates_roots)
 				presentation = Presentation.load(@slides_root, templates)
 				
-				PresentationController.new(presentation, state: State.new)
+				PresentationController.new(presentation, state: State.new, recordings: @recordings)
 			end
 		end
 		
@@ -89,7 +89,7 @@ module Presently
 			
 			router.get("/display"){make_page(resolver.root(DisplayView), interface: :display).call}
 			router.get("/presenter"){make_page(resolver.root(PresenterView), interface: :presenter).call}
-			router.get("/record"){make_page(resolver.root(RecordingView), interface: :recorder).call}
+			router.get("/recorder"){make_page(resolver.root(RecorderView), interface: :recorder).call}
 			
 			router.route("/recordings", methods: ["GET", "HEAD", "PUT", "PATCH"]) do |request|
 				handle_recording(request, request_parameters(request))

data/lib/presently/home_view.rb

@@ -20,7 +20,7 @@ module Presently
 				description: "Control the presentation with speaker notes, timing, and slide previews.",
 			},
 			{
-				href: "/record",
+				href: "/recorder",
 				title: "Narration Recorder",
 				description: "Record, review, and save narration for each slide.",
 			},

data/lib/presently/page.rb

@@ -29,6 +29,7 @@ module Presently
 		].freeze
 		IMPORTS = {
 			"live" => "/_components/@socketry/live/Live.js",
+			"@socketry/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",

data/lib/presently/presentation_controller.rb

@@ -18,8 +18,10 @@ module Presently
 		# 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)
+		# @parameter recordings [Recordings | Nil] The narration recording store, when recording is enabled.
+		def initialize(presentation, state: nil, recordings: nil)
 			@presentation = presentation
+			@recordings = recordings
 			@current_index = 0
 			@clock = Clock.new
 			@listeners = []
@@ -55,6 +57,13 @@ module Presently
 			@presentation.slides[@current_index]
 		end
 		
+		# Whether the given slide has a narration recording.
+		# @parameter slide [Slide] The slide to check.
+		# @returns [Boolean]
+		def recording_available?(slide)
+			@recordings&.exist?(slide) || false
+		end
+		
 		# The slide following the current one.
 		# @returns [Slide | Nil] The next slide, or `nil` if on the last slide.
 		def next_slide

data/lib/presently/{recording_view.rb → recorder_view.rb}

@@ -4,6 +4,7 @@
 # Copyright, 2026, by Samuel Williams.
 
 require_relative "editor"
+require_relative "recording_controls_view"
 require_relative "slide_view"
 require_relative "slide_renderer"
 
@@ -13,7 +14,7 @@ module Presently
 	# 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
+	class RecorderView < SlideView
 		# Initialize a recording view.
 		# @parameter id [String] The unique element identifier.
 		# @parameter data [Hash] The element data attributes.
@@ -22,6 +23,7 @@ module Presently
 			super(id, data)
 			@controller = controller
 			@slide_renderer = SlideRenderer.new(css_class: "slide recording-slide", templates: controller.templates)
+			@recording_controls = RecordingControlsView.mount(self, "recording-controls", controller: controller)
 		end
 		
 		# Bind this view to a page and register for slide changes.
@@ -73,9 +75,6 @@ module Presently
 			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)
 				
@@ -88,29 +87,7 @@ module Presently
 						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,
-								"data-slide-duration": slide.duration
-							) 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(:button, class: "recording-apply-duration", type: "button", hidden: true) do
-									builder.text("Update Slide Duration")
-								end
-								builder.tag(:label, class: "recording-duration-option") do
-									builder.tag(:input, class: "recording-update-duration", type: "checkbox")
-									builder.tag(:span){builder.text("Update slide duration to match recording")}
-								end
-								builder.tag(:p, class: "recording-status", role: "status"){builder.text("Checking for an existing recording…")}
-							end
+							builder << @recording_controls.to_html
 						end
 						
 						builder.tag(:section, class: "recording-notes") do

data/lib/presently/recording_controls_view.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "live"
+
+module Presently
+	# The persistent narration controls nested within {RecorderView}.
+	class RecordingControlsView < Live::View
+		# Initialize the recording controls view.
+		# @parameter id [String] The stable 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
+		end
+		
+		# Use the client-side recorder as this live view's custom element.
+		def tag_name
+			"presently-recording-controls"
+		end
+		
+		# Render the recorder host. Its shadow DOM owns the controls themselves.
+		# @parameter builder [XRB::Builder] The HTML builder.
+		def build_markup(builder)
+			slide = @controller.current_slide
+			return unless slide
+			
+			index = @controller.current_index
+			recording_present = @controller.recording_available?(slide)
+			
+			builder.inline_tag(tag_name,
+				id: @id,
+				data: @data,
+				"data-slide-index": index,
+				"data-recording-url": "/recordings?index=#{index}",
+				"data-slide-duration": slide.duration,
+				"data-recording-state": recording_present ? "present" : "missing"
+			)
+		end
+	end
+end

data/lib/presently/slide_renderer.rb

@@ -45,7 +45,9 @@ module Presently
 			scope = TemplateScope.new(slide)
 			html = template.to_string(scope)
 			
-			classes = [@css_class, extra_class].compact.join(" ")
+			classes = [@css_class, extra_class]
+			classes << "slide-scripted" unless slide.scripts.empty?
+			classes = classes.compact.join(" ")
 			path = Stylesheet.encode_path(slide.path)
 			
 			builder.tag(:div, class: "slide-surface", data: {template: slide.template}) do

data/lib/presently/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Presently
-	VERSION = "0.23.0"
+	VERSION = "0.24.0"
 end

data/lib/presently.rb

@@ -8,7 +8,7 @@ require_relative "presently/version"
 require_relative "presently/recordings"
 require_relative "presently/stylesheet"
 require_relative "presently/recordings/normalizer"
-require_relative "presently/recording_view"
+require_relative "presently/recorder_view"
 require_relative "presently/playback"
 require_relative "presently/application"
 require_relative "presently/environment/application"

data/public/_components/@socketry/presently/Presently/Scripts.js

@@ -25,6 +25,9 @@ export function runScript(slideEl, {animated = true} = {}) {
 		}
 	} catch (error) {
 		console.error('Slide script error:', error);
+	} finally {
+		// Scripted slides remain hidden until their initial state has been applied.
+		slideEl.dataset.slideReady = '';
 	}
 
 	return slide;

data/public/_components/@socketry/presently/Presently/SlideRendering.js

@@ -27,19 +27,21 @@ export class SlideRendering {
 	async initialize() {
 		if (this.#disposed) return false;
 
-		await prepareSlides();
-		if (this.#disposed) return false;
-
+		// Establish script-controlled visibility before yielding to asynchronous
+		// highlighting, so partially initialized slide content is never painted.
 		this.#view.querySelectorAll('.slide').forEach(slideElement => {
 			const slide = runScript(slideElement);
 			if (slide) this.#slides.push(slide);
 		});
 
-		return true;
+		await prepareSlides();
+		return !this.#disposed;
 	}
 
 	// Update the view, initialize its slides, and emit the change event.
-	// @parameter update [Function] Updates the view's DOM.
+	// The update must mutate the view synchronously so slide scripts can establish
+	// their initial state before the browser can paint the updated DOM.
+	// @parameter update [Function] Updates the view's DOM synchronously.
 	// @returns [Promise(Boolean)] Whether the rendering was completed.
 	async render(update) {
 		if (this.#disposed) return false;
@@ -48,7 +50,7 @@ export class SlideRendering {
 		const render = async () => {
 			if (this.#disposed) return;
 
-			await update(this.#view);
+			update(this.#view);
 			initialized = await this.initialize();
 		};
 

data/public/_static/recorder.css

@@ -55,69 +55,81 @@
 	opacity: 0.65;
 }
 
-presently-recorder {
+presently-recording-controls {
 	display: grid;
 	gap: 1rem;
+	/* Preserve the completed control layout while the client component upgrades. */
+	min-block-size: 12.5rem;
 }
 
-.recording-actions {
+presently-recording-controls::part(actions) {
 	display: flex;
 	align-items: center;
 	gap: 0.6rem;
 }
 
-.recording-actions button,
-.recording-apply-duration {
+presently-recording-controls::part(toggle),
+presently-recording-controls::part(save),
+presently-recording-controls::part(apply-duration) {
+	box-sizing: border-box;
 	padding: 0.55rem 0.9rem;
 	background: var(--surface-light);
-	border: 1px solid rgba(255,255,255,0.12);
+	border: 1px solid rgba(255, 255, 255, 0.12);
 	border-radius: 6px;
 	color: var(--slide-text);
 	cursor: pointer;
 	font: inherit;
+	transition:
+		background-color 120ms ease-out,
+		border-color 120ms ease-out,
+		color 120ms ease-out,
+		opacity 120ms ease-out;
 }
 
-.recording-apply-duration {
+presently-recording-controls::part(apply-duration) {
 	justify-self: start;
 }
 
-.recording-actions button:hover:not(:disabled),
-.recording-apply-duration:hover:not(:disabled) {
+presently-recording-controls::part(toggle):hover:not(:disabled),
+presently-recording-controls::part(save):hover:not(:disabled),
+presently-recording-controls::part(apply-duration):hover:not(:disabled) {
 	background: var(--accent);
 }
 
-.recording-actions button:disabled,
-.recording-apply-duration:disabled {
+presently-recording-controls::part(toggle):disabled,
+presently-recording-controls::part(save):disabled,
+presently-recording-controls::part(apply-duration):disabled {
 	cursor: default;
 	opacity: 0.35;
 }
 
-.recording-toggle:not(:disabled) {
+presently-recording-controls::part(toggle):not(:disabled) {
 	color: var(--accent-light);
 }
 
-presently-recorder[data-state="recording"] .recording-toggle {
+presently-recording-controls[data-recording-state="recording"]::part(toggle) {
 	color: #ef5350;
 }
 
-.recording-indicator {
+presently-recording-controls::part(indicator) {
+	box-sizing: border-box;
 	width: 0.65rem;
 	height: 0.65rem;
 	margin-left: auto;
-	background: rgba(255,255,255,0.2);
+	background: rgba(255, 255, 255, 0.2);
 	border-radius: 50%;
 }
 
-presently-recorder[data-state="preparing"] .recording-indicator,
-presently-recorder[data-state="starting"] .recording-indicator {
+presently-recording-controls[data-recording-state="preparing"]::part(indicator),
+presently-recording-controls[data-recording-state="starting"]::part(indicator) {
 	background: #f5b942;
-	box-shadow: 0 0 0 0.25rem rgba(245,185,66,0.15);
+	box-shadow: 0 0 0 0.25rem rgba(245, 185, 66, 0.15);
 	animation: recording-indicator-pulse 600ms ease-in-out infinite alternate;
 }
 
-presently-recorder[data-state="recording"] .recording-indicator {
+presently-recording-controls[data-recording-state="recording"]::part(indicator) {
 	background: #ef5350;
-	box-shadow: 0 0 0 0.25rem rgba(239,83,80,0.15);
+	box-shadow: 0 0 0 0.25rem rgba(239, 83, 80, 0.15);
 }
 
 @keyframes recording-indicator-pulse {
@@ -127,32 +139,29 @@ presently-recorder[data-state="recording"] .recording-indicator {
 	}
 }
 
-.recording-time {
+presently-recording-controls::part(time) {
 	font-family: var(--font-mono);
 	font-variant-numeric: tabular-nums;
 }
 
-.recording-playback {
+presently-recording-controls::part(playback) {
+	display: block;
 	width: 100%;
 }
 
-.recording-duration-option {
+presently-recording-controls::part(duration-option) {
 	display: flex;
 	align-items: center;
 	gap: 0.5rem;
 	cursor: pointer;
 }
 
-.recording-status {
-	min-height: 1.4em;
-	margin: 0;
-	font-size: 0.9rem;
-	opacity: 0.7;
-}
-
-.recording-status.error {
-	color: #ff4757;
-	opacity: 1;
+@media (prefers-reduced-motion: reduce) {
+	presently-recording-controls::part(toggle),
+	presently-recording-controls::part(save),
+	presently-recording-controls::part(apply-duration) {
+		transition: none;
+	}
 }
 
 .recording-notes {

data/public/_static/slides.css

@@ -60,6 +60,11 @@
 	container-type: size;
 }
 
+/* Never expose a scripted slide before its script establishes the initial state. */
+.slide-scripted:not([data-slide-ready]) {
+	visibility: hidden;
+}
+
 @container (min-aspect-ratio: 16 / 9) {
 	.slide {
 		width: auto;

data/public/application.js

@@ -1,7 +1,7 @@
-import { Live } from 'live';
-import {SlideRendering} from '@socketry/presently';
+import './recording_controls.js';
 
-import './recorder.js';
+import {Live} from '@socketry/live';
+import {SlideRendering} from '@socketry/presently';
 
 const SLIDE_RENDER_EVENT = 'presently:slide:render';
 
@@ -52,7 +52,7 @@ document.addEventListener('change', (event) => {
 
 // Keyboard navigation
 document.addEventListener('keydown', (event) => {
-	if (event.target.closest('button, input, textarea, select, audio, presently-recorder')) return;
+	if (event.target.closest('button, input, textarea, select, audio, presently-recording-controls')) return;
 	
 	const liveView = document.querySelector('live-view');
 	if (!liveView) return;