presently 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19e0176d3b7e17bd06f07d79e3ae4379d1992f3b75beb87b7725e47a713961be
-  data.tar.gz: 1b3bbd3f6a2c170f833a913cf1a0de5afb8030f3330773e62f1eba72153612c9
+  metadata.gz: 98c94c71298a2801441e3a2351c72e09b3c2e3dfdfde63a4d5b7673d42334aac
+  data.tar.gz: 15d88cf5bf1f4ddb3574c0f2ece5df062378650a1526bb14de74e20adb27354b
 SHA512:
-  metadata.gz: 0e9e35182f5d1fcd2a4e0a625ebfe3d0f8d743ece09335a1a399c82b5f720138ef62044e070ca54c01995b685dd970956fe15600f3b2176aee318226c569030c
-  data.tar.gz: d53ee079a8042e0abbcde56bb92d262084c2a8ea695dd4c41dec203bcd5d2a4050ba69557d2456cfcf5f85ddb48b8989bfe186938d8cda9ce6669e21d43cff99
+  metadata.gz: e0eb7788c6108fd1b16bfcac25deeeeb91c75e9af3e45f9b994351674931842880ce28567ccc30773e50d7a0f6d0c260f31e0db27d55a579121137e7a9ce912c
+  data.tar.gz: 8945b51b03abb5929c28267a544ed88e4f09b8baf342e33a2761f47d457e2476da320d3a7756319f0c2ebc8065ebe709d9b936c053a9d25c76eeffd533b67deb

data/context/getting-started.md

@@ -112,6 +112,36 @@ Relative images embedded in Markdown resolve from the Markdown file's directory,
 
 Presently loads each discovered stylesheet once in deterministic presentation order. Directory styles are loaded from parent to child before the matching slide sidecar, so more specific styles naturally appear later in the cascade. The same stylesheets are used by the display, presenter, recorder, playback, and export interfaces.
 
+### Background Images
+
+Add a background image behind any slide template using frontmatter:
+
+``` markdown
+---
+template: title
+background: images/mountains.jpg
+background-size: cover
+---
+
+# Welcome
+```
+
+The background fills the available slide surface, including space outside the 16:9 content area. Content keeps its 16:9 layout. Images are centred and do not repeat.
+
+Relative image paths resolve from the slide file's directory, just like Markdown images. Root-relative paths and external URLs are also supported.
+
+`background-size` accepts:
+
+| Value | Behaviour |
+|---|---|
+| `cover` (default) | Preserves proportions and fills the surface, cropping the image when necessary. |
+| `contain` | Preserves proportions and shows the whole image, potentially leaving uncovered space. |
+| `auto` | Uses the image's natural size. |
+
+Missing or unrecognised sizes use `cover`. An explicit background image replaces the template's background image or gradient; uncovered space shows the underlying slide background colour. Slides without a background image retain their template's appearance.
+
+Backgrounds appear in the display, presenter previews, recorder, playback, and PDF export. A preview or export with a different aspect ratio can crop the image differently from the audience display.
+
 ### Running the Presentation
 
 Start the server from your presentation directory:

data/lib/presently/slide.rb

@@ -272,24 +272,31 @@ module Presently
 			# @parameter source_path [String] The Markdown source path.
 			# @parameter root [String] The presentation asset root.
 			def rewrite_image_urls!(document, source_path, root)
+				document.walk do |node|
+					node.url = resolve_image_url(node.url, source_path, root) if node.type == :image
+				end
+			end
+			
+			# Resolve an image URL relative to its source file within the presentation.
+			# @parameter url [String] The image URL.
+			# @parameter source_path [String] The source file path.
+			# @parameter root [String] The presentation asset root.
+			# @returns [String] The resolved URL, preserving absolute URLs.
+			def resolve_image_url(url, source_path, root)
+				reference = Protocol::URL[url]
+				return url unless reference.is_a?(Protocol::URL::Relative)
+				return url if reference.path.empty? || reference.path.absolute?
+				
 				directory = File.dirname(File.expand_path(source_path))
 				root = File.expand_path(root)
-				return unless directory == root || directory.start_with?(root + File::SEPARATOR)
+				return url unless directory == root || directory.start_with?(root + File::SEPARATOR)
 				
 				relative_directory = directory.delete_prefix(root).delete_prefix(File::SEPARATOR)
 				base_path = Stylesheet::PREFIX
 				base_path += Stylesheet.encode_path(relative_directory) + "/" unless relative_directory.empty?
 				base_url = Protocol::URL::Relative.new(base_path)
 				
-				document.walk do |node|
-					next unless node.type == :image
-					
-					url = Protocol::URL[node.url]
-					next unless url.is_a?(Protocol::URL::Relative)
-					next if url.path.empty? || url.path.absolute?
-					
-					node.url = (base_url + url).to_s
-				end
+				(base_url + reference).to_s
 			end
 			
 		end
@@ -348,6 +355,22 @@ module Presently
 			@front_matter&.fetch("template", "default") || "default"
 		end
 		
+		# The background image URL, resolved relative to this slide's source file.
+		# @returns [String | Nil] The URL, or `nil` when no image is specified.
+		def background
+			value = @front_matter&.fetch("background", nil)
+			return unless value.is_a?(String) && !value.strip.empty?
+			
+			Parser.resolve_image_url(value, source_path, @presentation.root)
+		end
+		
+		# How the background image is sized within the full slide surface.
+		# @returns [String] `"cover"`, `"contain"`, or `"auto"`, defaulting to `"cover"`.
+		def background_size
+			value = @front_matter&.fetch("background-size", nil)
+			["cover", "contain", "auto"].include?(value) ? value : "cover"
+		end
+		
 		# The expected duration of this slide in seconds.
 		# Negative, invalid, or non-finite values are treated as zero.
 		# @returns [Float] A finite duration of at least `0.0`, defaulting to `0.0` when unspecified or null.

data/lib/presently/slide_renderer.rb

@@ -50,7 +50,14 @@ module Presently
 			classes = classes.compact.join(" ")
 			path = Stylesheet.encode_path(slide.path)
 			
-			builder.tag(:div, class: "slide-surface", data: {template: slide.template}) do
+			background = slide.background
+			if background
+				# Escape the CSS string independently of the builder's HTML escaping:
+				url = background.gsub(/["\\\x00-\x1f\x7f]/){|character| "\\#{character.ord.to_s(16)} "}
+				style = %(background-image: url("#{url}"); background-size: #{slide.background_size};)
+			end
+			
+			builder.tag(:div, class: "slide-surface", data: {template: slide.template, background: background}, style: style) do
 				builder.tag(:div, class: classes, data: {template: slide.template}, "data-slide-path": path) do
 					builder.raw(html)
 					

data/lib/presently/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Presently
-	VERSION = "0.28.0"
+	VERSION = "0.29.0"
 end

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

@@ -4,8 +4,19 @@ import {runScript} from './Scripts.js';
 
 const SLIDE_CHANGE_EVENT = 'presently:slide:change';
 
-async function prepareSlides() {
-	await Syntax.highlight();
+// Wait for background images to decode before capturing a transition or export.
+// A missing or invalid image must not prevent the slides from becoming ready.
+export async function prepareSlideBackgrounds(root = document) {
+	const urls = new Set(Array.from(root.querySelectorAll('.slide-surface[data-background]'), surface => surface.dataset.background));
+	await Promise.all(Array.from(urls, async url => {
+		const image = new Image();
+		image.src = url;
+		await image.decode().catch(() => {});
+	}));
+}
+
+async function prepareSlides(view) {
+	await Promise.all([Syntax.highlight(), prepareSlideBackgrounds(view)]);
 	await applyCodeFocus();
 }
 
@@ -42,7 +53,7 @@ export class SlideRendering {
 			if (slide) this.#slides.push(slide);
 		});
 
-		await prepareSlides();
+		await prepareSlides(this.#view);
 		return !this.#disposed;
 	}
 

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

@@ -1,4 +1,4 @@
 export {Slide, SlideBuilder, SlideContext, SlideElements} from './Presently/Slide.js';
 export {applyCodeFocus} from './Presently/CodeFocus.js';
-export {SlideRendering} from './Presently/SlideRendering.js';
+export {SlideRendering, prepareSlideBackgrounds} from './Presently/SlideRendering.js';
 export {runAllSlideScripts, runScript} from './Presently/Scripts.js';

data/public/_static/slides.css

@@ -17,6 +17,9 @@
 	place-items: center;
 	container-type: size;
 	background: var(--slide-background);
+	background-size: cover;
+	background-position: center;
+	background-repeat: no-repeat;
 }
 
 .slide {
@@ -159,7 +162,7 @@
 
 /* Section template */
 .slide-surface[data-template="section"] {
-	background: linear-gradient(135deg, var(--accent), var(--surface-light));
+	background-image: linear-gradient(135deg, var(--accent), var(--surface-light));
 }
 
 .section-template {

data/public/export.js

@@ -1,4 +1,4 @@
-import {applyCodeFocus, runAllSlideScripts} from '@socketry/presently';
+import {applyCodeFocus, runAllSlideScripts, prepareSlideBackgrounds} from '@socketry/presently';
 import Syntax from '@socketry/syntax';
 
 // Wait for two animation frames, ensuring the browser has processed all pending
@@ -9,15 +9,16 @@ function waitForRender() {
 }
 
 async function main() {
-	// 1. Kick off syntax highlighting and font loading concurrently.
+	// 1. Kick off syntax highlighting, background decoding, and font loading concurrently.
 	//    Slide scripts are synchronous and don't depend on either, so run them now.
 	const syntaxDone = Syntax.highlight();
+	const backgroundsDone = prepareSlideBackgrounds();
 
 	// 2. Run slide scripts (synchronous in export mode — sets visibility instantly).
 	runAllSlideScripts({animated: false});
 
-	// 3. Wait for syntax and fonts to finish before applying focus.
-	await Promise.all([syntaxDone, document.fonts.ready]);
+	// 3. Wait for syntax, backgrounds, and fonts to finish before applying focus.
+	await Promise.all([syntaxDone, backgroundsDone, document.fonts.ready]);
 
 	// 4. Apply code focus now that syntax-code elements are ready.
 	await applyCodeFocus();

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: presently
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.29.0
 platform: ruby
 authors:
 - Samuel Williams