presently 0.14.0 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46e3cc47613d0f667aeead379bdb8ed4c311ae9375c08ca32ceeeca4d57b5919
-  data.tar.gz: d4bf90e706c3a358a30937a3589f493a9c42f70a87babf9cc976407714124b98
+  metadata.gz: de6eb2668cd67cd34eb8f02c51dce3bc3f823f71b8e553835d27c2476d3f793e
+  data.tar.gz: 37601886d71cc24f89510ed65d918dbb87bcd1de1d0c48718f96b15820790e23
 SHA512:
-  metadata.gz: 07702bbfa6107d4ee4554015450a7008d09d69e6e2c7486a5b5aa6d94b7b15ba188557810634e8fca79bbadcc450793b7d36f01c6878cf04f9d0fe7a74f77de9
-  data.tar.gz: 6b31a696453ce2a9d9adf6fe3b084a4aba9a20a23f4535b3582fab49af4999e62cebe41389cacc3ce7d9227bf0653365b2009892377cb09e20396bfa02a9d204
+  metadata.gz: 5d272168a8f3de208c69e56fb44083c2417987d5178afc6e021f9ae4c9c2ddd5985f3251637581e21aea109e9698778c147865baece48bd8a6cb7dd652c7c888
+  data.tar.gz: 1d30ea352a266fcf97def9fdba931adb9cec25933f74bebbac85ecb53e35ceaee46c2faebdcbde473bb853c2959e135a6a2b0b5309eaff91646a632f50ddc043

data/context/animating-slides.md

@@ -0,0 +1,266 @@
+# Animating Slides
+
+This guide explains how to animate content within slides using the `morph` transition and the slide scripting system.
+
+## How Morph Works
+
+The `morph` transition uses the browser's View Transitions API. When navigating between two slides, any element that has a `view-transition-name` style on both the old and new slide is matched — the browser captures its position and appearance in both states and animates between them.
+
+Elements without a matching name crossfade. The slide background stays completely still (no container animation).
+
+This is the mechanism that makes build sequences possible: the same element appears on consecutive slides with the same name, so it stays pinned in place while hidden elements appear around it.
+
+## Slide Scripts
+
+Any slide can include a JavaScript block at the end of its presenter notes section. The script runs in the browser immediately after the slide renders.
+
+~~~ markdown
+---
+template: default
+duration: 30
+transition: morph
+---
+
+- First point
+- Second point
+- Third point
+
+---
+
+Your presenter notes here.
+
+```javascript
+slide.find("li").show(1, {group: "bullet"})
+```
+~~~
+
+The script receives a `slide` object — an instance of the `Slide` class from `slide.js` — scoped to the current slide's body.
+
+If the script contains a syntax error or throws an exception, the error is logged to the browser console and the presentation continues unaffected.
+
+## The Slide API
+
+### `slide.find(selector)`
+
+Queries elements within the slide body matching the given CSS selector. Returns a `SlideElements` collection. This is a pure query with no side effects.
+
+``` javascript
+slide.find("li")           // all list items
+slide.find("h2, li")       // headings and list items in document order
+slide.find(".callout")     // elements with a specific class
+```
+
+### `elements.show(n, options)`
+
+Shows the first `n` elements in the collection and hides the rest. Assigns `view-transition-name` to each element so the morph transition can match them across consecutive slides. Returns a `Promise` that resolves when any reveal animation completes.
+
+``` javascript
+slide.find("li").show(0)  // all hidden
+slide.find("li").show(1)  // first visible, rest hidden
+slide.find("li").show(3)  // first three visible, rest hidden
+```
+
+Options:
+
+| Option | Description |
+|---|---|
+| `group` | Name prefix for `view-transition-name` — must be consistent across slides for morph to match elements. Defaults to `"build"`. |
+| `effect` | Entry animation for the newly revealed element. See effects below. |
+
+### `elements.builder(options)`
+
+Creates a `SlideBuilder` with default options and a cached position. Use this instead of calling `show()` manually when you want to reveal elements one at a time from a script.
+
+``` javascript
+const bullets = slide.find("li").builder({group: "bullet", effect: "fly-up"})
+bullets.show(0)       // hide all initially
+bullets.next()        // reveal first, plays fly-up
+bullets.next()        // reveal second, plays fly-up
+bullets.finished      // true when all revealed
+```
+
+### `SlideBuilder#next(overrides)`
+
+Reveals the next element using the builder's default effect. Only touches the single newly revealed element — O(1). Returns a `Promise`. Accepts optional overrides for this step.
+
+### `SlideBuilder#show(n, overrides)`
+
+Sets the builder to an arbitrary position. Useful for initialization and jumping. Iterates all elements for correctness.
+
+### `SlideBuilder#play(interval, callback)`
+
+Reveals all remaining elements in sequence, with `interval` milliseconds between each step. An optional callback is invoked after each `next()` — return `false` to stop playback early. Requires the builder to be created via `slide.find(...).builder()` so that timeouts are tracked and cancelled when the slide changes.
+
+``` javascript
+// Play all elements at 400ms intervals:
+boxes.play(400)
+
+// Stop early based on a condition:
+boxes.play(400, () => !paused)
+
+// Inspect the builder after each step:
+boxes.play(400, (builder) => !builder.finished)
+```
+
+### `SlideBuilder#finished`
+
+Returns `true` when all elements have been revealed.
+
+## Build Sequences
+
+A build sequence is a series of consecutive slides with the same content, each revealing one more element. Because the slides are real files, each has its own duration and presenter notes — you can write exactly what to say when each element appears.
+
+~~~ markdown
+<!-- 030-overview.md -->
+---
+template: default
+duration: 20
+transition: morph
+---
+
+- Real-time synchronization
+- Markdown-based slides
+- Multiple templates
+
+---
+
+Let's walk through the key features.
+
+```javascript
+slide.find("li").show(0, {group: "bullet"})
+```
+~~~
+
+~~~ markdown
+<!-- 031-overview.md -->
+---
+template: default
+duration: 20
+transition: morph
+---
+
+- Real-time synchronization
+- Markdown-based slides
+- Multiple templates
+
+---
+
+The display and presenter stay in sync over a WebSocket connection.
+
+```javascript
+slide.find("li").show(1, {group: "bullet"})
+```
+~~~
+
+The `group` option must be identical across all slides in the sequence so the browser matches the same elements. Without it, each slide uses the default `"build"` prefix — which is fine as long as only one build sequence is active per slide.
+
+Because all elements are in the DOM from the start (just hidden), the vertical layout stays consistent throughout the sequence — there is no shift as elements appear.
+
+## Build Effects
+
+Pass an `effect` option to animate the newly revealed element as it appears. The effect plays as a CSS animation on the element and is removed automatically once it completes.
+
+``` javascript
+slide.find("li").show(2, {group: "bullet", effect: "fly-up"})
+```
+
+Available effects:
+
+| Effect | Animation |
+|---|---|
+| `fade` | Fades in |
+| `fly-left` | Slides in from the left |
+| `fly-right` | Slides in from the right |
+| `fly-up` | Rises in from below |
+| `fly-down` | Drops in from above |
+| `scale` | Scales up from 80% |
+
+## Multiple Build Groups
+
+A slide can have multiple independent build groups. Each `find().show()` call is self-contained:
+
+``` javascript
+// Reveal list items as one group, callout div as another
+slide.find("li").show(3, {group: "bullet"})
+slide.find(".callout").show(1, {group: "callout", effect: "fly-up"})
+```
+
+## In-Slide Animation with `slide.after()`
+
+For sequential reveals within a single slide (without navigating to the next slide), use `slide.after()`. Each step fires a delay in milliseconds relative to the previous step. Returns a `SlideContext` so subsequent `.after()` calls chain naturally.
+
+``` javascript
+const panes = slide.find(".pane").builder({group: "pane", effect: "fade"})
+const items = slide.find(".item").builder({group: "item", effect: "fly-up"})
+panes.show(0)
+items.show(0)
+
+slide
+  .after(400, () => panes.next())
+  .after(400, () => items.next())
+  .after(300, () => items.next())
+  .after(400, () => panes.next())
+```
+
+All timeouts registered via `slide.after()` (and the underlying `slide.setTimeout()`) are automatically cancelled when the user navigates to another slide, so stale callbacks never fire.
+
+The global `setTimeout` in slide scripts is also automatically tracked — you can use it directly and it will be cancelled on slide change.
+
+## Looping Animations with `slide.loop()`
+
+To repeat an animation indefinitely, use `slide.loop()`. The callback receives a fresh `SlideContext` each iteration and can use `after()` to schedule steps in the same way as a regular chain. The loop waits for all steps to complete and then restarts, with an optional extra pause between iterations.
+
+``` javascript
+const steps = slide.find(".step").builder({effect: "fly-up"})
+steps.show(0)
+
+slide.loop((context) => {
+  steps.show(0)  // reset at the start of each iteration
+  context
+    .after(800, () => steps.next())
+    .after(800, () => steps.next())
+    .after(800, () => steps.next())
+}, { delay: 1500 })
+```
+
+The `delay` option adds extra time after the last step before the next iteration begins — useful for giving the audience a moment to read the fully-revealed state before it resets.
+
+The callback is responsible for resetting any state (such as calling `builder.show(0)`) at the start of each iteration. This keeps the loop body self-contained and makes the reset timing explicit.
+
+All timeouts are tracked through the parent slide, so the loop stops automatically when the user navigates away — no cleanup needed.
+
+## Absolutely Positioned Elements
+
+All slide templates support absolutely positioned elements since the slide container is `position: relative`. You can overlay any element on top of normal slide content:
+
+~~~ markdown
+<div style="position: absolute; bottom: 2rem; right: 2rem; background: var(--accent); color: white; padding: 0.5rem 1rem; border-radius: 6px;">
+  Callout text
+</div>
+~~~
+
+In the `diagram` template, all direct `<div>` children are `position: absolute` by default, so you can build free-form layouts without repeating the positioning declaration:
+
+~~~ markdown
+---
+template: diagram
+---
+
+<div style="left: 10%; top: 20%; width: 35%; height: 30%; background: var(--surface-light);">
+  Node A
+</div>
+
+<div style="left: 55%; top: 20%; width: 35%; height: 30%; background: var(--surface-light);">
+  Node B
+</div>
+~~~
+
+Combine with the scripting system to animate diagram elements into place:
+
+``` javascript
+const nodes = slide.find("div").builder({group: "node", effect: "fade"})
+nodes.show(0)
+slide
+  .after(400, () => nodes.next())
+  .after(400, () => nodes.next())
+```

data/context/getting-started.md

@@ -0,0 +1,324 @@
+# Getting Started
+
+This guide explains how to use `presently` to create and deliver web-based presentations using Markdown slides.
+
+## Installation
+
+Add the gem to your project:
+
+``` bash
+$ gem install presently
+```
+
+## Core Concepts
+
+Presently has several core concepts:
+
+- A {ruby Presently::Presentation} which loads and manages slide content from Markdown files.
+- A {ruby Presently::PresentationController} which manages the mutable state of a presentation: current slide, clock, and listeners.
+- A {ruby Presently::Slide} which represents a single slide parsed from a Markdown file with YAML frontmatter.
+- A {ruby Presently::DisplayView} which renders the audience-facing full-screen display.
+- A {ruby Presently::PresenterView} which renders the presenter console with notes, timing, and slide previews.
+
+## Creating Your First Presentation
+
+Create a new directory for your presentation:
+
+``` bash
+$ mkdir my-talk
+$ cd my-talk
+$ mkdir slides
+```
+
+### Writing Slides
+
+Each slide is a Markdown file in the `slides/` directory. Files are ordered alphabetically, so prefix them with numbers:
+
+``` markdown
+---
+template: title
+duration: 30
+---
+
+# Title
+
+Welcome to My Talk
+
+# Subtitle
+
+A presentation built with Presently
+
+---
+
+These are presenter notes — only visible in the presenter view.
+```
+
+Each slide has three parts:
+
+1. **YAML frontmatter** between `---` markers at the top, specifying the template, duration, and other metadata.
+2. **Content** with Markdown headings that become named sections for the template.
+3. **Presenter notes** after a `---` separator in the body (optional).
+
+### Running the Presentation
+
+Start the server from your presentation directory:
+
+``` bash
+$ presently
+```
+
+Then open two browser windows:
+
+- `http://localhost:9292/` — the audience display.
+- `http://localhost:9292/presenter` — the presenter console.
+
+Advancing slides in either window updates both in real-time via WebSockets.
+
+### Keyboard Controls
+
+- **Arrow Right / Space / Page Down** — next slide.
+- **Arrow Left / Page Up** — previous slide.
+- **F** — toggle full-screen (display view).
+
+## 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. All content without a heading goes into the `body` section.
+
+``` markdown
+---
+template: default
+duration: 60
+---
+
+- First point
+- Second point
+- Third point
+```
+
+### Title
+
+A large title with a subtitle, centered on the slide.
+
+``` markdown
+---
+template: title
+duration: 30
+---
+
+# Title
+
+My Presentation Title
+
+# Subtitle
+
+A subtitle or tagline
+```
+
+### Section
+
+A section divider slide with a large heading and accent background.
+
+``` markdown
+---
+template: section
+duration: 15
+---
+
+# Heading
+
+Part Two
+```
+
+### Two Column
+
+A side-by-side layout with `left` and `right` sections.
+
+``` markdown
+---
+template: two_column
+duration: 90
+---
+
+# 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
+title: 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` section.
+
+``` markdown
+---
+template: statement
+duration: 30
+---
+
+The best way to predict the future is to create it.
+
+# Translation
+
+未来を予測する最善の方法は、それを創ることである。
+```
+
+### Translations
+
+All templates support an optional `# Translation` section. When present, the translation is displayed below the main content in a lighter style. This works with `title`, `section`, `statement`, and `image` templates.
+
+### Image
+
+A centered image with an optional caption.
+
+``` markdown
+---
+template: image
+duration: 30
+---
+
+![Architecture diagram](/images/architecture.png)
+
+# Caption
+
+System architecture overview
+```
+
+### Diagram
+
+A free-form layout slide with a `position: relative` container. Direct `<div>` children are `position: absolute` by default, so you can place elements precisely using inline styles. Use this for custom diagrams, annotated layouts, or any slide that doesn't fit a standard template.
+
+``` markdown
+---
+template: diagram
+duration: 60
+---
+
+<div style="left: 10%; top: 20%; width: 35%; height: 25%;">
+  Browser
+</div>
+
+<div style="left: 55%; top: 20%; width: 35%; height: 25%;">
+  Server
+</div>
+```
+
+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.
+
+## Transitions
+
+Slides transition instantly by default. Add a `transition` key to the frontmatter to animate between slides:
+
+``` markdown
+---
+template: default
+transition: fade
+---
+```
+
+Available transitions:
+
+| Transition | Effect |
+|---|---|
+| `fade` | Crossfade between slides |
+| `slide-left` | Current slide exits left, next enters from right |
+| `slide-right` | Current slide exits right, next enters from left |
+| `morph` | Matched elements animate between positions; everything else crossfades |
+
+The `morph` transition uses the browser's View Transitions API to smoothly animate individual elements between slides. Elements with the same `view-transition-name` across two consecutive slides are matched and interpolated.
+
+## Presenter Notes
+
+Presenter notes appear after a `---` separator in the slide body. They support standard Markdown including **bold** and *italic*. Italic text is styled as a stage direction — use it for cues that shouldn't be spoken aloud:
+
+``` markdown
+---
+
+*Take a breath and wait for the room to settle.*
+
+Hi everyone, thanks for being here.
+
+*Make eye contact with the front row.*
+```
+
+## Presenter Console
+
+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.
+- **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
+
+You can provide your own `.xrb` template files by configuring the templates root:
+
+``` ruby
+# In your environment configuration:
+service "presently" do
+  include Presently::Environment::Application
+
+  def templates_root
+    File.expand_path("templates", self.root)
+  end
+end
+```
+
+Templates receive a {ruby Presently::TemplateScope} with access to `self.slide` (the {ruby Presently::Slide} instance) and `self.section(name)` for retrieving named content sections.
+
+## Customizing the Application
+
+For advanced customization, create an `application.rb` and run with `presently application.rb`:
+
+``` ruby
+#!/usr/bin/env presently
+
+class Application < Presently::Application
+  def title
+    "My Conference Talk"
+  end
+end
+```

data/context/index.yaml

@@ -0,0 +1,16 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A web-based presentation tool built with Lively.
+metadata:
+  documentation_uri: https://socketry.github.io/presently/
+  source_code_uri: https://github.com/socketry/presently.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `presently` to create and deliver web-based
+    presentations using Markdown slides.
+- path: animating-slides.md
+  title: Animating Slides
+  description: This guide explains how to animate content within slides using the
+    `morph` transition and the slide scripting system.

data/lib/presently/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Presently
-	VERSION = "0.14.0"
+	VERSION = "0.14.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: presently
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.14.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -90,6 +90,9 @@ files:
 - bake/presently/rehearse.rb
 - bake/presently/slides.rb
 - bin/presently
+- context/animating-slides.md
+- context/getting-started.md
+- context/index.yaml
 - lib/presently.rb
 - lib/presently/application.rb
 - lib/presently/clock.rb