przn 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a02ff63ef48dadc49d46767f2f60e32457cd9562dffa726e6a6b3a811c3cf68d
-  data.tar.gz: 0a4c431ac13a990c06397626749de0b495e47efa3af5c3233800868b7fb56b41
+  metadata.gz: 926f4301117fde5642b907fbf96340d1e547af78086eb1fd47ed45fa16472e5e
+  data.tar.gz: 8cbbf68f1d784b6c6ed2ce7ba600c0a214dc8a688a785b5044701b9e8c587b39
 SHA512:
-  metadata.gz: 98e45b37b5125ece026f9140dbd68225beddde0eb1eac76ad0e614b28610898580acc5a9e03a3cd36313740165216cec646e1224f80f2e951a4c82d3dde89d9d
-  data.tar.gz: eef32162b80aedbef88fafbc3834e85e12eda8db63918a762183f341f45ee694397aa39407c5887f7fb004ccbd0276cf59beded6a695a8441bcefceb3f8416ff
+  metadata.gz: 6f6a58582c7a21ccfab9750ee0ebc39525626af2233d503497e933a1d5b108bcf08b34c156115730c145e3c4dd7473b8d48633597d68b487bcc5702e29132183
+  data.tar.gz: 0a3bf226c4c4e6300d515cf50274c1ad266556c9a984df6090ed9dec1dbcc7cc3e878675131e2d26f0e71b1167046f1d5ea3e7f1b0f965101f942e5a728d9967

data/README.md

@@ -75,6 +75,8 @@ przn --export prawn -o output.pdf your_slides.md
 
 przn's Markdown format is compatible with [Rabbit](https://rabbit-shocker.org/)'s Markdown mode.
 
+> **HTML-ish tag attributes** — every `<tag attr=value>` block below (`<bg>`, `<at>`, `<img>`, `<font>`) accepts three value forms: double-quoted `attr="value"`, single-quoted `attr='value'`, and unquoted `attr=value` (HTML5-ish — anything that isn't whitespace, `=`, `<`, `>`, a quote, or backtick). Self-closing tags need a space before `/>` when the last attribute is unquoted (`<img src=foo.png />`).
+
 ### Slide splitting
 
 Slides are separated by `#` (h1) headings.
@@ -235,6 +237,49 @@ content...
 
 The previous slide's background is cleared on every navigation, and on `przn` exit, so your shell isn't left tinted.
 
+### Absolute-position text
+
+Place text at an arbitrary `(column, row)` on the slide, escaping the normal top-down paragraph flow:
+
+```markdown
+# Layout test
+
+<at x="10" y="5">top-left ish</at>
+<at x="40" y="15"><size=3>BIG</size></at>
+<at x="80" y="25"><color=red>warn</color></at>
+<at x="50%" y="50%">dead center</at>
+
+{::at x="10" y="20"}same thing, kramdown form{:/at}
+```
+
+- `x` / `y` accept two forms:
+  - **Plain integer** — 1-based terminal cells, matching the cursor-position escape (`\e[y;xH`). `x="1" y="1"` is the very top-left of the slide pane.
+  - **Percent** (`x="50%"`, `y="100%"`) — resolves against the terminal's current width / height. Auto-adjusts when the pane is resized.
+- Content is parsed inline, so all the usual styling works inside an `<at>` — `<size>`, `<color>`, `<font>`, `**bold**`, `*italic*`, etc.
+- The block doesn't take up vertical space in the slide's layout — paragraphs around it render in their normal positions and the absolute placement layers on top. Useful for overlaying labels on a `<bg .../>` gradient or pinning annotations to specific cells.
+- Out-of-range coordinates clamp into the visible area; missing / unparseable coordinates skip silently.
+
+### Image
+
+Embed an image with the standard markdown form, or the `<img>` XML form when you want to absolute-position it. Both produce identical output — `<img>` just opens the door to extra attributes like `x` / `y`.
+
+```markdown
+![](doge.png){:relative_height="70"}
+<img src="doge.png" relative_height="70"/>
+
+<img src="doge.png" x="5"   y="3"   relative_height="40"/>
+<img src="doge.png" x="50%" y="50%" relative_height="40"/>
+```
+
+- `src` is required; `alt` and `title` are accepted and ignored at render time (kept for accessibility / future use).
+- `relative_height="N"` caps the image at N % of the terminal height (default 70). Aspect ratio is preserved. `relative_width="N"` is the same for the horizontal dimension.
+- `height="N%"` / `width="N%"` are short-form aliases for `relative_height` / `relative_width` (both forms — `<img>` and `![]{:...}` — accept the alias). An explicit `relative_*` on the same block wins; a non-`%` value (`height="40"`) is left alone since pixel units aren't supported.
+- `x` / `y` (optional) anchor the image's top-left at an absolute cell. Same two forms as [`<at>`](#absolute-position-text):
+  - **Plain integer** — 1-based terminal cells.
+  - **Percent** — resolves against the terminal's current width / height.
+  - With `x` and `y` set, the image layers on top of the slide and contributes 0 to the layout flow — paragraphs around it render in their normal positions, exactly like `<at>`. Without `x` / `y`, the image stays horizontally centered and takes up its natural height in the flow.
+- Rendering backend: Kitty Graphics Protocol on terminals that support it (PNG uploaded once and reused; JPG goes through `kitten icat`), Sixel as a fallback. Other terminals show nothing in place of the image.
+
 ### Comments
 
 ```markdown

data/lib/przn/controller.rb

@@ -44,6 +44,7 @@ module Przn
         @audience_link.close
       end
       @terminal.write "\e]7772;bg-clear\a"
+      @terminal.write ImageUtil.kitty_clear_all if ImageUtil.kitty_terminal?
       @terminal.show_cursor
       @terminal.leave_alt_screen
     end

data/lib/przn/image_util.rb

@@ -91,6 +91,16 @@ module Przn
       "\e_Ga=p,i=#{image_id},c=#{cols},r=#{rows},q=2\e\\"
     end
 
+    # Kitty Graphics Protocol: delete every placement and free the
+    # stored image data. Used on quit so previously-rendered images
+    # don't leak through onto the user's restored shell screen
+    # (placements aren't tied to the alt-screen buffer in most
+    # kitty-protocol implementations, so leaving the alt screen
+    # alone isn't enough to hide them). `q=2` suppresses the OK reply.
+    def kitty_clear_all
+      "\e_Ga=d,d=A,q=2\e\\"
+    end
+
     # Sixel via img2sixel
     def sixel_available?
       @sixel_available = system('command -v img2sixel > /dev/null 2>&1') if @sixel_available.nil?

data/lib/przn/parser.rb

@@ -25,6 +25,15 @@ module Przn
       'bright_white' => 97
     }.freeze
 
+    # HTML-ish attribute, three accepted value forms:
+    #   key="value"   key='value'   key=bareword
+    # The unquoted token excludes whitespace, `=`, `<`, `>`, `"`, `'` and
+    # backtick, matching the spirit of HTML5's unquoted-attribute grammar.
+    # `/` is intentionally NOT excluded so paths like `src=path/to/file`
+    # work — which means self-closing tags need a space before `/>` when
+    # the last attribute is unquoted (`<img src=foo.png />`).
+    ATTR_RE_SRC = '\w+=(?:"[^"]*"|\'[^\']*\'|[^\s=<>"\'`]+)'
+
     module_function
 
     def parse(markdown)
@@ -79,9 +88,20 @@ module Przn
         # Slide background (Echoes OSC 7772):
         #   <bg color="#..."/>                              — solid (bg-color)
         #   <bg from="#..." to="#..." angle="N"/>           — linear gradient (bg-gradient)
-        when /\A\s*<bg((?:\s+\w+="[^"]+")*)\s*\/>\s*\z/
+        # Attribute values may be double-quoted, single-quoted, or
+        # unquoted (HTML5-ish — see ATTR_RE_SRC).
+        when %r{\A\s*<bg((?:\s+#{ATTR_RE_SRC})*)\s*/>\s*\z}o
           blocks << {type: :bg, attrs: parse_xml_attrs(Regexp.last_match(1))}
 
+        # Absolute-position text:
+        #   <at x="N" y="N">content</at>
+        #   {::at x="N" y="N"}content{:/at}
+        # Content can include inline markup (size, color, font, bold, …).
+        when %r{\A\s*<at((?:\s+#{ATTR_RE_SRC})+)\s*>(.*)</at>\s*\z}o
+          blocks << {type: :at, attrs: parse_xml_attrs(Regexp.last_match(1)), content: Regexp.last_match(2)}
+        when %r{\A\s*\{::at((?:\s+#{ATTR_RE_SRC})+)\}(.*)\{:/at\}\s*\z}o
+          blocks << {type: :at, attrs: parse_xml_attrs(Regexp.last_match(1)), content: Regexp.last_match(2)}
+
         # Fenced code block
         when /\A\s*```(\w*)\s*\z/
           lang = Regexp.last_match(1)
@@ -176,6 +196,23 @@ module Przn
           i -= 1
           blocks << {type: :ordered_list, items: items}
 
+        # Image, XML form: <img src="path" alt="..." title="..." {:attrs}/>
+        # Equivalent to the markdown `![alt](src "title"){:attrs}` form below
+        # — emits the same `:image` block so the renderer handles both
+        # identically. `src` is required; all other attributes pass through
+        # to `block[:attrs]` (string-keyed, matching markdown's IAL parse) so
+        # `relative_height`, `width`, etc. work the same way.
+        when %r{\A\s*<img((?:\s+#{ATTR_RE_SRC})+)\s*/>\s*\z}o
+          raw = parse_xml_attrs(Regexp.last_match(1))
+          path = raw.delete(:src)
+          if path
+            alt = raw.delete(:alt).to_s
+            title = raw.delete(:title)
+            attrs = raw.transform_keys(&:to_s)
+            normalize_image_attrs!(attrs)
+            blocks << {type: :image, path: path, alt: alt, title: title, attrs: attrs}
+          end
+
         # Image: ![alt](path "title"){:attrs}
         when /\A!\[([^\]]*)\]\((\S+?)(?:\s+"([^"]*)")?\)(.*)/
           alt = Regexp.last_match(1)
@@ -194,6 +231,7 @@ module Przn
             attr_str = attr_str.sub(/\}\s*\z/, '')
             parse_image_attrs(attr_str, attrs)
           end
+          normalize_image_attrs!(attrs)
           blocks << {type: :image, path: path, alt: alt, title: title, attrs: attrs}
 
         # Definition list: term on one line, :   definition on next
@@ -237,12 +275,14 @@ module Przn
       attrs.slice(:face, :size, :color)
     end
 
-    # Generic attribute scanner — `key="value"` pairs, returned as a hash with
-    # symbolized keys. Doesn't validate which keys are allowed; callers slice.
+    # Generic attribute scanner — three value forms accepted:
+    #   key="value"   key='value'   key=bareword
+    # Returns a hash with symbolized keys. Doesn't validate which keys
+    # are allowed; callers slice.
     def parse_xml_attrs(str)
       attrs = {}
-      str.scan(/(\w+)="([^"]+)"/) do |key, value|
-        attrs[key.to_sym] = value
+      str.scan(/(\w+)=(?:"([^"]*)"|'([^']*)'|([^\s=<>"'`]+))/) do |key, dq, sq, uq|
+        attrs[key.to_sym] = dq || sq || uq
       end
       attrs
     end
@@ -254,6 +294,22 @@ module Przn
       end
     end
 
+    # Rewrite `height="N%"` / `width="N%"` into the canonical
+    # `relative_height="N"` / `relative_width="N"` the renderer reads.
+    # Values without a `%` suffix pass through unchanged (and are
+    # ignored downstream); an explicit `relative_*` already on the
+    # block wins so authors can mix forms without surprise.
+    def normalize_image_attrs!(attrs)
+      if (h = attrs['height']) && (m = h.match(/\A(\d+)%\z/))
+        attrs.delete('height')
+        attrs['relative_height'] ||= m[1]
+      end
+      if (w = attrs['width']) && (m = w.match(/\A(\d+)%\z/))
+        attrs.delete('width')
+        attrs['relative_width'] ||= m[1]
+      end
+    end
+
     def parse_table(lines)
       rows = []
       lines.each do |line|
@@ -275,9 +331,9 @@ module Przn
           segments << [:tag, scanner[2], scanner[1]]
         elsif scanner.scan(/<size=([^>\s]+)>(.*?)<\/size>/)
           segments << [:tag, scanner[2], scanner[1]]
-        elsif scanner.scan(/<font((?:\s+\w+="[^"]+")+)\s*>(.*?)<\/font>/)
+        elsif scanner.scan(%r{<font((?:\s+#{ATTR_RE_SRC})+)\s*>(.*?)</font>}o)
           segments << [:font, scanner[2], parse_font_attrs(scanner[1])]
-        elsif scanner.scan(/\{::font((?:\s+\w+="[^"]+")+)\}(.*?)\{:\/font\}/)
+        elsif scanner.scan(%r{\{::font((?:\s+#{ATTR_RE_SRC})+)\}(.*?)\{:/font\}}o)
           segments << [:font, scanner[2], parse_font_attrs(scanner[1])]
         elsif scanner.scan(/\{::note\}(.*?)\{:\/note\}/)
           segments << [:note, scanner[1]]
@@ -304,7 +360,21 @@ module Przn
         end
       end
 
-      segments
+      # Coalesce adjacent :text segments. The scanner has to bail to a
+      # single-character `.` when it sees `&` so the `&lt;` / `&gt;` /
+      # `&amp;` entity matches can run on the next iteration, which
+      # leaves a bare `&` as its own segment and fragments the
+      # surrounding text. Merging them back together means one OSC 66
+      # multicell sequence per typeset run — important for h1 titles
+      # under a proportional font, where Echoes pads each run
+      # independently and stray segments become visible gaps.
+      segments.each_with_object([]) do |seg, acc|
+        if seg[0] == :text && acc.last && acc.last[0] == :text
+          acc.last[1] = acc.last[1] + seg[1]
+        else
+          acc << seg
+        end
+      end
     end
   end
 end

data/lib/przn/renderer.rb

@@ -109,6 +109,7 @@ module Przn
       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
       end
     end
@@ -137,6 +138,48 @@ module Przn
       @terminal.write "\e]7772;bg-gradient;type=#{type}:angle=#{angle}:colors=#{colors.join(',')}\a"
     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
+    # value as a percentage of the terminal's width (for `x=`) or height
+    # (for `y=`) — `x="50%" y="50%"` lands at the middle of the pane,
+    # auto-resizing with the terminal. Content is parsed inline so
+    # `<size>`, `<color>`, `<font>`, **bold**, etc. all work inside `<at>`.
+    # 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?
+
+      segments = Parser.parse_inline(block[:content].to_s)
+      @terminal.move_to(y, x)
+      @terminal.write render_segments_scaled(segments, DEFAULT_SCALE)
+    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?
+
+      s = raw.to_s.strip
+      return nil if s.empty?
+
+      cells =
+        if s.end_with?('%')
+          pct = s.chomp('%').to_f
+          (pct / 100.0 * max).round
+        elsif s =~ /\A-?\d+\z/
+          s.to_i
+        end
+      return nil if cells.nil?
+
+      cells.clamp(1, max)
+    end
+
     # Bottom-row progress indicator (Rabbit-style):
     #
     #   1                   🐢                🐇                   9
@@ -415,9 +458,19 @@ module Przn
       img_w, img_h = img_size
       cell_w, cell_h = @terminal.cell_pixel_size
 
-      available_rows = @terminal.height - row - 2
-      left = content_left(width)
-      available_cols = width - left * 2
+      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
@@ -426,7 +479,7 @@ module Przn
       # 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 = block[:attrs]['relative_height'] || default_rh
+      rh = attrs['relative_height'] || default_rh
       target_rows = (@terminal.height * rh.to_i / 100.0).to_i
       available_rows = [target_rows, available_rows].min
 
@@ -439,24 +492,29 @@ module Przn
       target_cols = [target_cols, 1].max
       target_rows = [target_rows, 1].max
 
-      x = [(width - target_cols) / 2, 0].max
+      if absolute
+        y_cell, x_cell = abs_y, abs_x
+      else
+        y_cell = row
+        x_cell = [(width - target_cols) / 2, 0].max + 1
+      end
 
       if ImageUtil.kitty_terminal? && ImageUtil.png?(path)
         image_id = ensure_kitty_uploaded(path)
-        @terminal.move_to(row, x + 1)
+        @terminal.move_to(y_cell, x_cell)
         @terminal.write ImageUtil.kitty_place(image_id: image_id, cols: target_cols, rows: target_rows)
       elsif ImageUtil.kitty_terminal?
-        data = cached_kitty_icat(path, cols: target_cols, rows: target_rows, x: x, y: row - 1)
+        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?
       elsif ImageUtil.sixel_available?
-        @terminal.move_to(row, x + 1)
+        @terminal.move_to(y_cell, x_cell)
         target_pixel_w = target_cols * cell_w
         target_pixel_h = target_rows * cell_h
         sixel = cached_sixel_encode(path, width: target_pixel_w, height: target_pixel_h)
         @terminal.write sixel if sixel && !sixel.empty?
       end
 
-      row + target_rows
+      absolute ? row : row + target_rows
     end
 
     def resolve_image_path(path)
@@ -830,11 +888,20 @@ module Przn
       when :table
         ((block[:header] ? 2 : 0) + block[:rows].size) * s
       when :image
-        image_block_height(block, width)
+        # 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

data/lib/przn/screenshot_pdf_exporter.rb

@@ -76,6 +76,7 @@ module Przn
       paths
     ensure
       @terminal.write "#{OSC};bg-clear#{BEL}"
+      @terminal.write ImageUtil.kitty_clear_all if ImageUtil.kitty_terminal?
       @terminal.show_cursor
       @terminal.leave_alt_screen
       @terminal.flush

data/lib/przn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Przn
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/przn.rb

@@ -59,6 +59,7 @@ module Przn
       end
     ensure
       terminal.write "\e]7772;bg-clear\a"
+      terminal.write ImageUtil.kitty_clear_all if ImageUtil.kitty_terminal?
       terminal.show_cursor
       terminal.leave_alt_screen
     end

data/sample/sample.md

@@ -48,6 +48,22 @@ normal and {::tag name="red"}red text{:/tag} mixed
 
 ![](doge.jpg){:relative_height="70"}
 
+# Image (XML form)
+
+<img src="doge.png" relative_height="70"/>
+
+# Image (absolute position)
+
+<img src="doge.png" x="5"   y="3"   relative_height="40"/>
+<img src="doge.png" x="50%" y="50%" relative_height="40"/>
+
+# Absolute-position text
+
+<at x="10" y="10">top-left ish</at>
+<at x="40" y="15"><size=3>BIG</size></at>
+<at x="80" y="25"><color=red>warn</color></at>
+<at x="50%" y="50%">dead center</at>
+
 # Thank You!
 
 That's all! Enjoy!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: przn
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
   - Akira Matsuda