przn 0.5.0 → 0.6.0

data/lib/przn/renderer.rb

@@ -15,12 +15,6 @@ module Przn
 
     DEFAULT_SCALE = 2
 
-    # Default `relative_height` (as a percent of terminal height) applied to
-    # image blocks that don't carry an explicit one. Caps how much of the
-    # screen a single image can occupy; the rest leaves predictable margin
-    # for the slide footer and avoids placement-clearing edge cases in some
-    # terminals when an image lands right against the bottom row.
-    DEFAULT_IMAGE_RELATIVE_HEIGHT_PERCENT = 70
 
     # `mode:` controls whether `{::note}` / `<note>` segments are rendered:
     #   :solo      — dim-inline (today's behavior), default for stand-alone runs.
@@ -28,49 +22,169 @@ module Przn
     #   :presenter — dim-inline (so the presenter sees them in context) and
     #                ALSO aggregated separately for the side panel via
     #                Slide#notes; this renderer just keeps the inline copy.
-    def initialize(terminal, base_dir: '.', theme: nil, mode: :solo)
+    # `export_mode:` true when the renderer is driving a PDF export (currently
+    # ScreenshotPdfExporter): suppresses the 🐇/🐢 runner bar in favor of the
+    # plain `N / M` counter, since the emoji animation belongs on a live screen,
+    # not a static page.
+    # Swap in a fresh theme without rebuilding the renderer (so the
+    # image / kitty-upload caches survive). Used by the `r` reload
+    # path so a theme.yml edit takes effect mid-session.
+    attr_accessor :theme, :presentation
+    attr_reader :export_mode
+
+    def initialize(terminal, base_dir: '.', theme: nil, mode: :solo, export_mode: false, presentation: nil)
       @terminal = terminal
       @base_dir = base_dir
       @theme = theme || Theme.default
       @mode = mode
+      @export_mode = export_mode
+      # Deck-wide context for `<ref id="..."/>` resolution. nil is
+      # fine for unit tests that exercise a single slide; the
+      # render_ref path no-ops without a presentation wired.
+      @presentation = presentation
       @image_cache = {}
       @kitty_uploads = {}
       @mutex = Mutex.new
+      # Horizontal cell offset applied by `term_move` to flow-mode block
+      # rendering. Set per slot inside `render_layout`; zero everywhere
+      # else. Screen-absolute emits (footer, runner bar, render_at,
+      # `<img x y>` absolute mode) bypass it and call @terminal.move_to
+      # directly.
+      @x_offset = 0
+      # Per-slot text-style overrides (`size` / `family` / `color`)
+      # populated by `render_layout` for the duration of one slot.
+      # render_heading h1, render_paragraph, and the :body defaults in
+      # render_segments_scaled consult this so a `cover.title` slot
+      # with `size: xxx-large` actually makes the title bigger.
+      @slot_style = nil
+      # Kitty image id of the previous slide's background image (when
+      # set via `<bg image="..."/>` or `background.image:` in theme).
+      # Tracked so the placement can be deleted before the next slide
+      # applies its own bg — keeps the upload cached but wipes the
+      # visible artifact.
+      @bg_image_id = nil
     end
 
-    def render(slide, current:, total:, started_at: nil)
+    def render(slide, current:, total:, started_at: nil, step: 0, progress: 1.0, opacity: 1.0)
       @mutex.synchronize do
+        # Slide-level fade: when the controller drives a fractional
+        # opacity, bracket the entire slide render in OSC 7772
+        # `cell-alpha` so every text write inherits the alpha as
+        # terminal-side paint state. This is the slide-transition
+        # building block; the per-block `with_block_opacity` path
+        # (action-driven fades) is independent and still nests inside.
+        slide_alpha = opacity.to_f.clamp(0.0, 1.0)
+        slide_fade  = slide_alpha < 1.0
+        @terminal.write "\e]7772;cell-alpha;#{slide_alpha}\a" if slide_fade
+        # Per-block visibility for incremental reveals. Each `<wait/>`
+        # block bumps the step counter, so block_step[b] = "step at
+        # which block b becomes visible." A block is rendered iff
+        # block_step[b] <= step; otherwise its flow space is *reserved*
+        # but no bytes reach the terminal. See `suppressed_render`.
+        @block_step = compute_block_step(slide.blocks)
+        @current_step = step
+        # Action overrides accumulated up to the current step. Keyed
+        # by target id; merged into a block's attrs at render time.
+        # When `progress < 1.0`, actions at the JUST-REVEALED step
+        # (block_step == current_step) blend partway between their
+        # prior state and final values — that's what animates the
+        # smooth move. See `compute_effective_state`.
+        @effective_state = compute_effective_state(slide.blocks, @block_step, step, progress)
         @terminal.clear
+        # Wipe the previous slide's `<img>` / shape placements (cached
+        # image data stays alive). The current slide re-emits its own
+        # placements below; the alternative — letting placements leak
+        # — would mean every prior slide's images bleed through onto
+        # later ones, since kitty placements aren't tied to the cell
+        # buffer that @terminal.clear empties.
+        @terminal.write ImageUtil.kitty_delete_all_placements if ImageUtil.kitty_terminal?
         apply_slide_background(slide)
         w = @terminal.width
         h = @terminal.height
 
-        row = if current == 0
-          content_height = calculate_height(slide.blocks, w)
-          usable_height = h - 1
-          [(usable_height - content_height) / 2 + 1, 1].max
-        else
-          2
-        end
-
-        pending_align = nil
+        # Pre-pass: register shape placements AND fully-positioned `<img>`
+        # placements (both x and y set) BEFORE any text writes. Echoes'
+        # kitty graphics implementation erases the cells covered by a
+        # placement when the placement is registered, then text writes
+        # to those cells later restore the cell buffer (via
+        # erase_multicell_at). The placement itself stays in the GUI's
+        # @placements list and re-blits on top — so where the SVG / PNG
+        # is transparent, the underlying text shows through. Solid
+        # fills and opaque PNGs still occlude (Echoes has no z-index
+        # yet); thin strokes and outlined shapes coexist with text
+        # cleanly. Without this pass, text rendered BEFORE a positioned
+        # image was clobbered by the placement's cell-buffer wipe and
+        # disappeared even where the image had no opaque pixels.
+        #
+        # Hidden positioned content (block_step > current_step) is
+        # skipped outright — absolute placements don't take flow space
+        # so there's nothing to reserve, and we don't want a hidden
+        # image's bytes on the terminal before its reveal step.
         slide.blocks.each do |block|
-          if block[:type] == :align
-            pending_align = block[:align]
-          else
-            row = render_block(block, w, row, align: pending_align)
-            pending_align = nil
+          next if hidden?(block)
+          case block[:type]
+          when :shape
+            render_shape(block)
+          when :image
+            attrs = effective_attrs(block)
+            # Only "both-axes" positioned images can be pre-placed —
+            # x-only / y-only images still need the flow `row` to
+            # decide the unpinned axis, so they stay in the
+            # layout/flow pass below.
+            next unless attrs['x'] && attrs['y']
+            render_image(block, w, 1)
           end
         end
 
-        if @theme.rabbit
-          draw_runner_bar(h, w, current, total, started_at)
+        # Resolve the slide's effective layout name:
+        #   `# Title {layout=name}` on the slide wins.
+        #   Otherwise: slide 0 prefers `cover` (if the theme ships one),
+        #   every other slide falls through to `default`.
+        #   `{layout=none}` is an explicit per-slide opt-out — useful
+        #   when a custom default layout isn't right for one slide.
+        layout_name = slide.layout
+        layout_name ||= 'cover' if current == 0 && @theme.layouts['cover']
+        layout_name ||= 'default'
+        layout_name = nil if layout_name == 'none'
+        layout = layout_name && @theme.layouts[layout_name]
+
+        if layout
+          render_layout(slide, layout, w, h)
         else
-          status = " #{current + 1} / #{total} "
-          @terminal.move_to(h, w - status.size)
-          @terminal.write "#{ANSI[:dim]}#{status}#{ANSI[:reset]}"
+          # `{layout=none}` (or a theme stripped of `default`) — render
+          # blocks top-down from row 2 with no slot routing.
+          row = 2
+          pending_align = nil
+          slide.blocks.each do |block|
+            case block[:type]
+            when :align  then pending_align = block[:align]
+            when :wait   then next
+            when :action then next  # mutation already applied via @effective_state
+            else
+              row = render_block_or_reserve(block, w, row, align: pending_align)
+              pending_align = nil
+            end
+          end
         end
 
+        # `# Title {counter=hide}` opts a slide (typically the title
+        # page) out of the bottom row. Remembered for the runner-bar
+        # refresh thread, which only knows the slide index.
+        @counter_hidden = counter_hidden?(slide)
+        unless @counter_hidden
+          if counter_duration && !@export_mode
+            draw_runner_bar(h, w, current, total, started_at)
+          else
+            status = " #{current + 1} / #{total} "
+            @terminal.move_to(h, w - status.size)
+            @terminal.write "#{counter_color_open}#{status}#{ANSI[:reset]}"
+          end
+        end
+
+        # Close the slide-level cell-alpha bracket so the next render
+        # (or any other terminal write outside the renderer) lands at
+        # full opacity. Mirrors the per-block reset in `with_block_opacity`.
+        @terminal.write "\e]7772;cell-alpha;1\a" if slide_fade
         @terminal.flush
       end
     end
@@ -81,6 +195,19 @@ module Przn
     # against `render` via the renderer's mutex so terminal writes don't
     # interleave.
     def preload(slide)
+      # Code-block tokenizer warmup. Pays the `require 'rouge'` and
+      # per-lexer autoload costs *here*, on the background preload
+      # thread, so the first user-visible render of a slide with
+      # fenced code doesn't sit waiting for Rouge to load. Pure CPU
+      # work into a thread-safe in-process cache — no terminal I/O —
+      # so it deliberately runs outside the renderer mutex (no point
+      # blocking a foreground render on tokenization).
+      slide.blocks.each do |block|
+        next unless block[:type] == :code_block && block[:language]
+        CodeHighlighter.highlight(block[:content], block[:language],
+                                  theme: highlight_theme_name)
+      end
+
       return unless ImageUtil.kitty_terminal?
 
       @mutex.synchronize do
@@ -94,23 +221,804 @@ module Przn
       end
     end
 
+    # Public entrypoint for the controller's runner-bar refresh thread.
+    # Recomputes just the bottom-row 🐇/🐢 / N-M counter — leaves the
+    # rest of the slide untouched. No-op when the theme didn't opt
+    # into the runner bar (no `counter.duration`) or we're in export
+    # mode. Serialized against full slide renders via the renderer's
+    # mutex so the background thread can't tear writes.
+    def redraw_runner_bar(current:, total:, started_at:)
+      return if @export_mode
+      return unless counter_duration
+      return if @counter_hidden
+      @mutex.synchronize do
+        draw_runner_bar(@terminal.height, @terminal.width, current, total, started_at)
+        @terminal.flush
+      end
+    end
+
+    # Mouse hit test for dragging the 🐇. Returns the grab offset (cell
+    # column of the press minus the rabbit's left column) when `row` /
+    # `col` land on the rabbit, nil otherwise — including whenever the
+    # runner bar isn't on screen. A cell of slack either side makes the
+    # 4-cell glyph easier to catch.
+    def runner_grab(row, col, current:, total:)
+      return nil unless runner_bar_shown?
+      h = @terminal.height
+      track = runner_track(@terminal.width, current, total)
+      return nil unless track && row >= [h - 1, 1].max
+      rabbit_col = runner_col(current, [total - 1, 1].max, *track)
+      return nil unless col.between?(rabbit_col - 1, rabbit_col + EMOJI_RUNNER_CELLS)
+      col - rabbit_col
+    end
+
+    # Inverse of `runner_col`: the slide index whose rabbit position is
+    # nearest to `rabbit_col`, clamped to the deck. `current` fixes the
+    # track geometry (the left anchor's digit count shifts it).
+    def runner_slide_at(rabbit_col, current:, total:)
+      track = runner_track(@terminal.width, current, total)
+      return current unless track
+      track_left, track_right = track
+      span = (track_right - (EMOJI_RUNNER_CELLS - 1)) - track_left
+      return current if span <= 0
+      max = [total - 1, 1].max
+      ((rabbit_col - track_left).to_f / span * max).round.clamp(0, total - 1)
+    end
+
+    # How many discrete steps a slide has — one per `<wait/>` block,
+    # plus one for the initial state with nothing revealed. The
+    # controller uses this to decide whether Space advances within
+    # the slide or flips to the next one.
+    def step_count(slide)
+      slide.blocks.sum { |b| block_step_count(b) } + 1
+    end
+
+    # Number of step boundaries a block contributes — `:wait` blocks
+    # contribute 1, list blocks contribute one per item flagged with
+    # `:wait` (an inline `<wait/>` on a list item, parsed by the
+    # `LEADING_WAIT_RE` strip path), fragment blocks contribute 1
+    # (each `<at fragment="…">` adds an implicit step boundary before
+    # itself, matching reveal.js parity), everything else contributes 0.
+    def block_step_count(block)
+      case block[:type]
+      when :wait then 1
+      when :unordered_list, :ordered_list
+        block[:items].count { |i| i[:wait] }
+      else
+        block[:fragment] ? 1 : 0
+      end
+    end
+
+    # Longest `duration_ms` among the `:action` and fragment blocks
+    # whose `block_step` matches the given step. Returns 0 if neither
+    # an action nor a fragment at that step has a duration — the
+    # controller takes the snap path when this is 0, the animation loop
+    # otherwise. Fragment blocks pull their duration from
+    # `theme.fragment.duration` (default 300 ms).
+    def max_duration_for_step(slide, step)
+      bstep = compute_block_step(slide.blocks)
+      max = 0.0
+      slide.blocks.each do |b|
+        next unless (bstep[b] || 0) == step
+        d = if b[:type] == :action && b[:duration_ms]
+              b[:duration_ms]
+            elsif b[:fragment]
+              fragment_duration_ms
+            end
+        max = d if d && d > max
+      end
+      max
+    end
+
+    # Duration (ms) for a fragment animation — read from
+    # `theme.fragment.duration` with a hardcoded 300 ms fallback. Lives
+    # here (not on the controller) so any caller of the renderer reuses
+    # the same value. Returned as Float so `Controller#animate_step`'s
+    # `elapsed / duration_ms` lerps fractionally per frame — an integer
+    # value here triggers integer division and pins progress at 0 until
+    # the final frame.
+    def fragment_duration_ms
+      ((@theme && @theme.respond_to?(:fragment) && @theme.fragment && @theme.fragment[:duration]) || 300).to_f
+    end
+
     private
 
+    # Tiny stand-in for @terminal that swallows writes. Used by
+    # `suppressed_render` so a hidden block's render path still runs
+    # end-to-end (returning the same row advancement it would have
+    # produced visibly), but no bytes reach the real terminal.
+    # Mirrors the @terminal interface the renderer touches (see
+    # `grep -o '@terminal\.\w*' lib/przn/renderer.rb`).
+    class NullTerm
+      def initialize(real)
+        @width = real.width
+        @height = real.height
+        @cell_px = real.respond_to?(:cell_pixel_size) ? real.cell_pixel_size : [10, 20]
+      end
+      def width;  @width;  end
+      def height; @height; end
+      def cell_pixel_size; @cell_px; end
+      def write(_); end
+      def move_to(_, _); end
+      def clear; end
+      def flush; end
+    end
+
+    # Walk slide.blocks once and assign each block the step at which
+    # it becomes visible (= the count of `:wait` blocks preceding it).
+    # Returns a Hash keyed by the block dict itself (object identity)
+    # because the same dicts flow through route_blocks_to_slots into
+    # the layout pass and through the no-layout pass — both pick them
+    # back up by reference.
+    def compute_block_step(blocks)
+      step = 0
+      map = {}
+      blocks.each do |block|
+        # Fragment blocks declare their own step boundary AHEAD of their
+        # rendering — the bump runs BEFORE the assignment so the fragment
+        # block lands AT its post-boundary step, not on the step preceding
+        # it. `:wait` and list-item waits keep the existing post-assignment
+        # bump (the wait/item itself stays "at" the step it's revealed at,
+        # following blocks live one step further).
+        step += 1 if block[:fragment]
+        map[block] = step
+        case block[:type]
+        when :wait then step += 1
+        when :unordered_list, :ordered_list
+          step += block[:items].count { |i| i[:wait] }
+        end
+      end
+      map
+    end
+
+    # Build the "effective state" map for the current step: walk every
+    # `:action` block in slide order, and for each one that's already
+    # been triggered (block_step[a] <= current_step), accumulate its
+    # attr overrides under `state[target_id]`. Later actions targeting
+    # the same id overwrite earlier ones, so the final state is "the
+    # latest action that fired against each target."
+    #
+    # When `progress < 1.0`, an action at `block_step == current_step`
+    # is treated as partway through its `duration_ms` interpolation:
+    # each numeric attr blends from its prior value (whatever earlier
+    # actions left, or the target block's original attr) toward the
+    # action's new value. Actions on EARLIER steps are always fully
+    # applied — progress only affects the just-revealed ones.
+    #
+    # Returns `{target_id => {key => value, ...}}` where keys are
+    # stringified attr names — `effective_attrs` reconciles against
+    # the target block's own key style at merge time.
+    def compute_effective_state(blocks, block_step, current_step, progress = 1.0)
+      # Pre-index id'd blocks so an animating action can look up its
+      # target's *original* attr values when no earlier action has
+      # claimed the same key yet. Walks into `:group` children too so
+      # `<action target="inner"/>` on the same slide can drive a child
+      # of a sibling group, mirroring the deck-wide find_by_id index.
+      by_id = {}
+      index_ids = lambda do |bs|
+        bs.each do |b|
+          a = b[:attrs] || {}
+          bid = a['id'] || a[:id]
+          by_id[bid] = b if bid
+          index_ids.call(b[:children]) if b[:children].is_a?(Array)
+        end
+      end
+      index_ids.call(blocks)
+
+      state = {}
+      # Fragment pass — synthesize an action-equivalent state for each
+      # block carrying `:fragment`. Walks first so a later explicit
+      # `<action target="…">` overrides anything the fragment leaves.
+      blocks.each do |block|
+        next unless block[:fragment]
+        apply_fragment_state(state, block, block_step, current_step, progress)
+      end
+
+      blocks.each do |block|
+        next unless block[:type] == :action
+        bstep = block_step[block] || 0
+        next if bstep > current_step
+
+        attrs = block[:attrs] || {}
+        target = attrs[:target] || attrs['target']
+        next unless target
+
+        # An action animates only when (a) it carries duration_ms,
+        # (b) its step is the just-revealed one, and (c) we were
+        # called with progress < 1.0. Otherwise it snaps (v2 behavior).
+        animating = block[:duration_ms] && bstep == current_step && progress < 1.0
+
+        bucket = (state[target] ||= {})
+        target_block = by_id[target]
+        target_attrs = (target_block && target_block[:attrs]) || {}
+
+        attrs.each do |k, v|
+          key = k.to_s
+          next if key == 'target' || key == 'duration'
+          if animating
+            prev = bucket[key] || target_attrs[key] || target_attrs[key.to_sym]
+            # `opacity` has a semantic default of 1.0 — a block with no
+            # explicit opacity is fully opaque. Other attrs (x / y / w /
+            # h) have no universal default, so lerp_attr's nil→snap
+            # behavior stays correct for them. Without this, a plain
+            # fade-out (`<action opacity="0" .../>` targeting a block
+            # that never declared its initial opacity) would snap to 0
+            # instead of interpolating from 1.
+            prev = '1.0' if prev.nil? && key == 'opacity'
+            bucket[key] = lerp_attr(prev, v, progress)
+          else
+            bucket[key] = v
+          end
+        end
+      end
+      state
+    end
+
+    # Cells of positional offset baked into the four directional
+    # fragment styles. `fade-up` starts FRAG_OFFSET_Y cells *below* its
+    # declared y (so it slides upward into place); fade-down mirrors.
+    # Horizontal styles use the wider FRAG_OFFSET_X (text is roughly
+    # half as tall as it is wide on a cell grid). All hardcoded in v1;
+    # a theme knob can land later if anyone wants to tune the throw.
+    FRAG_OFFSET_Y = 2
+    FRAG_OFFSET_X = 4
+
+    # Synthesize an action-equivalent override for a fragment block at
+    # the current step. Writes into `state[block.id]` the same way the
+    # explicit `<action>` pass does — but uses the fragment's `style` to
+    # decide what the "before" state is (the offset position + opacity 0)
+    # versus the "after" state (the block's own declared attrs). When
+    # `current_step < bstep`, the block hasn't been revealed yet — pin it
+    # at the offset position. When `current_step == bstep` and
+    # `progress < 1.0`, lerp from offset → declared. Once
+    # `current_step > bstep` we leave no override; the block's own attrs
+    # take over (which is exactly the declared, final state).
+    def apply_fragment_state(state, block, block_step, current_step, progress)
+      bid = (block[:attrs] && (block[:attrs]['id'] || block[:attrs][:id])) or return
+      bstep = block_step[block] || 0
+      return if current_step > bstep   # past reveal: declared attrs win
+      initial = fragment_initial_attrs(block) or return
+      bucket = (state[bid] ||= {})
+      if current_step < bstep
+        # Pre-reveal: pin the offset state. No lerp.
+        initial.each { |k, v| bucket[k] = v }
+      else
+        # Animating at bstep — lerp each offset attr toward the declared
+        # value (or 1.0 for opacity, which has no per-attr fallback).
+        declared = block[:attrs] || {}
+        initial.each do |k, v|
+          target = declared[k] || declared[k.to_sym] || (k == 'opacity' ? '1.0' : nil)
+          bucket[k] = lerp_attr(v, target, progress)
+        end
+      end
+    end
+
+    # Compute the "before reveal" attrs for a fragment style — the
+    # state the renderer pins the block at when current_step has not
+    # yet reached the fragment's own step. Returns `{key => value}`
+    # with string keys (matching `state[id]` convention). Non-numeric
+    # x/y (e.g. `x="center"`) skip the offset; only opacity gets set —
+    # the block still slides into existence visually via the fade.
+    def fragment_initial_attrs(block)
+      attrs = block[:attrs] || {}
+      case block[:fragment].to_s
+      when 'fade-up'
+        {'opacity' => '0'}.merge(offset_attr('y', attrs, +FRAG_OFFSET_Y))
+      when 'fade-down'
+        {'opacity' => '0'}.merge(offset_attr('y', attrs, -FRAG_OFFSET_Y))
+      when 'fade-left'
+        {'opacity' => '0'}.merge(offset_attr('x', attrs, +FRAG_OFFSET_X))
+      when 'fade-right'
+        {'opacity' => '0'}.merge(offset_attr('x', attrs, -FRAG_OFFSET_X))
+      when 'fade-in'
+        {'opacity' => '0'}
+      else
+        nil   # unknown style — no-op
+      end
+    end
+
+    # Compute the offset variant of one positional attr. Numeric coords
+    # shift by `delta` cells; non-numeric coords (keyword `center`, `%`
+    # values, etc.) pass through unchanged so the lerp still has a
+    # consistent prev/target and falls back to "snap" on its own.
+    def offset_attr(key, attrs, delta)
+      v = attrs[key] || attrs[key.to_sym]
+      return {} if v.nil?
+      parsed = parse_dimension(v)
+      return {key => v} unless parsed && parsed[1] == ''   # cells only
+      shifted = parsed[0] + delta
+      shifted = shifted.to_i if shifted == shifted.to_i
+      {key => shifted.to_s}
+    end
+
+    # Split a coordinate-ish string into `[numeric_float, unit_string]`.
+    # `"15"` → `[15.0, ""]`, `"50%"` → `[50.0, "%"]`, `"100px"` →
+    # `[100.0, "px"]`, `"4c"` → `[4.0, "c"]`. Returns nil for garbage —
+    # `lerp_attr` uses that as the "can't interpolate, snap" signal.
+    def parse_dimension(str)
+      return nil if str.nil?
+      m = str.to_s.strip.match(/\A(-?\d+(?:\.\d+)?)([a-zA-Z%]*)\z/)
+      m && [m[1].to_f, m[2]]
+    end
+
+    # Blend two attr strings at `progress` in [0, 1].
+    #
+    #   lerp_attr("15", "50", 0.5)   → "32.5"
+    #   lerp_attr("20%", "80%", 0.5) → "50.0%"
+    #
+    # Returns `target_str` unchanged when:
+    #   - prev is nil (no prior value to blend from),
+    #   - either side fails to parse as a dimension,
+    #   - the two sides use different units (can't meaningfully blend),
+    #   - progress is at or past 1.0 (settled).
+    # These are graceful instant-fallback paths — the animation just
+    # snaps for that attr instead of trying to fake an interpolation.
+    def lerp_attr(prev_str, target_str, progress)
+      return target_str if prev_str.nil? || progress >= 1.0
+      prev = parse_dimension(prev_str)
+      targ = parse_dimension(target_str)
+      return target_str unless prev && targ && prev[1] == targ[1]
+      blended = prev[0] + progress * (targ[0] - prev[0])
+      num = blended == blended.to_i ? blended.to_i.to_s : blended.to_s
+      "#{num}#{prev[1]}"
+    end
+
+    # Merge a block's stored attrs with any action-driven overrides
+    # for that block's id. The block's original key style (string vs
+    # symbol) is preserved so the downstream render path keeps
+    # reading attrs the same way it always has — only the values
+    # change.
+    def effective_attrs(block)
+      attrs = block[:attrs] || {}
+      return attrs unless @effective_state
+      id = attrs['id'] || attrs[:id]
+      override = id && @effective_state[id]
+      return attrs unless override
+
+      result = attrs.dup
+      override.each do |k, v|
+        if attrs.key?(k.to_sym)
+          result[k.to_sym] = v
+        else
+          result[k.to_s] = v
+        end
+      end
+      result
+    end
+
+    # True when this block hasn't been revealed yet at the current
+    # step. Pre-pass uses this to skip hidden positioned content
+    # outright; the flow pass uses it to switch to `suppressed_render`.
+    def hidden?(block)
+      ((@block_step && @block_step[block]) || 0) > (@current_step || 0)
+    end
+
+    # Visibility-aware wrapper around `render_block`. Visible blocks
+    # render normally; hidden ones go through `suppressed_render`,
+    # which advances the row the same amount but writes nothing —
+    # so layout stays stable as the user advances steps, instead of
+    # everything reflowing up each time a new block reveals.
+    def render_block_or_reserve(block, width, row, align: nil)
+      if hidden?(block)
+        suppressed_render(block, width, row, align: align)
+      else
+        render_block(block, width, row, align: align)
+      end
+    end
+
+    # Run the full render_block path with @terminal swapped to a
+    # NullTerm. The block's natural row advancement is preserved
+    # (every height-aware render function computes its own row math
+    # and returns the new row), so reserving layout space happens
+    # automatically without duplicating per-block-type measurements.
+    def suppressed_render(block, width, row, align: nil)
+      real = @terminal
+      @terminal = NullTerm.new(real)
+      begin
+        render_block(block, width, row, align: align)
+      ensure
+        @terminal = real
+      end
+    end
+
+    # Dry-render the slot's block list and return how many rows it
+    # would occupy — the content height that `y: center` / `bottom`
+    # need before they can position the slot. Blocks that don't
+    # render (`:wait`, `:action`) are dropped; the `@measuring_last`
+    # flag is set for the FINAL renderable block so its trailing
+    # padding is excluded from the measurement (without that h1's
+    # built-in "+4 rows after the heading" makes a single-h1 slot
+    # measure 4 rows taller than it actually occupies, biasing the
+    # centred position upward by 2 rows).
+    def measure_blocks_content_height(blocks, width, slot_align)
+      visible = blocks.reject { |b| %i[wait action align].include?(b[:type]) }
+      return 0 if visible.empty?
+
+      real = @terminal
+      @terminal = NullTerm.new(real)
+      row = 0
+      pending_align = nil
+      begin
+        blocks.each do |block|
+          case block[:type]
+          when :align then pending_align = block[:align]
+          when :wait, :action then next
+          else
+            @measuring_last = block.equal?(visible.last)
+            row = render_block_or_reserve(block, width, row, align: pending_align || slot_align)
+            pending_align = nil
+          end
+        end
+      ensure
+        @measuring_last = false
+        @terminal = real
+      end
+      row
+    end
+
+    # Move the terminal cursor in flow-mode block coordinates: `col` is
+    # measured from the left of the current slot (or from the screen edge
+    # when no slot is active, @x_offset = 0). Screen-absolute emits
+    # (footer, runner bar, render_at, `<img x y>`) bypass this and call
+    # @terminal.move_to directly so a layout context can't shift them.
+    def term_move(row, col)
+      @terminal.move_to(row, col + @x_offset)
+    end
+
+    # Body-text OSC 66 scale (1-7). Reads `theme.font.size` and resolves
+    # via Parser::SIZE_SCALES (so `xx-small` / `2` / `large` all map to
+    # the same table title.size uses), falling back to DEFAULT_SCALE
+    # when unset. Consulted everywhere body text is rendered or
+    # vertically advanced — paragraphs, list items, blockquotes,
+    # code blocks, definition lists, table rows, blank rows, h2–h6.
+    def body_scale
+      size = @theme.font && @theme.font[:size]
+      (size && Parser::SIZE_SCALES[size.to_s]) || DEFAULT_SCALE
+    end
+
+    # Parsed `theme.counter.duration` in seconds, or nil when unset /
+    # unparseable. Truthy here is what opts the bottom row into the
+    # 🐇 / 🐢 runner bar; nil falls back to the plain " N / M " counter.
+    def counter_duration
+      raw = @theme.counter && @theme.counter[:duration]
+      raw && Theme.parse_duration(raw)
+    end
+
+    # The 🐇 / 🐢 bar is what's on the bottom row right now.
+    def runner_bar_shown?
+      !@export_mode && counter_duration && !@counter_hidden
+    end
+
+    # True when the slide's h1 IAL carries `counter=hide`. Duck-typed on
+    # `attrs` so callers can hand in lightweight slide stand-ins.
+    def counter_hidden?(slide)
+      attrs = slide.respond_to?(:attrs) && slide.attrs
+      !!(attrs && attrs[:counter].to_s == 'hide')
+    end
+
+    # Open-SGR for the bottom-row counter (plain `N / M` and the
+    # runner-bar anchor numbers). Honors `theme.counter.color`
+    # (named ANSI or 6-digit hex); falls back to the dim ANSI default.
+    def counter_color_open
+      c = @theme.counter && @theme.counter[:color]
+      (c && !c.to_s.empty?) ? color_code(c.to_s) : ANSI[:dim]
+    end
+
+    # Resolve the current slot's `size:` override into an OSC 66 scale
+    # (1-7). nil when no slot styling applies or the slot didn't set
+    # a size — caller falls back to its own default (HEADING_SCALES,
+    # body_scale, etc.).
+    def slot_scale
+      return nil unless @slot_style
+      name = @slot_style[:size]
+      name && Parser::SIZE_SCALES[name]
+    end
+
+    # The active slot's `family:` override, or nil.
+    def slot_family
+      @slot_style && @slot_style[:family]
+    end
+
+    # The active slot's `color:` override, or nil.
+    def slot_color
+      @slot_style && @slot_style[:color]
+    end
+
+    # Group a slide's blocks into per-slot lists and render each slot in
+    # its own region. The first slot named `title` (if any) is auto-filled
+    # from the h1; remaining slots fill in declaration order, advanced by
+    # a `<slot/>` block. `<slot name="...">` jumps to that slot if it
+    # exists. Slots whose blocks would resolve to an invalid region (x/y
+    # missing or unparseable) are skipped silently.
+    def render_layout(slide, slots, width, height)
+      buckets = route_blocks_to_slots(slide.blocks, slots)
+
+      cell_w, cell_h = @terminal.cell_pixel_size
+      slots.each do |slot|
+        blocks = buckets[slot.name] || []
+        next if blocks.empty?
+        # Resolve slot width + height first — keyword `x:` / `y:`
+        # need them to know where the slot's edges should land.
+        w = resolve_at_coord(slot.width, width, cell_px: cell_w)
+        h = resolve_at_coord(slot.height, height, cell_px: cell_h)
+        next unless w
+        # `x:` may be numeric / `%` / `c` / `px` (slot starts at that
+        # column, alignment defaults to :left) OR a keyword (`left` /
+        # `center` / `right`). For keywords, the slot's effective
+        # starting column is computed from `width` and the slide
+        # width, AND the alignment passed into block rendering is
+        # taken from the keyword too — replacing the separate
+        # `align:` key that used to do this.
+        x_kw = alignment_keyword(slot.x, :x)
+        if x_kw
+          x = alignment_keyword_cell(x_kw, width, w, :x)
+          slot_align = x_kw.to_sym  # :left | :center | :middle | :right
+          slot_align = :center if slot_align == :middle
+        else
+          x = resolve_at_coord(slot.x, width, cell_px: cell_w)
+          slot_align = nil
+        end
+        next unless x
+
+        # Install the slot's text-style overrides BEFORE measuring,
+        # so the dry-render that y-keyword centering relies on picks
+        # up the slot's `size:` (which an h1 at `xxxx-large` needs to
+        # know about to wrap at scale 7 instead of the default 4 and
+        # to claim 7 rows per line). Restored in `ensure` below.
+        prev_offset = @x_offset
+        prev_style = @slot_style
+        @x_offset = x - 1
+        @slot_style = {size: slot.size, family: slot.family, color: slot.color}.compact
+        @slot_style = nil if @slot_style.empty?
+        begin
+          # `y:` mirrors `x:` — same five forms — but doesn't carry an
+          # "alignment of blocks WITHIN the slot" side-effect (the slot
+          # just starts rendering downward from row `y`). Keyword
+          # behavior centers the *content*, not the slot's region:
+          # `y: center` puts the rendered content's vertical centre at
+          # the slide's vertical centre regardless of `slot.height`,
+          # `y: bottom` anchors the content's last row to the slide's
+          # last row. `slot.height` only matters for numeric `y:` and
+          # for the (already-respected) slot-content extent.
+          y_kw = alignment_keyword(slot.y, :y)
+          y =
+            case y_kw
+            when 'top'
+              1
+            when 'center', 'middle'
+              content_h = measure_blocks_content_height(blocks, w, slot_align)
+              [(height - content_h) / 2 + 1, 1].max
+            when 'bottom'
+              content_h = measure_blocks_content_height(blocks, w, slot_align)
+              [height - content_h + 1, 1].max
+            else
+              resolve_at_coord(slot.y, height, cell_px: cell_h)
+            end
+          next unless y
+          row = y
+          pending_align = nil
+          blocks.each do |block|
+            case block[:type]
+            when :align  then pending_align = block[:align]
+            when :wait   then next
+            when :action then next  # mutation already applied via @effective_state
+            else
+              row = render_block_or_reserve(block, w, row, align: pending_align || slot_align)
+              pending_align = nil
+            end
+          end
+        ensure
+          @x_offset = prev_offset
+          @slot_style = prev_style
+        end
+      end
+    end
+
+    # Walk the slide's blocks once and bucket each one into a slot name.
+    # The h1 (first heading at level 1) goes into the `title` slot when
+    # one exists. Remaining blocks fill the first non-title slot until a
+    # `:slot` block advances the cursor (`<slot/>` → next slot;
+    # `<slot name="X"/>` → jump to slot X by name). Blocks past the last
+    # slot are silently dropped — the slot list is the layout contract.
+    def route_blocks_to_slots(blocks, slots)
+      buckets = Hash.new { |h, k| h[k] = [] }
+      title_slot = slots.find { |s| s.name == 'title' }
+      non_title_slots = title_slot ? slots.reject { |s| s.equal?(title_slot) } : slots
+      cursor = 0  # index into non_title_slots
+
+      blocks.each do |block|
+        if title_slot && block[:type] == :heading && block[:level] == 1 && !buckets.key?('title')
+          buckets['title'] << block
+        elsif block[:type] == :slot
+          if block[:name]
+            idx = non_title_slots.index { |s| s.name == block[:name] }
+            cursor = idx if idx
+          else
+            cursor += 1
+          end
+        else
+          next if cursor >= non_title_slots.size
+          buckets[non_title_slots[cursor].name] << block
+        end
+      end
+      buckets
+    end
+
     def render_block(block, width, row, align: nil)
-      case block[:type]
-      when :heading         then render_heading(block, width, row)
-      when :paragraph       then render_paragraph(block, width, row, align: align)
-      when :code_block      then render_code_block(block, width, row)
-      when :unordered_list  then render_unordered_list(block, width, row)
-      when :ordered_list    then render_ordered_list(block, width, row)
-      when :definition_list then render_definition_list(block, width, row)
-      when :blockquote      then render_blockquote(block, width, row)
-      when :table           then render_table(block, width, row)
-      when :image           then render_image(block, width, row)
-      when :blank           then row + DEFAULT_SCALE
-      when :bg              then row
-      when :at              then render_at(block); row
-      else row + 1
+      with_block_opacity(block) do
+        case block[:type]
+        when :heading         then render_heading(block, width, row, align: align)
+        when :paragraph       then render_paragraph(block, width, row, align: align)
+        when :code_block      then render_code_block(block, width, row)
+        when :unordered_list  then render_unordered_list(block, width, row)
+        when :ordered_list    then render_ordered_list(block, width, row)
+        when :definition_list then render_definition_list(block, width, row)
+        when :blockquote      then render_blockquote(block, width, row)
+        when :table           then render_table(block, width, row)
+        when :image           then render_image_or_skip(block, width, row)
+        when :mermaid         then render_mermaid(block, width, row)
+        when :shape           then row   # rendered in render()'s pre-pass
+        when :blank           then row + body_scale
+        when :bg              then row
+        when :slot            then row
+        when :wait            then row   # step boundary marker, not a renderable
+        when :action          then row   # state mutation, applied via effective_attrs
+        when :at              then render_at(block); row
+        when :ref             then render_ref(block, width, row, align: align)
+        when :group           then render_group(block, width, row, align: align)
+        else row + 1
+        end
+      end
+    end
+
+    # Walk a `<group>`'s children in declaration order, threading the
+    # row through each child's render. Mirrors the top-level slide walk
+    # (renderer.rb's `slide.blocks.each` body and the layout path's
+    # `blocks.each`) — the same `:align` / `:wait` / `:action` handling
+    # so a group is a transparent container: anything that works at
+    # slide top level works inside a group. v1 caveat: `:wait` children
+    # don't drive sub-steps (compute_block_step only walks slide.blocks,
+    # not group children), so all children render at every step.
+    #
+    # `:shape` and fully-positioned `:image` children get dispatched to
+    # their renderers DIRECTLY here, not through render_block_or_reserve.
+    # At slide top level those types are drawn in render()'s pre-pass
+    # and skipped during the flow walk; the pre-pass doesn't recurse
+    # into group children, so without these inline calls a `<rect>` or
+    # positioned `<img>` inside a `<group>` would silently disappear
+    # (and so would the ref'd copy on another slide).
+    def render_group(block, width, row, align: nil)
+      pending_align = align
+      (block[:children] || []).each do |child|
+        case child[:type]
+        when :align then pending_align = child[:align]
+        when :wait, :action then next
+        when :shape then render_shape(child)
+        when :image
+          attrs = effective_attrs(child)
+          if attrs['x'] && attrs['y']
+            render_image(child, width, row)
+          else
+            row = render_block_or_reserve(child, width, row, align: pending_align)
+            pending_align = nil
+          end
+        else
+          row = render_block_or_reserve(child, width, row, align: pending_align)
+          pending_align = nil
+        end
+      end
+      row
+    end
+
+    # Render a `<mermaid>` block by shelling out to mmdc once per
+    # unique source (cached for the session), then dispatch as an
+    # inline image. Per-block IAL (`{height=70%}` etc.) carries
+    # through to the synthetic image's attrs, so sizing is the same
+    # surface `<img>` already offers.
+    #
+    # When mmdc fails (not installed, headless Chrome missing,
+    # bad-syntax source, …) we fall back to rendering the mermaid
+    # source as a plain code block so the slide still shows
+    # something useful instead of silently going blank.
+    def render_mermaid(block, width, row)
+      png_path = MermaidRenderer.render(block[:content])
+      if png_path && File.exist?(png_path)
+        synthetic = {
+          type: :image,
+          path: png_path,
+          alt: '',
+          title: '',
+          attrs: (block[:attrs] || {}).transform_keys(&:to_s)
+        }
+        render_image_or_skip(synthetic, width, row)
+      else
+        # Plain-text fallback. `language: nil` skips syntax highlight;
+        # the dim-gray bg + body font shape still makes the source
+        # readable and obvious that something failed to render.
+        render_code_block(
+          {type: :code_block, content: block[:content], language: nil},
+          width, row
+        )
+      end
+    end
+
+    # Resolve a `<ref id="x"/>` block to its source declaration anywhere
+    # in the deck and re-dispatch through render_block. Same-tag attrs
+    # on the `<ref>` (typically x / y) override the source's. The
+    # synthetic clone is stripped of `id` so an `<action target="x"/>`
+    # on the *ref* slide can't accidentally bind to it — actions stay
+    # per-slide; the clone has no separate identity in v1.
+    def render_ref(block, width, row, align: nil)
+      return row unless @presentation
+      id = block[:attrs] && (block[:attrs][:id] || block[:attrs]['id'])
+      return row unless id
+      source = @presentation.find_by_id(id)
+      return row unless source
+
+      # Deep-clone the source so a group source's children don't share
+      # storage with the deck (otherwise the id-scrub would mutate the
+      # canonical block). Every descendant's id is stripped too — a
+      # per-slide <action target="..."/> on the ref slide must not bind
+      # to any nested child of the synthesised clone.
+      synthetic = deep_clone_strip_ids(source)
+      src_attrs = source[:attrs] || {}
+      # Merge the ref's own attrs over the clone's top-level attrs,
+      # preserving the source's per-key style (string vs symbol) so
+      # downstream renderers keep reading attrs the way they always
+      # have — same trick effective_attrs uses at the action site.
+      merged = synthetic[:attrs]
+      (block[:attrs] || {}).each do |k, v|
+        next if k.to_s == 'id'                    # never carry id forward
+        if src_attrs.key?(k.to_sym)
+          merged[k.to_sym] = v
+        elsif src_attrs.key?(k.to_s)
+          merged[k.to_s] = v
+        elsif k.is_a?(Symbol)
+          merged[k] = v
+        else
+          merged[k.to_s] = v
+        end
+      end
+
+      render_block(synthetic, width, row, align: align)
+    end
+
+    # Recursive clone of a block tree with every node's `id` stripped.
+    # Top-level dup is shallow but `:attrs` and `:children` get their
+    # own dup'd containers, so callers can mutate the result without
+    # touching the source. Used by render_ref to produce a tree whose
+    # descendants can't be action-targeted on the ref slide.
+    def deep_clone_strip_ids(block)
+      cloned = block.dup
+      attrs = (block[:attrs] || {}).dup
+      attrs.delete(:id)
+      attrs.delete('id')
+      cloned[:attrs] = attrs
+      if block[:children].is_a?(Array)
+        cloned[:children] = block[:children].map { |c| deep_clone_strip_ids(c) }
+      end
+      cloned
+    end
+
+    # Wrap a block's render with the Echoes-private OSC 7772 cell-alpha
+    # paint state when an action has driven its `opacity` (or the block
+    # itself ships an explicit `opacity=`). Non-Echoes terminals ignore
+    # the OSC. v1 only fades `put_char`-driven content (paragraphs,
+    # lists, code blocks, tables, blockquotes) — h1 multicells, runner
+    # emojis, and images stay opaque.
+    def with_block_opacity(block)
+      attrs = effective_attrs(block)
+      alpha_str = attrs['opacity'] || attrs[:opacity]
+      return yield unless alpha_str
+
+      alpha = alpha_str.to_f.clamp(0.0, 1.0)
+      return yield if alpha >= 1.0  # fully opaque — no fade to apply
+
+      @terminal.write "\e]7772;cell-alpha;#{alpha}\a"
+      begin
+        yield
+      ensure
+        @terminal.write "\e]7772;cell-alpha;1\a"
       end
     end
 
@@ -123,8 +1031,17 @@ module Przn
       attrs = block ? block[:attrs] : (@theme.background || {})
 
       @terminal.write "\e]7772;bg-clear\a"
+      clear_background_image
       return if attrs.empty?
 
+      # An `image:` background wins over color / gradient — the image
+      # covers the whole slide area at z: -1 so subsequent text and
+      # `<img>` placements draw on top.
+      if (image = attrs[:image])
+        apply_background_image(image.to_s)
+        return
+      end
+
       if (color = attrs[:color])
         @terminal.write "\e]7772;bg-color;#{color}\a"
         return
@@ -138,6 +1055,37 @@ module Przn
       @terminal.write "\e]7772;bg-gradient;type=#{type}:angle=#{angle}:colors=#{colors.join(',')}\a"
     end
 
+    # Cover the slide with a Kitty Graphics image at z: -1 so text
+    # drawn afterward layers on top. PNG only for now (relies on the
+    # in-process upload path; JPGs would need a kitten icat detour).
+    # Silently no-ops on non-Kitty terminals — the bg-clear emitted
+    # above already wiped any prior Echoes color / gradient.
+    def apply_background_image(path)
+      return unless ImageUtil.kitty_terminal?
+      resolved = resolve_image_path(path)
+      return unless File.exist?(resolved) && ImageUtil.png?(resolved)
+
+      image_id = ensure_kitty_uploaded(resolved)
+      @bg_image_id = image_id
+      @terminal.move_to(1, 1)
+      @terminal.write ImageUtil.kitty_place(
+        image_id: image_id,
+        cols: @terminal.width,
+        rows: @terminal.height,
+        z: -1
+      )
+    end
+
+    # Delete the previous slide's bg-image placement (if any) so it
+    # doesn't bleed through to a slide that defines no image bg.
+    # Image data stays cached so revisiting the same bg doesn't
+    # re-upload.
+    def clear_background_image
+      return unless @bg_image_id && ImageUtil.kitty_terminal?
+      @terminal.write ImageUtil.kitty_delete_placements(image_id: @bg_image_id)
+      @bg_image_id = nil
+    end
+
     # Place text at an absolute (column, row) on the slide, escaping the
     # normal top-down paragraph flow. Coordinates are 1-based terminal cells
     # to match the CSI cursor-position escape. A trailing `%` interprets the
@@ -148,36 +1096,730 @@ module Przn
     # The block contributes 0 to the slide's layout height so it doesn't
     # push subsequent content down.
     def render_at(block)
-      attrs = block[:attrs] || {}
-      x = resolve_at_coord(attrs[:x], @terminal.width)
-      y = resolve_at_coord(attrs[:y], @terminal.height)
-      return if x.nil? || y.nil?
+      attrs = effective_attrs(block)
+      cell_w, cell_h = @terminal.cell_pixel_size
 
       segments = Parser.parse_inline(block[:content].to_s)
-      @terminal.move_to(y, x)
-      @terminal.write render_segments_scaled(segments, DEFAULT_SCALE)
+      # Split on `:break` (from <br>) and emit each chunk on its own
+      # row at the same x. `render_segments_scaled` itself doesn't
+      # know about :break — it's a styling renderer, not a wrapping
+      # one — so we handle the line break here.
+      lines = [[]]
+      segments.each do |seg|
+        seg[0] == :break ? (lines << []) : (lines.last << seg)
+      end
+      line_heights = lines.map { |l| max_segment_scale(l, body_scale) }
+      # Content extent: widest line wins horizontally, total of per-line
+      # heights vertically. Needed up front so `x="center"` / `"right"`
+      # and `y="center"` / `"bottom"` can resolve against the actual
+      # rendered footprint, not just the terminal dimensions.
+      content_w = lines.map { |l| segments_visible_cells(l, body_scale) }.max || 0
+      content_h = line_heights.sum
+
+      x = resolve_at_axis(attrs[:x], @terminal.width,  cell_w, :x, content_w)
+      y = resolve_at_axis(attrs[:y], @terminal.height, cell_h, :y, content_h)
+      return if x.nil? || y.nil?
+
+      # Advance y by each line's *own* height (the max inline scale
+      # of its segments). When the whole `<at>` is wrapped in
+      # `<font size=1>` or `<size=1>`, the lines pack tight at
+      # 1 cell apart; a `<size=5>` line takes 5 cells before the
+      # next line starts. Falls back to body_scale when a line
+      # carries no explicit size, matching the pre-fix behavior.
+      y_cursor = y
+      lines.zip(line_heights).each do |line_segs, line_h|
+        @terminal.move_to(y_cursor, x)
+        @terminal.write render_segments_scaled(line_segs, body_scale, line_height: line_h)
+        y_cursor += line_h
+      end
     end
 
-    # Resolve an `<at>` coordinate string against the dimension it indexes.
-    # `"50%"` → halfway along `max`; plain integer string → that number of
-    # cells. Out-of-range values clamp into [1, max]. Returns nil when the
-    # input is missing or unparseable so the renderer skips silently.
-    def resolve_at_coord(raw, max)
-      return nil if raw.nil?
+    # `<at x|y="…">` extension over `resolve_at_coord` that adds the
+    # keyword forms `left|center|right` (x-axis) and `top|center|bottom`
+    # (y-axis). `middle` is accepted as a synonym of `center` for
+    # readers who think of vertical centering that way. Keywords need
+    # the content's rendered footprint (`content_extent`) so the
+    # caller measures the parsed-inline lines first, then asks here.
+    # Anything that isn't a recognised keyword falls through to
+    # `resolve_at_coord`'s numeric / `%` / `px` / `c` parsing.
+    def resolve_at_axis(raw, max, cell_px, axis, content_extent)
+      cell = alignment_keyword_cell(raw, max, content_extent, axis)
+      return cell if cell
+      resolve_at_coord(raw, max, cell_px: cell_px)
+    end
+
+    # Shared keyword → 1-based cell math used by both `<at>` and
+    # `<img>`'s `x` / `y` resolvers. The right / bottom branches
+    # anchor the content's far edge at `max`, so a 4-cell-wide
+    # block at `x="right"` on an 80-wide pane occupies cols 77-80
+    # — flush to the edge, no margin. Use percent (`x="95%"`) when
+    # you want a margin.
+    def alignment_keyword_cell(raw, max, content_extent, axis)
+      s = raw.to_s.strip.downcase
+      case axis
+      when :x
+        case s
+        when 'left'             then 1
+        when 'center', 'middle' then [(max - content_extent) / 2 + 1, 1].max
+        when 'right'            then [max - content_extent + 1, 1].max
+        end
+      when :y
+        case s
+        when 'top'              then 1
+        when 'center', 'middle' then [(max - content_extent) / 2 + 1, 1].max
+        when 'bottom'           then [max - content_extent + 1, 1].max
+        end
+      end
+    end
+
+    # Lower-case keyword string when `raw` is one of the alignment
+    # keywords recognised on `axis`; nil otherwise. Used by
+    # `render_image` to detect keywords up front and defer the cell
+    # resolution until target_cols / target_rows are known.
+    def alignment_keyword(raw, axis)
+      s = raw.to_s.strip.downcase
+      keywords = axis == :x ? %w[left center middle right] : %w[top center middle bottom]
+      keywords.include?(s) ? s : nil
+    end
+
+    # Compute a single line's vertical extent in terminal cells. Each
+    # segment contributes either its explicit `<size=...>` / `<font
+    # size="...">` scale, or `default_scale` when it has no size of
+    # its own; the line's height is the max across all of them.
+    #
+    # Crucially this can return *less* than `default_scale` — a line
+    # entirely wrapped in `<font size=1>` returns 1, so `<br>`-stacked
+    # small text packs tight at 1 cell per line instead of body_scale
+    # cells. Plain text mixed with a small-sized tag still uses
+    # body_scale (the plain part needs the room).
+    def max_segment_scale(segments, default_scale)
+      return default_scale if segments.empty?
+      segments.map { |seg|
+        type = seg[0]
+        size_key =
+          case type
+          when :tag  then seg[2]
+          when :font then (seg[2] || {})[:size]
+          end
+        Parser::SIZE_SCALES[size_key] || default_scale
+      }.max
+    end
+
+    # Draw a Keynote-style shape primitive (rect, circle, ellipse, line,
+    # polyline, polygon) by composing a tiny self-contained SVG document
+    # and shipping it via the Kitty Graphics Protocol's direct-data mode.
+    # Echoes content-sniffs the payload and rasterizes it through its
+    # native CoreGraphics fast path (sub-millisecond for path-only SVGs,
+    # which these always are).
+    #
+    # Geometry is authored in slide-cell coords (or `N%` of the terminal
+    # w/h) but composed into the SVG in **pixel** coords. The SVG
+    # viewBox matches the cell-quantized rasterization target exactly,
+    # which keeps 1 user unit = 1 pixel and avoids the anisotropic
+    # stretch that would otherwise turn `<circle>` into an ellipse
+    # (terminal cells are ~1:2 wide-to-tall). For "axis-agnostic"
+    # extents (`r`, `stroke-width`) we use `cell_w` as the canonical
+    # unit so a `circle r="5"` renders as a true circle.
+    # Shapes are absolute-positioned and contribute 0 to the layout flow.
+    def render_shape(block)
+      return unless ImageUtil.kitty_terminal?
+      kind = block[:kind]
+      attrs = effective_attrs(block)
+      cell_w, cell_h = @terminal.cell_pixel_size
+      return unless cell_w&.positive? && cell_h&.positive?
+
+      geom = resolve_shape_geometry(kind, attrs, cell_w, cell_h)
+      return unless geom
+
+      sw_user = if attrs['stroke-width']
+                  attrs['stroke-width'].to_f
+                elsif open_shape?(kind)
+                  SHAPE_DEFAULT_STROKE_WIDTH
+                else
+                  0.0
+                end
+      sw_px = sw_user * cell_w
+      pad = sw_px / 2.0
+
+      # Arrows need an arrowhead computed from the resolved stroke width
+      # (the head dimensions scale with stroke). expand_arrow_geometry
+      # adds the triangle vertices to `geom` and grows the bbox to fit.
+      geom = expand_arrow_geometry(geom, sw_px) if kind == :arrow
+
+      gx_min = geom[:bbox_x] - pad
+      gy_min = geom[:bbox_y] - pad
+      gx_max = geom[:bbox_x] + geom[:bbox_w] + pad
+      gy_max = geom[:bbox_y] + geom[:bbox_h] + pad
+
+      # Quantize the pixel bbox to whole slide cells.
+      place_col0 = (gx_min / cell_w).floor       # 0-indexed cell col
+      place_row0 = (gy_min / cell_h).floor
+      end_col0   = (gx_max / cell_w).ceil
+      end_row0   = (gy_max / cell_h).ceil
+      cols = end_col0 - place_col0
+      rows = end_row0 - place_row0
+      return if cols < 1 || rows < 1
+
+      # viewBox in pixels covers the cell-quantized footprint exactly.
+      vb_x = place_col0 * cell_w
+      vb_y = place_row0 * cell_h
+      vb_w = cols * cell_w
+      vb_h = rows * cell_h
+
+      svg = build_shape_svg(kind, attrs, geom, sw_px, vb_x, vb_y, vb_w, vb_h)
+      image_id = ensure_kitty_inline_uploaded(svg)
+      @terminal.move_to(place_row0 + 1, place_col0 + 1)
+      # z=-1 draws the shape below text but above the slide background,
+      # so heading text / paragraphs at the same cells remain legible.
+      # An explicit `z="..."` attr lets authors put a shape on top.
+      z = attrs['z'] ? attrs['z'].to_i : -1
+      @terminal.write ImageUtil.kitty_place(image_id: image_id, cols: cols, rows: rows, z: z)
+    end
+
+    # SVG paint / presentation attributes passed through to the shape
+    # element verbatim. Anything else on `block[:attrs]` is treated as
+    # geometry (consumed per-shape) and not re-emitted.
+    SHAPE_PAINT_ATTRS = %w[
+      fill stroke stroke-width opacity fill-opacity stroke-opacity
+      stroke-linecap stroke-linejoin stroke-dasharray stroke-miterlimit
+      fill-rule transform
+    ].freeze
+
+    SHAPE_DEFAULT_STROKE_WIDTH = 0.2
 
+    OPEN_SHAPES = %i[line polyline arrow path].freeze
+
+    def open_shape?(kind)
+      OPEN_SHAPES.include?(kind)
+    end
+
+    # Resolve a shape's geometry attrs to pixel coordinates. Positional
+    # attrs (x, y, cx, cy, x1, y1, x2, y2, polyline/polygon points) are
+    # 1-indexed cell coords matching `<at>` semantics — cell N maps to
+    # pixel `(N-1) * cell_dim`. Size attrs (width, height, rx, ry) are
+    # cell counts → `N * cell_dim` pixels. `r` and other "axis-agnostic"
+    # extents use `cell_w` as the canonical unit so a `circle r="5"`
+    # renders visually circular regardless of cell aspect ratio.
+    # Returns a hash with the per-shape geometry in pixels plus a
+    # `:bbox_*` quadruple covering the shape's pixel extent, or nil if
+    # any required attr is missing / unparseable.
+    def resolve_shape_geometry(kind, attrs, cell_w, cell_h)
+      case kind
+      when :rect
+        x  = to_px(attrs['x'],      :position, :x, cell_w, cell_h)
+        y  = to_px(attrs['y'],      :position, :y, cell_w, cell_h)
+        w_ = to_px(attrs['width'],  :size,     :x, cell_w, cell_h)
+        h_ = to_px(attrs['height'], :size,     :y, cell_w, cell_h)
+        return nil unless x && y && w_ && h_
+        {bbox_x: x, bbox_y: y, bbox_w: w_, bbox_h: h_, x: x, y: y, w: w_, h: h_,
+         rx: to_px(attrs['rx'], :size, :x, cell_w, cell_h),
+         ry: to_px(attrs['ry'], :size, :y, cell_w, cell_h)}
+      when :circle
+        cx = to_px(attrs['cx'], :position, :x, cell_w, cell_h)
+        cy = to_px(attrs['cy'], :position, :y, cell_w, cell_h)
+        # r is axis-agnostic: use cell_w on both axes so the rasterized
+        # shape is a true circle, not a vertical ellipse.
+        r  = to_px(attrs['r'],  :size,     :x, cell_w, cell_h)
+        return nil unless cx && cy && r
+        {bbox_x: cx - r, bbox_y: cy - r, bbox_w: 2 * r, bbox_h: 2 * r, cx: cx, cy: cy, r: r}
+      when :ellipse
+        cx = to_px(attrs['cx'], :position, :x, cell_w, cell_h)
+        cy = to_px(attrs['cy'], :position, :y, cell_w, cell_h)
+        rx = to_px(attrs['rx'], :size,     :x, cell_w, cell_h)
+        ry = to_px(attrs['ry'], :size,     :y, cell_w, cell_h)
+        return nil unless cx && cy && rx && ry
+        {bbox_x: cx - rx, bbox_y: cy - ry, bbox_w: 2 * rx, bbox_h: 2 * ry, cx: cx, cy: cy, rx: rx, ry: ry}
+      when :line, :arrow
+        # `<arrow>` shares the line's geometry surface; the renderer
+        # adds a filled triangular head at (x2, y2) once stroke_width
+        # is resolved (see expand_arrow_geometry).
+        x1 = to_px(attrs['x1'], :position, :x, cell_w, cell_h)
+        y1 = to_px(attrs['y1'], :position, :y, cell_w, cell_h)
+        x2 = to_px(attrs['x2'], :position, :x, cell_w, cell_h)
+        y2 = to_px(attrs['y2'], :position, :y, cell_w, cell_h)
+        return nil unless x1 && y1 && x2 && y2
+        {bbox_x: [x1, x2].min, bbox_y: [y1, y2].min,
+         bbox_w: (x2 - x1).abs, bbox_h: (y2 - y1).abs,
+         x1: x1, y1: y1, x2: x2, y2: y2}
+      when :polyline, :polygon
+        pts = parse_shape_points(attrs['points'], cell_w, cell_h)
+        return nil if pts.nil? || pts.empty?
+        xs = pts.map(&:first)
+        ys = pts.map(&:last)
+        {bbox_x: xs.min, bbox_y: ys.min,
+         bbox_w: xs.max - xs.min, bbox_h: ys.max - ys.min,
+         points: pts}
+      when :path
+        # Parse `d`, compute bbox in pixels, and rewrite the path data
+        # from cell-space (what the user wrote) into pixel-space (what
+        # the SVG viewBox expects). Rewriting avoids wrapping in a
+        # `<g transform="scale(...)">` — a non-uniform scale would
+        # render strokes elliptically, which is not what anyone wants.
+        path_to_pixels(attrs['d'], cell_w, cell_h)
+      end
+    end
+
+    # Convert a single coord attribute to pixels.
+    #   role:  :position — 1-indexed cell N → pixel (N-1)*cell_dim
+    #          :size     — cell count N → pixel N*cell_dim
+    #   axis:  :x → cell_w & terminal.width;  :y → cell_h & terminal.height
+    # `%` is allowed and resolves against the corresponding terminal
+    # extent before the cell→pixel conversion.
+    def to_px(raw, role, axis, cell_w, cell_h)
+      return nil if raw.nil?
       s = raw.to_s.strip
       return nil if s.empty?
 
+      cell_dim    = (axis == :x) ? cell_w : cell_h
+      total_cells = (axis == :x) ? @terminal.width : @terminal.height
+
       cells =
         if s.end_with?('%')
-          pct = s.chomp('%').to_f
-          (pct / 100.0 * max).round
-        elsif s =~ /\A-?\d+\z/
-          s.to_i
+          s.chomp('%').to_f / 100.0 * total_cells
+        elsif s =~ /\A-?[\d.]+\z/
+          s.to_f
         end
       return nil if cells.nil?
 
-      cells.clamp(1, max)
+      role == :position ? (cells - 1) * cell_dim : cells * cell_dim
+    end
+
+    # Parse a `points="x1,y1 x2,y2 …"` attribute into resolved [x, y]
+    # pixel-coord pairs. Coords are 1-indexed cells or `N%`; each
+    # x uses `:x` axis, each y uses `:y` axis. Returns nil if the token
+    # count is odd or any individual coord fails to parse.
+    def parse_shape_points(raw, cell_w, cell_h)
+      return nil if raw.nil?
+      tokens = raw.to_s.split(/[\s,]+/).reject(&:empty?)
+      return nil if tokens.empty? || tokens.size.odd?
+      pts = []
+      tokens.each_slice(2) do |xs, ys|
+        x = to_px(xs, :position, :x, cell_w, cell_h)
+        y = to_px(ys, :position, :y, cell_w, cell_h)
+        return nil if x.nil? || y.nil?
+        pts << [x, y]
+      end
+      pts
+    end
+
+    # Tokenizer / rewriter for SVG `<path d="...">` data. Returns
+    # `{bbox_x:, bbox_y:, bbox_w:, bbox_h:, d:}` (all in pixel space)
+    # or nil if the path data has an unknown command.
+    #
+    # User authors path data in 1-indexed slide cells, matching every
+    # other shape coord (`<line x1>`, `<rect x>`, polyline points …).
+    # We walk each command, accumulate every endpoint and control
+    # point as a pixel coord (over-estimates the bbox slightly for
+    # cubic / quadratic curves — control points commonly sit outside
+    # the visible curve — but that's safe), and re-emit `d` with the
+    # numbers translated. Absolute positions take the `(N-1)*cell_dim`
+    # offset; relative deltas use the unshifted `N*cell_dim`. Arc `A`
+    # / `a` rx & ry scale anisotropically (rx by cell_w, ry by
+    # cell_h) so an author who wants a circular arc has to use equal
+    # rx/ry written in cell-widths of *each* axis — same as the
+    # `<circle>` vs `<ellipse>` distinction.
+    PATH_TOKEN_RE = /[A-Za-z]|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/
+    def path_to_pixels(d_attr, cell_w, cell_h)
+      return nil if d_attr.nil?
+      tokens = d_attr.to_s.scan(PATH_TOKEN_RE)
+      return nil if tokens.empty?
+
+      xs = []
+      ys = []
+      cx = 0.0
+      cy = 0.0
+      sx = 0.0   # subpath start (for Z)
+      sy = 0.0
+      out = []
+      cmd = nil
+      i = 0
+
+      pos_x = ->(x) { (x - 1) * cell_w }
+      pos_y = ->(y) { (y - 1) * cell_h }
+      del_x = ->(x) { x * cell_w }
+      del_y = ->(y) { y * cell_h }
+
+      while i < tokens.size
+        tok = tokens[i]
+        if tok.match?(/\A[A-Za-z]\z/)
+          cmd = tok
+          out << cmd
+          i += 1
+          if cmd == 'Z' || cmd == 'z'
+            cx, cy = sx, sy
+          end
+          next
+        end
+
+        case cmd
+        when 'M', 'L', 'T'
+          x = tokens[i].to_f; y = tokens[i + 1].to_f
+          cx, cy = x, y
+          sx, sy = cx, cy if cmd == 'M'
+          px = pos_x.call(cx); py = pos_y.call(cy)
+          xs << px; ys << py
+          out << "#{fnum(px)} #{fnum(py)}"
+          i += 2
+          cmd = 'L' if cmd == 'M'
+        when 'm', 'l', 't'
+          dx = tokens[i].to_f; dy = tokens[i + 1].to_f
+          cx += dx; cy += dy
+          sx, sy = cx, cy if cmd == 'm'
+          xs << pos_x.call(cx); ys << pos_y.call(cy)
+          out << "#{fnum(del_x.call(dx))} #{fnum(del_y.call(dy))}"
+          i += 2
+          cmd = 'l' if cmd == 'm'
+        when 'H'
+          x = tokens[i].to_f
+          cx = x
+          xs << pos_x.call(cx); ys << pos_y.call(cy)
+          out << fnum(pos_x.call(cx))
+          i += 1
+        when 'h'
+          dx = tokens[i].to_f
+          cx += dx
+          xs << pos_x.call(cx); ys << pos_y.call(cy)
+          out << fnum(del_x.call(dx))
+          i += 1
+        when 'V'
+          y = tokens[i].to_f
+          cy = y
+          xs << pos_x.call(cx); ys << pos_y.call(cy)
+          out << fnum(pos_y.call(cy))
+          i += 1
+        when 'v'
+          dy = tokens[i].to_f
+          cy += dy
+          xs << pos_x.call(cx); ys << pos_y.call(cy)
+          out << fnum(del_y.call(dy))
+          i += 1
+        when 'C'
+          nums = (0..5).map { |k| tokens[i + k].to_f }
+          # Three (x, y) pairs: two control points then endpoint.
+          pairs = nums.each_slice(2).to_a
+          pairs.each { |x, y| xs << pos_x.call(x); ys << pos_y.call(y) }
+          cx, cy = pairs.last
+          out << pairs.map { |x, y| "#{fnum(pos_x.call(x))} #{fnum(pos_y.call(y))}" }.join(' ')
+          i += 6
+        when 'c'
+          nums = (0..5).map { |k| tokens[i + k].to_f }
+          pairs_rel = nums.each_slice(2).to_a
+          pairs_abs = pairs_rel.map { |dx, dy| [cx + dx, cy + dy] }
+          pairs_abs.each { |x, y| xs << pos_x.call(x); ys << pos_y.call(y) }
+          cx, cy = pairs_abs.last
+          out << pairs_rel.map { |dx, dy| "#{fnum(del_x.call(dx))} #{fnum(del_y.call(dy))}" }.join(' ')
+          i += 6
+        when 'S', 'Q'
+          nums = (0..3).map { |k| tokens[i + k].to_f }
+          pairs = nums.each_slice(2).to_a
+          pairs.each { |x, y| xs << pos_x.call(x); ys << pos_y.call(y) }
+          cx, cy = pairs.last
+          out << pairs.map { |x, y| "#{fnum(pos_x.call(x))} #{fnum(pos_y.call(y))}" }.join(' ')
+          i += 4
+        when 's', 'q'
+          nums = (0..3).map { |k| tokens[i + k].to_f }
+          pairs_rel = nums.each_slice(2).to_a
+          pairs_abs = pairs_rel.map { |dx, dy| [cx + dx, cy + dy] }
+          pairs_abs.each { |x, y| xs << pos_x.call(x); ys << pos_y.call(y) }
+          cx, cy = pairs_abs.last
+          out << pairs_rel.map { |dx, dy| "#{fnum(del_x.call(dx))} #{fnum(del_y.call(dy))}" }.join(' ')
+          i += 4
+        when 'A'
+          rx = tokens[i].to_f; ry = tokens[i + 1].to_f
+          rot = tokens[i + 2].to_f
+          la  = tokens[i + 3].to_i
+          sw_flag = tokens[i + 4].to_i
+          x = tokens[i + 5].to_f; y = tokens[i + 6].to_f
+          cx, cy = x, y
+          xs << pos_x.call(cx); ys << pos_y.call(cy)
+          out << "#{fnum(del_x.call(rx))} #{fnum(del_y.call(ry))} #{fnum(rot)} #{la} #{sw_flag} #{fnum(pos_x.call(x))} #{fnum(pos_y.call(y))}"
+          i += 7
+        when 'a'
+          rx = tokens[i].to_f; ry = tokens[i + 1].to_f
+          rot = tokens[i + 2].to_f
+          la  = tokens[i + 3].to_i
+          sw_flag = tokens[i + 4].to_i
+          dx = tokens[i + 5].to_f; dy = tokens[i + 6].to_f
+          cx += dx; cy += dy
+          xs << pos_x.call(cx); ys << pos_y.call(cy)
+          out << "#{fnum(del_x.call(rx))} #{fnum(del_y.call(ry))} #{fnum(rot)} #{la} #{sw_flag} #{fnum(del_x.call(dx))} #{fnum(del_y.call(dy))}"
+          i += 7
+        else
+          return nil
+        end
+      end
+
+      return nil if xs.empty?
+      {bbox_x: xs.min, bbox_y: ys.min,
+       bbox_w: xs.max - xs.min, bbox_h: ys.max - ys.min,
+       d: out.join(' ')}
+    end
+
+    # Compose the SVG document shipped to the terminal. The viewBox is
+    # in pixels and matches the cell-quantized rasterization footprint
+    # exactly, so 1 user unit = 1 pixel — no anisotropic stretching,
+    # circles render circular, stroke widths reproduce the exact pixel
+    # thickness we computed. Default paint colors are spelled out as
+    # `white` (not `currentColor`) so the SVG renders correctly even
+    # if Echoes doesn't propagate the root `color=` to children.
+    def build_shape_svg(kind, attrs, geom, sw_px, vb_x, vb_y, vb_w, vb_h)
+      vb = "#{fnum(vb_x)} #{fnum(vb_y)} #{fnum(vb_w)} #{fnum(vb_h)}"
+      shape_xml = shape_element(kind, attrs, geom, sw_px)
+      %(<svg xmlns="http://www.w3.org/2000/svg" viewBox="#{vb}">#{shape_xml}</svg>)
+    end
+
+    def shape_element(kind, attrs, geom, sw_px)
+      paint = shape_paint_attrs(kind, attrs, sw_px)
+      case kind
+      when :rect
+        rx = geom[:rx] ? %( rx="#{fnum(geom[:rx])}") : ''
+        ry = geom[:ry] ? %( ry="#{fnum(geom[:ry])}") : ''
+        %(<rect x="#{fnum(geom[:x])}" y="#{fnum(geom[:y])}" width="#{fnum(geom[:w])}" height="#{fnum(geom[:h])}"#{rx}#{ry}#{paint}/>)
+      when :circle
+        %(<circle cx="#{fnum(geom[:cx])}" cy="#{fnum(geom[:cy])}" r="#{fnum(geom[:r])}"#{paint}/>)
+      when :ellipse
+        %(<ellipse cx="#{fnum(geom[:cx])}" cy="#{fnum(geom[:cy])}" rx="#{fnum(geom[:rx])}" ry="#{fnum(geom[:ry])}"#{paint}/>)
+      when :line
+        %(<line x1="#{fnum(geom[:x1])}" y1="#{fnum(geom[:y1])}" x2="#{fnum(geom[:x2])}" y2="#{fnum(geom[:y2])}"#{paint}/>)
+      when :arrow
+        # Stem (line) + filled triangular head. The head's fill
+        # defaults to the stem's stroke color so the two read as one
+        # arrow; an explicit `fill="..."` on the tag overrides only
+        # the head, giving a two-tone arrow if that's what you want.
+        stem = %(<line x1="#{fnum(geom[:x1])}" y1="#{fnum(geom[:y1])}" x2="#{fnum(geom[:x2])}" y2="#{fnum(geom[:y2])}"#{paint}/>)
+        tip, b1, b2 = geom[:head]
+        head_pts = "#{fnum(tip[0])},#{fnum(tip[1])} #{fnum(b1[0])},#{fnum(b1[1])} #{fnum(b2[0])},#{fnum(b2[1])}"
+        head_fill = normalize_svg_color(attrs['fill'] || attrs['stroke'] || 'white')
+        stem + %(<polygon points="#{head_pts}" fill="#{head_fill}"/>)
+      when :polyline
+        %(<polyline points="#{points_attr(geom[:points])}"#{paint}/>)
+      when :polygon
+        %(<polygon points="#{points_attr(geom[:points])}"#{paint}/>)
+      when :path
+        # `d` has already been rewritten into pixel space by
+        # path_to_pixels — stash on the geom hash so the renderer
+        # never needs to know about cell coordinates here.
+        %(<path d="#{geom[:d]}"#{paint}/>)
+      end
+    end
+
+    # Compute the arrowhead triangle for an `<arrow>` shape and merge
+    # the result back into the geom hash. Head dimensions scale with
+    # stroke width: length 4× sw_px, width 3× sw_px — typical SVG
+    # marker proportions. Bbox grows to include the head's vertices
+    # so cell quantization reserves room for the triangle.
+    def expand_arrow_geometry(geom, sw_px)
+      x1 = geom[:x1].to_f
+      y1 = geom[:y1].to_f
+      x2 = geom[:x2].to_f
+      y2 = geom[:y2].to_f
+      dx = x2 - x1
+      dy = y2 - y1
+      len = Math.sqrt(dx * dx + dy * dy)
+      return geom if len < 1e-6
+
+      head_len = sw_px * 4.0
+      head_wid = sw_px * 3.0
+      ux = dx / len
+      uy = dy / len
+      base_cx = x2 - ux * head_len
+      base_cy = y2 - uy * head_len
+      # Perpendicular unit vector (rotate (ux,uy) by 90°).
+      perp_x = -uy * head_wid / 2.0
+      perp_y =  ux * head_wid / 2.0
+      tip = [x2, y2]
+      b1  = [base_cx + perp_x, base_cy + perp_y]
+      b2  = [base_cx - perp_x, base_cy - perp_y]
+
+      xs = [x1, x2, b1[0], b2[0]]
+      ys = [y1, y2, b1[1], b2[1]]
+      geom.merge(
+        bbox_x: xs.min,
+        bbox_y: ys.min,
+        bbox_w: xs.max - xs.min,
+        bbox_h: ys.max - ys.min,
+        head: [tip, b1, b2]
+      )
+    end
+
+    # `stroke-width` is overridden with the renderer-computed pixel
+    # value so the user's "0.3" cell-widths becomes the actual pixel
+    # count we padded the bbox by. The user's other paint attrs pass
+    # through; sensible defaults fill in fill/stroke if unset. `fill`
+    # and `stroke` get normalized through CSS_NAMED_COLORS so that
+    # SVG names Echoes' fast path doesn't know natively (tomato,
+    # gold, lavender, …) become `#rrggbb` before the SVG is shipped.
+    def shape_paint_attrs(kind, attrs, sw_px)
+      defaults =
+        if open_shape?(kind)
+          {'fill' => 'none', 'stroke' => 'white'}
+        else
+          {'fill' => 'white'}
+        end
+      out = defaults.merge(attrs.slice(*SHAPE_PAINT_ATTRS))
+      out['fill']   = normalize_svg_color(out['fill'])   if out['fill']
+      out['stroke'] = normalize_svg_color(out['stroke']) if out['stroke']
+      # Replace stroke-width (if present, or implicit on open shapes)
+      # with the pixel value matching our bbox padding.
+      if out['stroke'] && out['stroke'] != 'none' && sw_px > 0
+        out['stroke-width'] = fnum(sw_px)
+      else
+        out.delete('stroke-width')
+      end
+      out.map { |k, v| %( #{k}="#{v}") }.join
+    end
+
+    # Translate a named CSS color to `#rrggbb` so Echoes' SVG renderer
+    # gets a hex code it always parses (its native named-color list
+    # covers only ~22 of the 140 standard CSS names). Hex codes,
+    # `rgb(...)` / `rgba(...)` functions, `none`, `currentColor`, and
+    # `transparent` pass through unchanged; unknown names also pass
+    # through (let Echoes decide).
+    def normalize_svg_color(value)
+      s = value.to_s
+      return s if s.empty?
+      return s if s.start_with?('#')
+      return s if s.match?(/\A(?:rgb|rgba|hsl|hsla)\(/i)
+      down = s.downcase
+      return s if down == 'none' || down == 'currentcolor' || down == 'transparent'
+      hex = CSS_NAMED_COLORS[down]
+      hex ? "##{hex}" : s
+    end
+
+    # Full set of CSS / SVG named colors — the same 147-color table the
+    # browsers ship. We translate every name to `#rrggbb` before handing
+    # the SVG to Echoes so the deck author can write `fill="tomato"`,
+    # `stroke="lavender"`, etc. without thinking about which subset the
+    # terminal's named-color parser happens to recognize.
+    CSS_NAMED_COLORS = {
+      'aliceblue' => 'f0f8ff', 'antiquewhite' => 'faebd7', 'aqua' => '00ffff',
+      'aquamarine' => '7fffd4', 'azure' => 'f0ffff', 'beige' => 'f5f5dc',
+      'bisque' => 'ffe4c4', 'black' => '000000', 'blanchedalmond' => 'ffebcd',
+      'blue' => '0000ff', 'blueviolet' => '8a2be2', 'brown' => 'a52a2a',
+      'burlywood' => 'deb887', 'cadetblue' => '5f9ea0', 'chartreuse' => '7fff00',
+      'chocolate' => 'd2691e', 'coral' => 'ff7f50', 'cornflowerblue' => '6495ed',
+      'cornsilk' => 'fff8dc', 'crimson' => 'dc143c', 'cyan' => '00ffff',
+      'darkblue' => '00008b', 'darkcyan' => '008b8b', 'darkgoldenrod' => 'b8860b',
+      'darkgray' => 'a9a9a9', 'darkgrey' => 'a9a9a9', 'darkgreen' => '006400',
+      'darkkhaki' => 'bdb76b', 'darkmagenta' => '8b008b', 'darkolivegreen' => '556b2f',
+      'darkorange' => 'ff8c00', 'darkorchid' => '9932cc', 'darkred' => '8b0000',
+      'darksalmon' => 'e9967a', 'darkseagreen' => '8fbc8f', 'darkslateblue' => '483d8b',
+      'darkslategray' => '2f4f4f', 'darkslategrey' => '2f4f4f', 'darkturquoise' => '00ced1',
+      'darkviolet' => '9400d3', 'deeppink' => 'ff1493', 'deepskyblue' => '00bfff',
+      'dimgray' => '696969', 'dimgrey' => '696969', 'dodgerblue' => '1e90ff',
+      'firebrick' => 'b22222', 'floralwhite' => 'fffaf0', 'forestgreen' => '228b22',
+      'fuchsia' => 'ff00ff', 'gainsboro' => 'dcdcdc', 'ghostwhite' => 'f8f8ff',
+      'gold' => 'ffd700', 'goldenrod' => 'daa520', 'gray' => '808080',
+      'grey' => '808080', 'green' => '008000', 'greenyellow' => 'adff2f',
+      'honeydew' => 'f0fff0', 'hotpink' => 'ff69b4', 'indianred' => 'cd5c5c',
+      'indigo' => '4b0082', 'ivory' => 'fffff0', 'khaki' => 'f0e68c',
+      'lavender' => 'e6e6fa', 'lavenderblush' => 'fff0f5', 'lawngreen' => '7cfc00',
+      'lemonchiffon' => 'fffacd', 'lightblue' => 'add8e6', 'lightcoral' => 'f08080',
+      'lightcyan' => 'e0ffff', 'lightgoldenrodyellow' => 'fafad2', 'lightgray' => 'd3d3d3',
+      'lightgrey' => 'd3d3d3', 'lightgreen' => '90ee90', 'lightpink' => 'ffb6c1',
+      'lightsalmon' => 'ffa07a', 'lightseagreen' => '20b2aa', 'lightskyblue' => '87cefa',
+      'lightslategray' => '778899', 'lightslategrey' => '778899', 'lightsteelblue' => 'b0c4de',
+      'lightyellow' => 'ffffe0', 'lime' => '00ff00', 'limegreen' => '32cd32',
+      'linen' => 'faf0e6', 'magenta' => 'ff00ff', 'maroon' => '800000',
+      'mediumaquamarine' => '66cdaa', 'mediumblue' => '0000cd', 'mediumorchid' => 'ba55d3',
+      'mediumpurple' => '9370db', 'mediumseagreen' => '3cb371', 'mediumslateblue' => '7b68ee',
+      'mediumspringgreen' => '00fa9a', 'mediumturquoise' => '48d1cc', 'mediumvioletred' => 'c71585',
+      'midnightblue' => '191970', 'mintcream' => 'f5fffa', 'mistyrose' => 'ffe4e1',
+      'moccasin' => 'ffe4b5', 'navajowhite' => 'ffdead', 'navy' => '000080',
+      'oldlace' => 'fdf5e6', 'olive' => '808000', 'olivedrab' => '6b8e23',
+      'orange' => 'ffa500', 'orangered' => 'ff4500', 'orchid' => 'da70d6',
+      'palegoldenrod' => 'eee8aa', 'palegreen' => '98fb98', 'paleturquoise' => 'afeeee',
+      'palevioletred' => 'db7093', 'papayawhip' => 'ffefd5', 'peachpuff' => 'ffdab9',
+      'peru' => 'cd853f', 'pink' => 'ffc0cb', 'plum' => 'dda0dd',
+      'powderblue' => 'b0e0e6', 'purple' => '800080', 'rebeccapurple' => '663399',
+      'red' => 'ff0000', 'rosybrown' => 'bc8f8f', 'royalblue' => '4169e1',
+      'saddlebrown' => '8b4513', 'salmon' => 'fa8072', 'sandybrown' => 'f4a460',
+      'seagreen' => '2e8b57', 'seashell' => 'fff5ee', 'sienna' => 'a0522d',
+      'silver' => 'c0c0c0', 'skyblue' => '87ceeb', 'slateblue' => '6a5acd',
+      'slategray' => '708090', 'slategrey' => '708090', 'snow' => 'fffafa',
+      'springgreen' => '00ff7f', 'steelblue' => '4682b4', 'tan' => 'd2b48c',
+      'teal' => '008080', 'thistle' => 'd8bfd8', 'tomato' => 'ff6347',
+      'turquoise' => '40e0d0', 'violet' => 'ee82ee', 'wheat' => 'f5deb3',
+      'white' => 'ffffff', 'whitesmoke' => 'f5f5f5', 'yellow' => 'ffff00',
+      'yellowgreen' => '9acd32'
+    }.freeze
+
+    def points_attr(points)
+      points.map { |x, y| "#{fnum(x)},#{fnum(y)}" }.join(' ')
+    end
+
+    # Compact float formatting for SVG: drop trailing ".0" on integral
+    # values, otherwise emit up to three decimals. Keeps the payload
+    # short and the cache key stable.
+    def fnum(n)
+      f = n.to_f
+      i = f.to_i
+      f == i ? i.to_s : format('%.3f', f)
+    end
+
+    # Resolve a coordinate string against the dimension it indexes.
+    # Accepts four suffix forms; the bare-number case picks between cells
+    # and pixels based on `default_unit:` so each tag can pick the unit
+    # that matches its native vocabulary (`<at>` → cells, `<img>` → px).
+    #
+    #   "50%"  → halfway along `max` cells
+    #   "100px"→ 100 pixels (anchor cell + sub-cell pixel offset)
+    #   "10c"  → cell 10 (1-based; explicit)
+    #   "10"   → cell 10 OR 10 px (per default_unit)
+    #
+    # Pixel forms compute both the *anchor cell* (the 1-based cell
+    # containing that pixel) and the pixel remainder *within* that cell
+    # — useful for Kitty Graphics' `X=`/`Y=` sub-cell offsets, which
+    # give true 1-px positioning instead of snap-to-cell.
+    #
+    # By default this returns just the anchor cell (preserving the old
+    # `<at>`/`<slot>` shape). Pass `with_offset: true` to get back
+    # `[cell, px_offset_within_anchor]` instead — `<img>` uses the pair
+    # form because images can place at any sub-cell pixel; text and
+    # slots stay cell-snapped because they have to.
+    #
+    # `cell_px` is required for any px form; if it's nil and a px-form
+    # value is given, returns nil. Out-of-range values clamp into
+    # [1, max] and the sub-cell offset is zeroed if the clamp moved the
+    # cell (the placement is going off-screen anyway, no point keeping
+    # a stale offset). Returns nil when the input is missing or
+    # unparseable so the renderer skips silently.
+    def resolve_at_coord(raw, max, cell_px: nil, default_unit: :cell, with_offset: false)
+      return nil if raw.nil?
+
+      s = raw.to_s.strip
+      return nil if s.empty?
+
+      cell = nil
+      px_off = 0
+
+      if s.end_with?('%')
+        pct = s.chomp('%').to_f
+        cell = (pct / 100.0 * max).round
+      elsif (m = s.match(/\A(-?\d+(?:\.\d+)?)px\z/))
+        return nil unless cell_px && cell_px > 0
+        px = m[1].to_f
+        cell = (px / cell_px).floor + 1
+        px_off = (px - (cell - 1) * cell_px).to_i
+      elsif (m = s.match(/\A(-?\d+)c\z/))
+        cell = m[1].to_i
+      elsif s =~ /\A-?\d+(?:\.\d+)?\z/
+        if default_unit == :px
+          return nil unless cell_px && cell_px > 0
+          px = s.to_f
+          cell = (px / cell_px).floor + 1
+          px_off = (px - (cell - 1) * cell_px).to_i
+        else
+          cell = s.to_i
+        end
+      end
+      return nil if cell.nil?
+
+      clamped = cell.clamp(1, max)
+      px_off = 0 if clamped != cell
+      cell = clamped
+
+      with_offset ? [cell, px_off] : cell
     end
 
     # Bottom-row progress indicator (Rabbit-style):
@@ -186,33 +1828,43 @@ module Przn
     #   └ current slide #   └ elapsed time    └ slide progress     └ goal (total slides)
     #
     # The anchor numbers (current at the left, total at the right) sit on the
-    # very bottom row; the emojis render at OSC 66 scale 2 and are anchored at
-    # row `h-1` so their bottom half lands on row `h` next to the numbers,
-    # making them visibly twice as large as the labels without needing more
-    # vertical screen real-estate. The turtle is hidden when
-    # `theme.rabbit.duration` is unset / unparseable. `flip=h` mirrors each
-    # glyph horizontally on terminals that honor it (Echoes); others ignore
-    # the parameter and the emojis face left.
-    EMOJI_RUNNER_CELLS = 4 # 🐇/🐢 are 2 source cells wide, rendered at s=2 → 4 cells
+    # very bottom row; the runner emojis live at theme.counter[:rabbit] /
+    # [:turtle] as raw escape sequences (the default is an OSC 7772 multicell
+    # at scale 2 with flip=h, so they face right; non-Echoes terminals drop
+    # the OSC and the runner glyphs don't appear). The strings are emitted
+    # at row `h-1` so their bottom half lands on row `h` next to the anchor
+    # numbers — twice as tall as the labels without needing more rows.
+    EMOJI_RUNNER_CELLS = 4 # default 🐇/🐢 at OSC 66 s=2 occupy 4 cells; override theme keys at your peril
 
     def draw_runner_bar(h, w, current, total, started_at)
       left  = (current + 1).to_s
       right = total.to_s
-      track_left  = left.size + 2          # 1 cell gap after the left number
-      track_right = w - right.size - 1     # 1 cell gap before the right number
-      return if track_right - track_left < EMOJI_RUNNER_CELLS
+      track = runner_track(w, current, total)
+      return unless track
+      track_left, track_right = track
+
+      rabbit_row = [h - 1, 1].max
+
+      # Wipe the emoji track before redrawing so a previous turtle
+      # position (left over from the last runner-bar thread tick)
+      # doesn't ghost beside the new one. Row h has the anchor
+      # numbers — they're re-written right below so they don't need
+      # a wipe.
+      @terminal.move_to(rabbit_row, track_left)
+      @terminal.write ' ' * (track_right - track_left + EMOJI_RUNNER_CELLS)
 
+      open_seq = counter_color_open
       @terminal.move_to(h, 1)
-      @terminal.write "#{ANSI[:dim]}#{left}#{ANSI[:reset]}"
+      @terminal.write "#{open_seq}#{left}#{ANSI[:reset]}"
       @terminal.move_to(h, w - right.size + 1)
-      @terminal.write "#{ANSI[:dim]}#{right}#{ANSI[:reset]}"
+      @terminal.write "#{open_seq}#{right}#{ANSI[:reset]}"
 
-      rabbit_row = [h - 1, 1].max
+      counter = @theme&.counter || {}
       rabbit_col = runner_col(current, [total - 1, 1].max, track_left, track_right)
       @terminal.move_to(rabbit_row, rabbit_col)
-      @terminal.write KittyText.sized('🐇', s: 2, flip: 'h')
+      @terminal.write counter[:rabbit].to_s
 
-      duration_s = Theme.parse_duration(@theme.rabbit[:duration])
+      duration_s = counter_duration
       return unless started_at && duration_s && duration_s.positive?
 
       elapsed = Time.now - started_at
@@ -220,7 +1872,17 @@ module Przn
       span = (track_right - (EMOJI_RUNNER_CELLS - 1)) - track_left
       turtle_col = track_left + (frac * [span, 0].max).round
       @terminal.move_to(rabbit_row, turtle_col)
-      @terminal.write KittyText.sized('🐢', s: 2, flip: 'h')
+      @terminal.write counter[:turtle].to_s
+    end
+
+    # `[track_left, track_right]` columns of the runner track, or nil
+    # when the terminal is too narrow to fit an emoji between the anchor
+    # numbers.
+    def runner_track(w, current, total)
+      track_left  = (current + 1).to_s.size + 2   # 1 cell gap after the left number
+      track_right = w - total.to_s.size - 1        # 1 cell gap before the right number
+      return nil if track_right - track_left < EMOJI_RUNNER_CELLS
+      [track_left, track_right]
     end
 
     # Linear-interpolate a runner's column inside the track. `step` is 0..max
@@ -234,42 +1896,54 @@ module Przn
       track_left + (step.to_f / max * span).round
     end
 
-    def render_heading(block, width, row)
+    def render_heading(block, width, row, align: nil)
       text = block[:content]
 
       if block[:level] == 1
         title = @theme.title || {}
-        scale = (title[:size] && Parser::SIZE_SCALES[title[:size].to_s]) || KittyText::HEADING_SCALES[1]
-        face = title[:family]
-        color = title[:color]
+        scale = slot_scale || (title[:size] && Parser::SIZE_SCALES[title[:size].to_s]) || KittyText::HEADING_SCALES[1]
+        face = slot_family || title[:family]
+        color = slot_color || title[:color]
         max_w = max_text_width(width, 0, scale)
         segments = Parser.parse_inline(text)
         wrapped = wrap_segments(segments, max_w, scale)
 
         wrapped.each do |line_segs|
-          vis = segments_visible_cells(line_segs, scale)
-          pad = [(width - vis) / 2, 0].max
-          @terminal.move_to(row, pad + 1)
-          @terminal.write "#{ANSI[:bold]}#{render_segments_scaled(line_segs, scale, default_face: face, default_h: 2, default_color: color)}#{ANSI[:reset]}"
+          if server_centered_eligible?(line_segs, face, align, width, scale)
+            col, body = server_centered_emit(line_segs.first[1], scale, face, width)
+            body = "#{color_code(color)}#{body}#{ANSI[:reset]}" if color && !color.to_s.empty?
+            term_move(row, col)
+            @terminal.write "#{ANSI[:bold]}#{body}#{ANSI[:reset]}"
+          else
+            vis = segments_visible_cells(line_segs, scale)
+            pad = compute_pad(width, vis, align)
+            term_move(row, pad + 1)
+            @terminal.write "#{ANSI[:bold]}#{render_segments_scaled(line_segs, scale, default_face: face, default_h: 2, default_color: color)}#{ANSI[:reset]}"
+          end
           row += scale
         end
-        row + 4
+        # `+ 4` is the standard "leave a bit of breathing room
+        # below the heading before the next block." For the
+        # measure_blocks_content_height dry-run, skip it on the
+        # FINAL block so `y: center` on a single-h1 slot centres
+        # the actual text, not the text plus trailing padding.
+        @measuring_last ? row : row + 4
       else
         left = content_left(width)
         prefix = @theme.bullet[:text]
         prefix_w = display_width(prefix)
-        max_w = max_text_width(width, left, DEFAULT_SCALE) - prefix_w
+        max_w = max_text_width(width, left, body_scale) - prefix_w
         segments = Parser.parse_inline(text)
-        wrapped = wrap_segments(segments, max_w, DEFAULT_SCALE)
+        wrapped = wrap_segments(segments, max_w, body_scale)
 
         wrapped.each_with_index do |line_segs, li|
-          @terminal.move_to(row, left)
+          term_move(row, left)
           if li == 0
-            @terminal.write "#{render_bullet(prefix)}#{render_segments_scaled(line_segs, DEFAULT_SCALE)}"
+            @terminal.write "#{render_bullet(prefix)}#{render_segments_scaled(line_segs, body_scale)}"
           else
-            @terminal.write "#{KittyText.sized(' ' * prefix_w, s: DEFAULT_SCALE)}#{render_segments_scaled(line_segs, DEFAULT_SCALE)}"
+            @terminal.write "#{KittyText.sized(' ' * prefix_w, s: body_scale)}#{render_segments_scaled(line_segs, body_scale)}"
           end
-          row += DEFAULT_SCALE
+          row += body_scale
         end
         row
       end
@@ -277,118 +1951,326 @@ module Przn
 
     def render_paragraph(block, width, row, align: nil)
       text = block[:content]
-      scale = max_inline_scale(text) || DEFAULT_SCALE
+      # Two scales, not one:
+      #   - `base_scale` is the cell size for plain (unsized) text.
+      #     Always body_scale (or the active slot's override) — a
+      #     `<font size=xx-large>` somewhere in the paragraph must
+      #     NOT pull body text up with it.
+      #   - row advance happens per line and uses each line's own
+      #     `max_segment_scale` so a tall span only inflates the row
+      #     it actually appears on.
+      base_scale = slot_scale || body_scale
+      face = slot_family || @theme.font[:family]
+      color = slot_color || @theme.font[:color]
       left = content_left(width)
 
       if align
-        vis = visible_width_scaled(text, scale)
+        vis = visible_width_scaled(text, base_scale)
         left = compute_pad(width, vis, align)
       end
 
-      max_w = max_text_width(width, left, scale)
+      max_w = max_text_width(width, left, base_scale)
       segments = Parser.parse_inline(text)
-      wrapped = wrap_segments(segments, max_w, scale)
+      wrapped = wrap_segments(segments, max_w, base_scale)
 
       wrapped.each do |line_segs|
-        @terminal.move_to(row, left + 1)
-        @terminal.write render_segments_scaled(line_segs, scale)
-        row += scale
+        line_h = max_segment_scale(line_segs, base_scale)
+        if server_centered_eligible?(line_segs, face, align, width, base_scale)
+          # Hand the centering to Echoes' halign + proportional
+          # measurement so a Yu Gothic / Helvetica Neue / etc. line
+          # lands at the true pixel center rather than the cell-grid
+          # estimate compute_pad would use. Body color is wrapped
+          # around the multicell the same way render_segments_scaled
+          # would have done — otherwise this line falls through to
+          # the terminal default fg and visibly drifts from the
+          # theme.font.color / slot.color the rest of the deck uses.
+          col, body = server_centered_emit(line_segs.first[1], base_scale, face, width)
+          body = "#{color_code(color)}#{body}#{ANSI[:reset]}" if color && !color.to_s.empty?
+          term_move(row, col)
+          @terminal.write body
+        else
+          term_move(row, left + 1)
+          @terminal.write render_segments_scaled(line_segs, base_scale, line_height: line_h)
+        end
+        row += line_h
       end
       row
     end
 
     def render_code_block(block, width, row)
       code_lines = block[:content].lines.map(&:chomp)
-      return row + DEFAULT_SCALE if code_lines.empty?
+      return row + body_scale if code_lines.empty?
+
+      # `theme.code` knobs (all optional):
+      #   family — OSC 66 f= face (Echoes only); falls back to font.family.
+      #   size   — OSC 66 scale; falls back to body_scale.
+      #   color  — default fg for tokens that the highlighter didn't
+      #            paint; falls back to terminal default.
+      #   bg     — block background; falls back to the historical
+      #            dim gray (ANSI 256-color 236).
+      cfg = @theme.code || {}
+      # Per-block IAL on the fenced opener (```ruby {size=1}` etc.) wins
+      # over theme.code so an author can shrink one long snippet without
+      # touching the deck-wide default.
+      block_attrs = block[:attrs] || {}
+      size_raw = block_attrs[:size] || cfg[:size]
+      scale = (size_raw && Parser::SIZE_SCALES[size_raw.to_s]) || body_scale
+      face = block_attrs[:family] || cfg[:family] || @theme.font[:family]
+      bg_sgr = code_bg_sgr(block_attrs[:bg] || cfg[:bg])
+      default_fg = block_attrs[:color] || cfg[:color]
+      default_fg_sgr = (default_fg && color_code(default_fg)) || ''
 
       left = content_left(width)
-      max_content_w = max_text_width(width, left, DEFAULT_SCALE) - 4
+      max_content_w = max_text_width(width, left, scale) - 4
       max_len = code_lines.map { |l| display_width(l) }.max
       box_content_w = [max_len, max_content_w].min
 
-      code_lines.each do |code_line|
-        truncated = truncate_to_width(code_line, box_content_w)
-        padded = pad_to_width(truncated, box_content_w)
-        @terminal.move_to(row, left + 1)
-        @terminal.write "#{ANSI[:gray_bg]}#{KittyText.sized("  #{padded}  ", s: DEFAULT_SCALE)}#{ANSI[:reset]}"
-        row += DEFAULT_SCALE
+      highlighted = highlighted_code_lines(block, code_lines)
+
+      # Per-line highlight stepping (`{lines=1-2|3|4}` IAL): walk the
+      # pipe-separated phase the slide's current step lands on; lines
+      # outside that phase's Set get wrapped in OSC 7772 cell-alpha so
+      # Echoes paints them dim. Non-Echoes terminals drop the OSC and
+      # render every line at full opacity (documented limitation).
+      active_lines = if block[:line_steps] && @current_step && @block_step
+                       phase = (@current_step - (@block_step[block] || 0)).clamp(0, block[:line_steps].size - 1)
+                       block[:line_steps][phase]
+                     end
+
+      highlighted.each_with_index do |line_tokens, idx|
+        fitted, used_w = fit_tokens_to_width(line_tokens, box_content_w)
+        pad_len = [box_content_w - used_w, 0].max
+        dim = active_lines && !active_lines.include?(idx + 1)
+        term_move(row, left + 1)
+        @terminal.write bg_sgr
+        @terminal.write default_fg_sgr unless default_fg_sgr.empty?
+        @terminal.write "\e]7772;cell-alpha;0.35\a" if dim
+        @terminal.write KittyText.sized('  ', s: scale, f: face)
+        fitted.each do |color, value|
+          if color && !value.empty?
+            code = color_code(color)
+            @terminal.write code unless code.empty?
+            @terminal.write KittyText.sized(value, s: scale, f: face)
+            # Reset just the fg so the bg stays in effect, then reopen
+            # the theme-default fg (if any) so the next uncolored token
+            # picks it up instead of the terminal default.
+            unless code.empty?
+              @terminal.write "\e[39m"
+              @terminal.write default_fg_sgr unless default_fg_sgr.empty?
+            end
+          else
+            @terminal.write KittyText.sized(value, s: scale, f: face) unless value.empty?
+          end
+        end
+        @terminal.write KittyText.sized("#{' ' * pad_len}  ", s: scale, f: face)
+        @terminal.write "\e]7772;cell-alpha;1\a" if dim
+        @terminal.write ANSI[:reset]
+        row += scale
       end
 
       row
     end
 
+    # Resolve `theme.code.bg` to a background-color SGR. Accepts the
+    # same forms as `color_code`: CSS named colors, the ANSI palette
+    # names (red / cyan / …), and 6-digit hex (with or without `#`).
+    # An unset / unrecognised value falls back to ANSI 256-color 236
+    # — the dim gray code blocks have rendered with since v1.
+    def code_bg_sgr(value)
+      return ANSI[:gray_bg] if value.nil? || value.to_s.empty?
+      c = value.to_s.sub(/\A#/, '')
+      if (hex = CSS_NAMED_COLORS[c.downcase])
+        r, g, b = hex.scan(/../).map { |h| h.to_i(16) }
+        "\e[48;2;#{r};#{g};#{b}m"
+      elsif (ansi_fg = Parser::NAMED_COLORS[c])
+        # Translate the 30-37 / 90-97 fg codes to their 40-47 / 100-107
+        # bg counterparts (the +10 offset is the standard ANSI rule).
+        "\e[#{ansi_fg.to_i + 10}m"
+      elsif c.match?(/\A[0-9a-fA-F]{6}\z/)
+        r, g, b = c.scan(/../).map { |h| h.to_i(16) }
+        "\e[48;2;#{r};#{g};#{b}m"
+      else
+        ANSI[:gray_bg]
+      end
+    end
+
+    # Tokenize fenced code through CodeHighlighter when a language is
+    # set; fall back to a single uncolored token per line otherwise.
+    # The returned shape is always `[[[color, value], …], …]` — one
+    # outer array per code line, one inner pair per token, color is
+    # nil for "default fg" runs.
+    def highlighted_code_lines(block, code_lines)
+      tokens = block[:language] && CodeHighlighter.highlight(
+        block[:content], block[:language], theme: highlight_theme_name
+      )
+      return code_lines.map { |line| [[nil, line]] } unless tokens
+
+      group_tokens_by_line(tokens, code_lines.size)
+    end
+
+    # Read the configured Rouge theme name from `theme.code.highlight`,
+    # or nil when no theme is loaded or the key is unset (current ANSI
+    # palette).
+    def highlight_theme_name
+      @theme && @theme.code && @theme.code[:highlight]
+    end
+
+    # Walk a flat token stream and split values containing "\n" so each
+    # line gets its own array. The trailing newline on a token is
+    # dropped — render_code_block emits line-by-line and newlines are
+    # implicit between rows.
+    def group_tokens_by_line(tokens, expected_lines)
+      lines = [[]]
+      tokens.each do |color, value|
+        parts = value.split("\n", -1)
+        parts.each_with_index do |part, idx|
+          lines.last << [color, part] unless part.empty?
+          lines << [] if idx < parts.size - 1
+        end
+      end
+      # Pop a trailing empty line that comes from the source's final \n.
+      lines.pop if lines.last.empty? && lines.size > expected_lines
+      lines
+    end
+
+    # Walk tokens until the cumulative visible width hits `max_w`,
+    # truncating the last partial token if needed. Returns the
+    # fitted-token array and the total width it consumed (useful for
+    # right-padding the line).
+    def fit_tokens_to_width(line_tokens, max_w)
+      out = []
+      used = 0
+      line_tokens.each do |color, value|
+        avail = max_w - used
+        break if avail <= 0
+        w = display_width(value)
+        if w <= avail
+          out << [color, value]
+          used += w
+        else
+          out << [color, truncate_to_width(value, avail)]
+          used = max_w
+          break
+        end
+      end
+      [out, used]
+    end
+
     def render_unordered_list(block, width, row)
       left = content_left(width)
+      # Per-item step gating only applies when the list is reached via
+      # the slide-level walk that populated @block_step. Inside a group
+      # (or any nested context that doesn't seed an entry) — match the
+      # group's "no sub-steps in v1" rule and render every item.
+      gated = @block_step && @block_step.key?(block)
+      item_step = gated ? @block_step[block] : nil
       block[:items].each do |item|
-        depth = item[:depth] || 0
-        indent = '  ' * depth
-        prefix = "#{indent}#{@theme.bullet[:text]}"
-        prefix_w = display_width(prefix)
-        max_w = max_text_width(width, left, DEFAULT_SCALE) - prefix_w
-
-        segments = Parser.parse_inline(item[:text])
-        wrapped = wrap_segments(segments, max_w, DEFAULT_SCALE)
-
-        wrapped.each_with_index do |line_segs, li|
-          @terminal.move_to(row, left)
-          if li == 0
-            @terminal.write "#{render_bullet(prefix)}#{render_segments_scaled(line_segs, DEFAULT_SCALE)}"
-          else
-            @terminal.write "#{KittyText.sized(' ' * prefix_w, s: DEFAULT_SCALE)}#{render_segments_scaled(line_segs, DEFAULT_SCALE)}"
+        item_step += 1 if gated && item[:wait]
+        with_item_visibility(item_step) do
+          depth = item[:depth] || 0
+          indent = '  ' * depth
+          prefix = "#{indent}#{@theme.bullet[:text]}"
+          prefix_w = display_width(prefix)
+          # Plain text renders at body_scale; lines containing a sized
+          # span (e.g. `<size=5>BIG</size>`) advance the row by that
+          # span's height per-line. Mixing `body` and `BIG` on the same
+          # line keeps body at body size — only the BIG span grows.
+          base_scale = body_scale
+          max_w = max_text_width(width, left, base_scale) - prefix_w
+
+          segments = Parser.parse_inline(item[:text])
+          wrapped = wrap_segments(segments, max_w, base_scale)
+
+          wrapped.each_with_index do |line_segs, li|
+            line_h = max_segment_scale(line_segs, base_scale)
+            term_move(row, left)
+            if li == 0
+              @terminal.write "#{render_bullet(prefix)}#{render_segments_scaled(line_segs, base_scale, line_height: line_h)}"
+            else
+              @terminal.write "#{KittyText.sized(' ' * prefix_w, s: base_scale)}#{render_segments_scaled(line_segs, base_scale, line_height: line_h)}"
+            end
+            row += line_h
           end
-          row += DEFAULT_SCALE
+          row += 1
         end
-        row += 1
       end
       row
     end
 
     def render_ordered_list(block, width, row)
       left = content_left(width)
+      gated = @block_step && @block_step.key?(block)
+      item_step = gated ? @block_step[block] : nil
       block[:items].each_with_index do |item, i|
-        depth = item[:depth] || 0
-        indent = '  ' * depth
-        prefix = "#{indent}#{i + 1}. "
-        prefix_w = display_width(prefix)
-        max_w = max_text_width(width, left, DEFAULT_SCALE) - prefix_w
-
-        segments = Parser.parse_inline(item[:text])
-        wrapped = wrap_segments(segments, max_w, DEFAULT_SCALE)
-
-        wrapped.each_with_index do |line_segs, li|
-          @terminal.move_to(row, left)
-          if li == 0
-            @terminal.write "#{KittyText.sized(prefix, s: DEFAULT_SCALE)}#{render_segments_scaled(line_segs, DEFAULT_SCALE)}"
-          else
-            @terminal.write "#{KittyText.sized(' ' * prefix_w, s: DEFAULT_SCALE)}#{render_segments_scaled(line_segs, DEFAULT_SCALE)}"
+        item_step += 1 if gated && item[:wait]
+        with_item_visibility(item_step) do
+          depth = item[:depth] || 0
+          indent = '  ' * depth
+          prefix = "#{indent}#{i + 1}. "
+          prefix_w = display_width(prefix)
+          base_scale = body_scale
+          max_w = max_text_width(width, left, base_scale) - prefix_w
+
+          segments = Parser.parse_inline(item[:text])
+          wrapped = wrap_segments(segments, max_w, base_scale)
+
+          wrapped.each_with_index do |line_segs, li|
+            line_h = max_segment_scale(line_segs, base_scale)
+            term_move(row, left)
+            if li == 0
+              @terminal.write "#{KittyText.sized(prefix, s: base_scale)}#{render_segments_scaled(line_segs, base_scale, line_height: line_h)}"
+            else
+              @terminal.write "#{KittyText.sized(' ' * prefix_w, s: base_scale)}#{render_segments_scaled(line_segs, base_scale, line_height: line_h)}"
+            end
+            row += line_h
           end
-          row += DEFAULT_SCALE
+          row += 1
         end
-        row += 1
       end
       row
     end
 
+    # Run the block with @terminal swapped to a NullTerm if `item_step`
+    # is past the current reveal — the per-item parallel of
+    # `suppressed_render`. Items past the current step still execute
+    # their render path so `row` advances naturally (reserving layout
+    # space), but no bytes reach the real terminal. A nil `item_step`
+    # disables gating entirely (used when the surrounding block isn't
+    # reached via the slide-level step walk).
+    def with_item_visibility(item_step)
+      if item_step && @current_step && item_step > @current_step
+        real = @terminal
+        @terminal = NullTerm.new(real)
+        begin
+          yield
+        ensure
+          @terminal = real
+        end
+      else
+        yield
+      end
+    end
+
     def render_definition_list(block, width, row)
       left = content_left(width)
-      max_w = max_text_width(width, left, DEFAULT_SCALE)
+      max_w = max_text_width(width, left, body_scale)
 
       segments = Parser.parse_inline(block[:term])
-      wrapped = wrap_segments(segments, max_w, DEFAULT_SCALE)
+      wrapped = wrap_segments(segments, max_w, body_scale)
       wrapped.each do |line_segs|
-        @terminal.move_to(row, left)
-        @terminal.write "#{ANSI[:bold]}#{render_segments_scaled(line_segs, DEFAULT_SCALE)}#{ANSI[:reset]}"
-        row += DEFAULT_SCALE
+        term_move(row, left)
+        @terminal.write "#{ANSI[:bold]}#{render_segments_scaled(line_segs, body_scale)}#{ANSI[:reset]}"
+        row += body_scale
       end
 
       def_max_w = [max_w - 4, 1].max
       block[:definition].each_line do |line|
         segments = Parser.parse_inline(line.chomp)
-        wrapped = wrap_segments(segments, def_max_w, DEFAULT_SCALE)
+        wrapped = wrap_segments(segments, def_max_w, body_scale)
         wrapped.each do |line_segs|
-          @terminal.move_to(row, left + 4)
-          @terminal.write render_segments_scaled(line_segs, DEFAULT_SCALE)
-          row += DEFAULT_SCALE
+          term_move(row, left + 4)
+          @terminal.write render_segments_scaled(line_segs, body_scale)
+          row += body_scale
         end
       end
       row
@@ -398,18 +2280,18 @@ module Przn
       left = content_left(width)
       prefix = '| '
       prefix_w = display_width(prefix)
-      max_w = max_text_width(width, left + 1, DEFAULT_SCALE) - prefix_w
+      max_w = max_text_width(width, left + 1, body_scale) - prefix_w
 
       block[:content].each_line do |line|
         text = line.chomp
         segments = [[:text, text]]
-        wrapped = wrap_segments(segments, max_w, DEFAULT_SCALE)
+        wrapped = wrap_segments(segments, max_w, body_scale)
 
         wrapped.each_with_index do |line_segs, li|
-          @terminal.move_to(row, left + 1)
+          term_move(row, left + 1)
           p = li == 0 ? prefix : ' ' * prefix_w
-          @terminal.write "#{ANSI[:dim]}#{KittyText.sized(p, s: DEFAULT_SCALE)}#{render_segments_scaled(line_segs, DEFAULT_SCALE)}#{ANSI[:reset]}"
-          row += DEFAULT_SCALE
+          @terminal.write "#{ANSI[:dim]}#{KittyText.sized(p, s: body_scale)}#{render_segments_scaled(line_segs, body_scale)}#{ANSI[:reset]}"
+          row += body_scale
         end
       end
       row
@@ -428,81 +2310,177 @@ module Przn
       all_rows.each_with_index do |cells, ri|
         next unless cells
 
-        @terminal.move_to(row, left)
+        term_move(row, left)
         line = cells.each_with_index.map { |cell, ci|
           pad_to_width(cell, col_widths[ci] || 0)
         }.join('  |  ')
         if ri == 0
-          @terminal.write "#{ANSI[:bold]}#{KittyText.sized(line, s: DEFAULT_SCALE)}#{ANSI[:reset]}"
+          @terminal.write "#{ANSI[:bold]}#{KittyText.sized(line, s: body_scale)}#{ANSI[:reset]}"
         else
-          @terminal.write KittyText.sized(line, s: DEFAULT_SCALE)
+          @terminal.write KittyText.sized(line, s: body_scale)
         end
-        row += DEFAULT_SCALE
+        row += body_scale
 
         if ri == 0
-          @terminal.move_to(row, left)
-          @terminal.write KittyText.sized(col_widths.map { |w| '-' * w }.join('--+--'), s: DEFAULT_SCALE)
-          row += DEFAULT_SCALE
+          term_move(row, left)
+          @terminal.write KittyText.sized(col_widths.map { |w| '-' * w }.join('--+--'), s: body_scale)
+          row += body_scale
         end
       end
       row
     end
 
+    # Layout/flow dispatch for :image blocks. Fully-positioned images
+    # (both x and y set) were already rendered in the slide's pre-pass
+    # — skip them here so we don't re-emit the placement (which would
+    # re-erase the cells that subsequent text writes have since
+    # restored).
+    def render_image_or_skip(block, width, row)
+      attrs = effective_attrs(block)
+      return row if attrs['x'] && attrs['y']
+      render_image(block, width, row)
+    end
+
     def render_image(block, width, row)
       path = resolve_image_path(block[:path])
-      return row + DEFAULT_SCALE unless File.exist?(path)
+      return row + body_scale unless File.exist?(path)
 
       img_size = ImageUtil.image_size(path)
-      return row + DEFAULT_SCALE unless img_size
+      return row + body_scale unless img_size
 
       img_w, img_h = img_size
       cell_w, cell_h = @terminal.cell_pixel_size
 
-      attrs = block[:attrs] || {}
-      abs_x = resolve_at_coord(attrs['x'], @terminal.width)
-      abs_y = resolve_at_coord(attrs['y'], @terminal.height)
-      absolute = abs_x && abs_y
-
-      origin_row = absolute ? abs_y : row
-      available_rows = [@terminal.height - origin_row - 2, 1].max
-      if absolute
-        available_cols = [@terminal.width - abs_x + 1, 1].max
-      else
-        left = content_left(width)
-        available_cols = width - left * 2
-      end
-
-      # Cap the default vertical area to 70 % of the screen, matching what
-      # `{:relative_height="70"}` would do explicitly. Large images that
-      # extend to within a couple of rows of the screen edge render
-      # unreliably in some terminals — they're known-good at 70 %, and
-      # smaller images sit well within this cap so they're unaffected.
-      # An explicit `relative_height` still overrides.
-      default_rh = DEFAULT_IMAGE_RELATIVE_HEIGHT_PERCENT
-      rh = attrs['relative_height'] || default_rh
-      target_rows = (@terminal.height * rh.to_i / 100.0).to_i
-      available_rows = [target_rows, available_rows].min
-
-      # Calculate target cell size maintaining aspect ratio
+      attrs = effective_attrs(block)
+      # Detect `x="center"` / `"right"` (and y twins) up front. The
+      # cell value can't be computed yet — it depends on the image's
+      # rendered cell footprint, which isn't known until target_cols
+      # / target_rows are resolved below. We just remember the
+      # keyword and circle back. Anything that isn't a keyword falls
+      # through to resolve_at_coord's numeric / `%` / `px` / `c` path
+      # — sub-cell px offsets included.
+      x_keyword = alignment_keyword(attrs['x'], :x)
+      y_keyword = alignment_keyword(attrs['y'], :y)
+      # `<img>` x/y resolve with sub-cell pixel precision: each axis
+      # comes back as `[anchor_cell, px_offset_within_anchor]`. The
+      # anchor cell handles where to move the cursor for layering /
+      # fallback paths; the px offset feeds Kitty Graphics' `X=`/`Y=`
+      # so a "100px from the left" request lands at 100 px, not at
+      # the nearest cell edge.
+      abs_x_pair = resolve_at_coord(attrs['x'], @terminal.width, cell_px: cell_w, default_unit: :px, with_offset: true) unless x_keyword
+      abs_y_pair = resolve_at_coord(attrs['y'], @terminal.height, cell_px: cell_h, default_unit: :px, with_offset: true) unless y_keyword
+      abs_x, abs_x_off = abs_x_pair if abs_x_pair
+      abs_y, abs_y_off = abs_y_pair if abs_y_pair
+      # `x` or `y` (either / both) pins the image at that absolute cell;
+      # the unspecified axis falls back to the flow default (centered
+      # in `width` for x, the current `row` for y). Any explicit
+      # positioning makes the image contribute 0 to the layout flow
+      # — same as `<at>` — so a single-axis pin doesn't push the next
+      # block past where the image landed.
+      positioned = !abs_x.nil? || !abs_y.nil? || !x_keyword.nil? || !y_keyword.nil?
+
+      # Compute the image's intrinsic size in cells. Default is to draw
+      # at intrinsic size — no auto-fit shrinking. If the image is
+      # larger than the available pane, the terminal clips the overflow
+      # (same as a tall string of text scrolling off the bottom).
+      #
+      # `relative_height="N"` / `relative_width="N"` (set directly, or
+      # via the `height="N%"` / `width="N%"` aliases) are explicit
+      # author caps: they shrink the image proportionally so that no
+      # axis exceeds N % of the terminal. They never grow it.
       img_cell_w = img_w.to_f / cell_w
       img_cell_h = img_h.to_f / cell_h
-      scale = [available_cols / img_cell_w, available_rows / img_cell_h, 1.0].min
-      target_cols = (img_cell_w * scale).to_i
-      target_rows = (img_cell_h * scale).to_i
-      target_cols = [target_cols, 1].max
-      target_rows = [target_rows, 1].max
-
-      if absolute
-        y_cell, x_cell = abs_y, abs_x
-      else
-        y_cell = row
-        x_cell = [(width - target_cols) / 2, 0].max + 1
+      scale = 1.0
+
+      # Pixel sizing — `height="200"` / `width="300"` (plain integer,
+      # optional `px` suffix) force-resizes the image to that pixel
+      # target. Unlike `relative_*` caps, a pixel value can scale the
+      # image UP as well as down — they're an exact "render at this
+      # size" request, not a cap. Setting both shrinks to fit inside
+      # the smaller of the two ratios (aspect ratio preserved).
+      px_scale = nil
+      if (h_px = parse_px_size(attrs['height']))
+        px_scale = h_px / img_h.to_f
+      end
+      if (w_px = parse_px_size(attrs['width']))
+        w_scale = w_px / img_w.to_f
+        px_scale = px_scale ? [px_scale, w_scale].min : w_scale
+      end
+      scale = px_scale if px_scale
+
+      # `relative_height="N"` / `relative_width="N"` (set directly, or
+      # via the `height="N%"` / `width="N%"` aliases) are explicit
+      # author caps: they shrink the image proportionally so that no
+      # axis exceeds N % of the terminal. They never grow it, and they
+      # win over a px sizing request when smaller.
+      if (rh = attrs['relative_height']) && rh.to_i.positive?
+        max_cell_h = @terminal.height * rh.to_i / 100.0
+        scale = [scale, max_cell_h / img_cell_h].min
+      end
+      if (rw = attrs['relative_width']) && rw.to_i.positive?
+        max_cell_w = @terminal.width * rw.to_i / 100.0
+        scale = [scale, max_cell_w / img_cell_w].min
+      end
+      target_cols = [(img_cell_w * scale).to_i, 1].max
+      target_rows = [(img_cell_h * scale).to_i, 1].max
+
+      # Now that the rendered cell footprint is known, resolve any
+      # alignment keywords. `right` / `bottom` anchor flush to the
+      # pane edge; `center` / `middle` centre against target_cols /
+      # target_rows; `left` / `top` snap to col 1 / row 1. Sub-cell
+      # px offsets are zeroed because keywords are cell-grid choices.
+      if x_keyword
+        abs_x = alignment_keyword_cell(x_keyword, @terminal.width, target_cols, :x)
+        abs_x_off = 0
+      end
+      if y_keyword
+        abs_y = alignment_keyword_cell(y_keyword, @terminal.height, target_rows, :y)
+        abs_y_off = 0
       end
 
-      if ImageUtil.kitty_terminal? && ImageUtil.png?(path)
+      # Per-axis position: explicit `x` / `y` win; absent axes pick
+      # up the flow default. `x_cell` folds the active slot offset
+      # into the centered flow position so both move_to and
+      # kitty_icat land in the right column when rendering inside a
+      # layout slot. The absolute coords already name the screen
+      # cell directly.
+      y_cell = abs_y || row
+      x_cell = abs_x || ([(width - target_cols) / 2, 0].max + 1 + @x_offset)
+      # Sub-cell pixel offsets only flow through when that axis was
+      # explicitly positioned in pixel-form. Flow / centered / cell-
+      # form values land on cell boundaries and pass 0.
+      x_off = abs_x_off || 0
+      y_off = abs_y_off || 0
+
+      # Direct kitty-graphics upload for PNGs always; for non-PNG
+      # raster formats only on Echoes — its NSBitmapImageRep-based
+      # decoder treats `f=100` permissively (PNG / JPEG / TIFF / GIF /
+      # BMP all decode through the same code path), so we can ship a
+      # JPG via the same transmit + place pair the PNG path uses and
+      # avoid the `kitten icat` subprocess. Stock kitty rejects non-
+      # PNG bytes at `f=100` (EBADDATA), so we keep the icat fallback
+      # for it. icat doesn't cope with placements that exceed the
+      # visible cells, so the PNG path is also where intrinsic-size
+      # oversize images work cleanly.
+      if ImageUtil.kitty_terminal? && (ImageUtil.png?(path) || KittyText.echoes?)
         image_id = ensure_kitty_uploaded(path)
         @terminal.move_to(y_cell, x_cell)
-        @terminal.write ImageUtil.kitty_place(image_id: image_id, cols: target_cols, rows: target_rows)
+        # z layering: explicit `z="..."` attr wins. With no z attr, an
+        # image rendered in slide flow stays on top of cells (default
+        # Kitty z=0 behavior) — that's what authors want for the
+        # common single-image-per-slide case. A pinned image (both x
+        # and y given) is more likely to be sitting under other slide
+        # content, so it defaults to z=-1 (behind text) — same trick
+        # `<bg image="..."/>` uses. Authors can override with z="0"
+        # / z="1" / etc. when they want the image on top of text.
+        z = if attrs['z']
+              attrs['z'].to_i
+            elsif abs_x && abs_y
+              -1
+            else
+              nil
+            end
+        @terminal.write ImageUtil.kitty_place(image_id: image_id, cols: target_cols, rows: target_rows, z: z, x_off: x_off, y_off: y_off)
       elsif ImageUtil.kitty_terminal?
         data = cached_kitty_icat(path, cols: target_cols, rows: target_rows, x: x_cell - 1, y: y_cell - 1)
         @terminal.write data if data && !data.empty?
@@ -514,7 +2492,18 @@ module Przn
         @terminal.write sixel if sixel && !sixel.empty?
       end
 
-      absolute ? row : row + target_rows
+      positioned ? row : row + target_rows
+    end
+
+    # Parse an `<img>` height / width attribute as a pixel target.
+    # Accepts `"200"` and `"200px"` (CSS-style suffix, forgiving). A
+    # bare integer with no unit is interpreted as pixels. `nil` /
+    # empty / a percent value / anything non-numeric returns nil so
+    # the caller falls back to relative or intrinsic sizing.
+    def parse_px_size(raw)
+      return nil unless raw.is_a?(String)
+      m = raw.match(/\A(\d+)(?:px)?\z/)
+      m ? m[1].to_i : nil
     end
 
     def resolve_image_path(path)
@@ -555,6 +2544,20 @@ module Przn
       @kitty_uploads[key] = image_id
     end
 
+    # Upload any inline image bytes (currently used by shape SVGs) once
+    # via Kitty graphics direct-data transmission. Keyed by SHA1 so
+    # identical shapes on multiple slides dedup. Shares the
+    # @kitty_uploads cache (and id counter) with PNG / file uploads.
+    def ensure_kitty_inline_uploaded(bytes)
+      require 'digest'
+      key = [:inline, Digest::SHA1.hexdigest(bytes.to_s)]
+      return @kitty_uploads[key] if @kitty_uploads.key?(key)
+
+      image_id = @kitty_uploads.size + 1
+      @terminal.write ImageUtil.kitty_upload_inline(bytes, image_id: image_id)
+      @kitty_uploads[key] = image_id
+    end
+
     def content_left(width)
       width / 16
     end
@@ -571,6 +2574,49 @@ module Przn
       end
     end
 
+    # Can this line use the server-side centering shortcut? Four
+    # conditions must hold:
+    #   - The line is centered (align == :center). The shortcut is a
+    #     centering tool; left- and right-aligned lines keep the
+    #     existing pad-based path.
+    #   - A proportional `face` is set. Monospace lines center fine
+    #     under the cell-grid estimate; the shortcut only matters
+    #     when the font's actual rendered width disagrees with cell
+    #     count, which is the proportional case.
+    #   - We're running in Echoes. The shortcut relies on Echoes'
+    #     widened OSC 7772 `w=` parameter and its pixel-precise
+    #     halign engine. Strict-kitty terminals cap w at 7 (insufficient
+    #     for a slot-spanning block) and don't measure proportional
+    #     glyphs anyway, so the fallback path is the right answer there.
+    #   - The line is a single :text segment. Multi-segment lines
+    #     (a `<color=red>...` halfway through, say) need per-segment
+    #     SGR/face changes that one multicell can't express; they
+    #     keep the per-segment path and accept the cell-grid drift.
+    #
+    # `width / scale >= 1` is also required so the OSC 7772 `w=`
+    # field has a positive integer to take.
+    def server_centered_eligible?(line_segs, face, align, width, scale)
+      align == :center &&
+        face && !face.to_s.empty? &&
+        KittyText.echoes? &&
+        line_segs.size == 1 && line_segs.first[0] == :text &&
+        scale && scale > 0 && (width.to_f / scale).floor >= 1
+    end
+
+    # Compute the slot-relative cursor column + the multicell body
+    # bytes for a server-side-centered line. The block is
+    # `floor(width/scale) * scale` cells wide so it fits inside the
+    # slot; any leftover slot space splits evenly via `lead_cells`
+    # so the BLOCK is slot-centered. Halign=2 then centers the text
+    # pixel-precisely inside the block.
+    def server_centered_emit(text, scale, face, width)
+      block_w_units = (width.to_f / scale).floor
+      block_w = block_w_units * scale
+      lead_cells = (width - block_w) / 2
+      body = KittyText.sized(text, s: scale, w: block_w_units, h: 2, f: face)
+      [lead_cells + 1, body]
+    end
+
     def render_inline(text)
       Parser.parse_inline(text).map { |segment|
         type = segment[0]
@@ -604,25 +2650,69 @@ module Przn
     # the row, which looks wrong against the larger body text.
     def render_bullet(prefix)
       size = @theme.bullet[:size]
-      if size && size < DEFAULT_SCALE
-        KittyText.sized(prefix, s: DEFAULT_SCALE, n: size, d: DEFAULT_SCALE, v: 2)
-      else
-        KittyText.sized(prefix, s: size || DEFAULT_SCALE)
-      end
+      sized =
+        if size && size < body_scale
+          KittyText.sized(prefix, s: body_scale, n: size, d: body_scale, v: 2)
+        else
+          KittyText.sized(prefix, s: size || body_scale)
+        end
+      color = @theme.bullet[:color]
+      return sized unless color && !color.to_s.empty?
+      "#{color_code(color.to_s)}#{sized}#{ANSI[:reset]}"
     end
 
     # Render a <font face="..." size="..." color="..."> run. The face goes out
     # via OSC 66 f= (Echoes extension); the size resolves through the same
     # SIZE_SCALES table that <size=N> uses; the color wraps in the same ANSI
-    # escape that <color=NAME> uses.
-    def render_font_segment(content, attrs, para_scale, default_face: nil, default_h: nil)
+    # escape that <color=NAME> uses. `line_height:` lets a small font ride
+    # at the bottom of a taller line (see `sized_in_line`).
+    def render_font_segment(content, attrs, para_scale, line_height: nil, mixed_line: false, default_face: nil, default_h: nil)
       scale = (attrs[:size] && Parser::SIZE_SCALES[attrs[:size]]) || para_scale
-      base = KittyText.sized(content, s: scale, f: attrs[:face] || default_face, h: default_h)
+      base = sized_in_line(content, seg_scale: scale, line_height: line_height, mixed_line: mixed_line, f: attrs[:face] || default_face, h: default_h)
       color = attrs[:color]
       return base unless color
       "#{color_code(color)}#{base}#{ANSI[:reset]}"
     end
 
+    # Wrap `content` in OSC 66 so segments on a mixed-size line share a
+    # typographic baseline (not just a block-bottom edge). All segments
+    # emit `s=line_height` so their multicell blocks have the same top
+    # and bottom; then `v=3` (Echoes-private baseline-align mode) tells
+    # the renderer to position each one so its baseline lands at the
+    # same y within the block, regardless of font/scale.
+    #
+    #   - Shorter than line_height → s=line_height,n=seg,d=line_height,v=3.
+    #     Block matches the tallest sibling; glyph drawn at seg/line_height
+    #     ratio; baseline shared with the tall siblings.
+    #
+    #   - Equal to line_height but on a mixed line → s=seg_scale,v=3.
+    #     Same block size as the shorter siblings (since they all emit
+    #     s=line_height too). v=3 keeps everyone on the same baseline.
+    #
+    #   - Anything when line_height is nil OR no mixed-size line at all →
+    #     plain `s=seg_scale`. Byte-identical to the pre-line-height path
+    #     so single-scale paragraphs / lists / etc. don't drift.
+    #
+    # `mixed_line:` tells the helper whether *some other* segment on this
+    # line is shorter than line_height — the caller computes it once per
+    # line because the helper itself only sees one segment at a time.
+    #
+    # Echoes' v= mapping (echoes/lib/echoes/gui.rb:1269):
+    #   v=0 (default) → top
+    #   v=1           → text-bottom at block-bottom
+    #   v=2           → text-centered in block
+    #   v=3           → baseline at `block_bottom - cell_h + default_ascender`
+    #                   (Echoes-private; falls back to top on strict kitty)
+    def sized_in_line(content, seg_scale:, line_height:, mixed_line: false, f: nil, h: nil)
+      if line_height && line_height > seg_scale
+        KittyText.sized(content, s: line_height, n: seg_scale, d: line_height, v: 3, f: f, h: h)
+      elsif mixed_line
+        KittyText.sized(content, s: seg_scale, v: 3, f: f, h: h)
+      else
+        KittyText.sized(content, s: seg_scale, f: f, h: h)
+      end
+    end
+
     # `default_face:` / `default_color:` let a caller (currently h1 rendering)
     # override the OSC 66 `f=` and the ANSI fg for every emit on the line.
     # When unset, body text falls back to `theme.font.family` / `theme.font.color`.
@@ -636,11 +2726,20 @@ module Przn
     # centered within the reserved cell block — without it the glyphs left-
     # align inside the block and the visible text drifts left of the center
     # column we computed.
-    def render_segments_scaled(segments, para_scale, default_face: :body, default_h: nil, default_color: :body)
-      f = default_face == :body ? @theme.font[:family] : default_face
+    def render_segments_scaled(segments, para_scale, line_height: nil, default_face: :body, default_h: nil, default_color: :body)
+      f = default_face == :body ? (slot_family || @theme.font[:family]) : default_face
       h = default_h
-      c = default_color == :body ? @theme.font[:color] : default_color
+      c = default_color == :body ? (slot_color || @theme.font[:color]) : default_color
       body_open = c ? color_code(c) : ''
+      # "Mixed line" = line_height is set AND at least one segment is
+      # shorter than line_height. When true, the tall segment(s) also
+      # get v=1 so they share the baseline with the shorter siblings
+      # (otherwise tall floats to the top and short to the bottom).
+      mixed = line_height &&
+        segments.any? { |s| s[0] != :break && effective_seg_scale(s, para_scale) < line_height }
+      # When `line_height` isn't passed, callers want the pre-mixed-size
+      # behavior — sized_in_line collapses to plain `s=seg_scale`, so
+      # existing wire-shape tests keep their byte-for-byte output.
       inner = segments.map { |segment|
         type = segment[0]
         content = segment[1]
@@ -648,19 +2747,23 @@ module Przn
         when :tag
           tag_name = segment[2]
           if (scale = Parser::SIZE_SCALES[tag_name])
-            KittyText.sized(content, s: scale, f: f, h: h)
-          elsif Parser::NAMED_COLORS.key?(tag_name)
-            "#{color_code(tag_name)}#{KittyText.sized(content, s: para_scale, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
+            sized_in_line(content, seg_scale: scale, line_height: line_height, mixed_line: mixed, f: f, h: h)
+          elsif !(code = color_code(tag_name)).empty?
+            # `<color=NAME>`, `<color=ff5555>`, `<color=#ff5555>`, the
+            # kramdown `{::tag name="red"}` form — anything color_code
+            # can resolve gets wrapped in that SGR. Same engine
+            # `<font color="...">` uses, so the two stay in sync.
+            "#{code}#{sized_in_line(content, seg_scale: para_scale, line_height: line_height, mixed_line: mixed, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
           else
-            KittyText.sized(content, s: para_scale, f: f, h: h)
+            sized_in_line(content, seg_scale: para_scale, line_height: line_height, mixed_line: mixed, f: f, h: h)
           end
-        when :font          then "#{render_font_segment(content, segment[2] || {}, para_scale, default_face: f, default_h: h)}#{(segment[2] || {})[:color] ? body_open : ''}"
-        when :note          then @mode == :audience ? "" : "#{ANSI[:dim]}#{KittyText.sized(content, s: para_scale, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
-        when :bold          then "#{ANSI[:bold]}#{KittyText.sized(content, s: para_scale, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
-        when :italic        then "#{ANSI[:italic]}#{KittyText.sized(content, s: para_scale, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
-        when :strikethrough then "#{ANSI[:strikethrough]}#{KittyText.sized(content, s: para_scale, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
-        when :code          then "#{ANSI[:gray_bg]}#{KittyText.sized(" #{content} ", s: para_scale, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
-        when :text          then KittyText.sized(content, s: para_scale, f: f, h: h)
+        when :font          then "#{render_font_segment(content, segment[2] || {}, para_scale, line_height: line_height, mixed_line: mixed, default_face: f, default_h: h)}#{(segment[2] || {})[:color] ? body_open : ''}"
+        when :note          then @mode == :audience ? "" : "#{ANSI[:dim]}#{sized_in_line(content, seg_scale: para_scale, line_height: line_height, mixed_line: mixed, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
+        when :bold          then "#{ANSI[:bold]}#{sized_in_line(content, seg_scale: para_scale, line_height: line_height, mixed_line: mixed, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
+        when :italic        then "#{ANSI[:italic]}#{sized_in_line(content, seg_scale: para_scale, line_height: line_height, mixed_line: mixed, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
+        when :strikethrough then "#{ANSI[:strikethrough]}#{sized_in_line(content, seg_scale: para_scale, line_height: line_height, mixed_line: mixed, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
+        when :code          then "#{ANSI[:gray_bg]}#{sized_in_line(" #{content} ", seg_scale: para_scale, line_height: line_height, mixed_line: mixed, f: f, h: h)}#{ANSI[:reset]}#{body_open}"
+        when :text          then sized_in_line(content, seg_scale: para_scale, line_height: line_height, mixed_line: mixed, f: f, h: h)
         end
       }.join
       body_open.empty? ? inner : "#{body_open}#{inner}#{ANSI[:reset]}"
@@ -673,7 +2776,20 @@ module Przn
     # Wrap parsed inline segments into lines that fit within max_width units,
     # where 1 unit = `para_scale` terminal cells. Per-segment scaling (e.g.
     # size tags) is honored so a span with a larger scale consumes more budget.
-    def wrap_segments(segments, max_width, para_scale = DEFAULT_SCALE)
+    def wrap_segments(segments, max_width, para_scale = body_scale)
+      # Force-break support: split at `:break` segments (from <br>),
+      # wrap each chunk independently against `max_width`, then
+      # concatenate the resulting lines. An empty chunk (two `<br>`s
+      # in a row, or a leading / trailing `<br>`) yields one blank
+      # line, matching HTML semantics.
+      if segments.any? { |s| s[0] == :break }
+        groups = [[]]
+        segments.each do |seg|
+          seg[0] == :break ? (groups << []) : (groups.last << seg)
+        end
+        return groups.flat_map { |g| wrap_segments(g, max_width, para_scale) }
+      end
+
       return [segments] if max_width <= 0
 
       max_cells = max_width * para_scale
@@ -775,44 +2891,66 @@ module Przn
       text + ' ' * [target_width - current, 0].max
     end
 
+    # Largest OSC 66 scale used inside the paragraph's inline markup,
+    # used by callers to decide how many rows to advance the layout
+    # row by per text line. Recognizes all three size-bearing
+    # spellings: the kramdown `{::tag name="..."}`, the XML
+    # `<size=N>`, and `<font size="..."/>` — each emits OSC 66 text
+    # that occupies `N` cells tall, so a list item or paragraph
+    # carrying any of them needs the row to advance by N rather
+    # than the body scale.
     def max_inline_scale(text)
       max = 0
-      text.scan(/\{::tag\s+name="([^"]+)"\}/) do
-        scale = Parser::SIZE_SCALES[$1]
-        max = scale if scale && scale > max
+      [
+        /\{::tag\s+name="([^"]+)"\}/,
+        /<size=(?:"([^"]*)"|'([^']*)'|([^>\s]+))>/,
+        /<font\b[^>]*\bsize=["']?([^"'\s>]+)/
+      ].each do |re|
+        text.scan(re) do |groups|
+          value = Array(groups).compact.first
+          scale = Parser::SIZE_SCALES[value]
+          max = scale if scale && scale > max
+        end
       end
       max > 0 ? max : nil
     end
 
     def visible_width_scaled(text, default_scale)
       Parser.parse_inline(text).sum { |segment|
-        type = segment[0]
-        content = segment[1]
-        case type
-        when :tag
-          scale = Parser::SIZE_SCALES[segment[2]] || default_scale
-          display_width(content) * scale
-        else
-          display_width(content) * default_scale
-        end
+        content = segment[1] || ''
+        display_width(content) * effective_seg_scale(segment, default_scale)
       }
     end
 
+    # Resolve a CSS-ish color value into an opening ANSI SGR escape.
+    # Accepts: a named ANSI color (`red`, `bright_cyan`, …), a 6-digit
+    # hex code (`ff5555`, with or without a leading `#`). Returns `''`
+    # for an unrecognized value so callers can no-op safely.
+    #
+    # Named colors prefer the CSS table over the ANSI palette so that
+    # `<color=red>` (font) and `<rect stroke="red"/>` (shape) render
+    # the same `#ff0000` on screen — they used to drift because shape
+    # paint went through `normalize_svg_color` (CSS hex) while text
+    # went through Parser::NAMED_COLORS (terminal-theme ANSI). The
+    # 147-name CSS table covers every basic colour name plus dozens
+    # of CSS-only names like tomato / lavender that previously
+    # rendered as no-op on fonts. `bright_*` and any other name not
+    # in CSS still falls through to the ANSI palette.
     def color_code(color)
-      if (code = Parser::NAMED_COLORS[color])
+      c = color.to_s.sub(/\A#/, '')
+      if (hex = CSS_NAMED_COLORS[c.downcase])
+        r, g, b = hex.scan(/../).map { |h| h.to_i(16) }
+        "\e[38;2;#{r};#{g};#{b}m"
+      elsif (code = Parser::NAMED_COLORS[c])
         "\e[#{code}m"
-      elsif color.match?(/\A[0-9a-fA-F]{6}\z/)
-        r, g, b = color.scan(/../).map { |h| h.to_i(16) }
+      elsif c.match?(/\A[0-9a-fA-F]{6}\z/)
+        r, g, b = c.scan(/../).map { |h| h.to_i(16) }
         "\e[38;2;#{r};#{g};#{b}m"
       else
         ''
       end
     end
 
-    def visible_length(text)
-      display_width(strip_markup(text))
-    end
-
     def display_width(str)
       str.each_char.sum { |c|
         o = c.ord
@@ -838,104 +2976,5 @@ module Przn
       }
     end
 
-    def strip_markup(text)
-      text
-        .gsub(/\{::tag\s+name="[^"]+"\}(.*?)\{:\/tag\}/, '\1')
-        .gsub(/\{::note\}(.*?)\{:\/note\}/, '\1')
-        .gsub('{::wait/}', '')
-        .gsub(/\*\*(.+?)\*\*/, '\1')
-        .gsub(/\*(.+?)\*/, '\1')
-        .gsub(/~~(.+?)~~/, '\1')
-        .gsub(/`([^`]+)`/, '\1')
-        .gsub(/&(lt|gt|amp);/) { |_| {'lt' => '<', 'gt' => '>', 'amp' => '&'}[$1] }
-    end
-
-    def calculate_height(blocks, width)
-      blocks.sum { |b| block_height(b, width) }
-    end
-
-    def block_height(block, width)
-      s = DEFAULT_SCALE
-      left = content_left(width)
-      max_w = max_text_width(width, left, s)
-
-      case block[:type]
-      when :heading
-        scale = KittyText::HEADING_SCALES[block[:level]] || s
-        if block[:level] == 1
-          scale + 4
-        else
-          lines_count(block[:content], [max_w - 2, 1].max) * scale
-        end
-      when :paragraph
-        para_scale = max_inline_scale(block[:content]) || s
-        lines_count(block[:content], [max_text_width(width, left, para_scale), 1].max) * para_scale
-      when :code_block
-        [block[:content].lines.size * s, s].max
-      when :unordered_list
-        block[:items].sum { |item|
-          prefix_w = (item[:depth] || 0) * 2 + 2
-          lines_count(item[:text], [max_w - prefix_w, 1].max) * s
-        }
-      when :ordered_list
-        block[:items].size * s
-      when :definition_list
-        term_lines = lines_count(block[:term], [max_w, 1].max)
-        def_lines = block[:definition].lines.sum { |l| lines_count(l.chomp, [max_w - 4, 1].max) }
-        (term_lines + def_lines) * s
-      when :blockquote
-        block[:content].lines.sum { |l| lines_count(l.chomp, [max_w - 3, 1].max) } * s
-      when :table
-        ((block[:header] ? 2 : 0) + block[:rows].size) * s
-      when :image
-        # Absolute-positioned images (`<img x y src/>`) layer on top of
-        # the slide and contribute 0 to the layout — same treatment as :at.
-        attrs = block[:attrs] || {}
-        if resolve_at_coord(attrs['x'], @terminal.width) && resolve_at_coord(attrs['y'], @terminal.height)
-          0
-        else
-          image_block_height(block, width)
-        end
-      when :align
-        0
-      when :bg
-        0
-      when :at
-        0
-      when :blank
-        s
-      else
-        s
-      end
-    end
-
-    def lines_count(text, max_width)
-      vis_w = display_width(strip_markup(text))
-      return 1 if vis_w <= max_width
-      (vis_w.to_f / max_width).ceil
-    end
-
-    def image_block_height(block, width)
-      path = resolve_image_path(block[:path])
-      img_size = ImageUtil.image_size(path)
-      return DEFAULT_SCALE unless img_size
-
-      img_w, img_h = img_size
-      cell_w, cell_h = @terminal.cell_pixel_size
-      h = @terminal.height
-
-      left = content_left(width)
-      available_cols = width - left * 2
-      available_rows = h / 2
-
-      if (rh = block[:attrs]['relative_height'])
-        available_rows = (h * rh.to_i / 100.0).to_i
-      end
-
-      img_cell_w = img_w.to_f / cell_w
-      img_cell_h = img_h.to_f / cell_h
-      scale = [available_cols / img_cell_w, available_rows / img_cell_h, 1.0].min
-      [(img_cell_h * scale).ceil, 1].max
-    end
   end
 end