hadar 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7b4c769b40f5836617885858a50bc58e93ef8072b97430520ec2315ed81edbb
-  data.tar.gz: e8379cf1cc2f8039429d0fba6a650d8d7f059801e30c0df69864bf5ed94be8b0
+  metadata.gz: ca92c68fe912ebaddf03792345b9747c02f994a1134f47c4481313f8312d0fe2
+  data.tar.gz: 5e1e1e5dd08e6516af6a540dd86c262a6da4ba175e532301a4e3c7fd5d9ebc7a
 SHA512:
-  metadata.gz: b44313439e6fcc8a411c8b7fbc379a2050c843b8758dfa42352c4f007f5334141b45ced44d8d139a14dc030332d826744feaab621678e7e671760710f2ee1edd
-  data.tar.gz: 46f5d21160a6b804ba95067906abcc9f0277bf263a5aa51281ebe93ae0c1712982d8ebf0f328a3ca0dc2670a3f0a7573d67509b75f1787f6f477a64de1714d61
+  metadata.gz: aa6fe7bc92f62e5d4780e6e2b6236a82949f6bab93858243d734a4953146028028ff8b45345829c774b0d35277f9bb459b005178133768559ab473c22d6ddcab
+  data.tar.gz: 62d2be12ec8b34ab18bcc71866edd8a4ce8e40d0fc67f3cb5d853dab520a5e4f8fd28cda7e8ea4648946f471f9b410aec0c1e07d85cb6dff9ac6cc8c368fded8

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.0 - 2026-09-24
+
+- Use the preview's Zaniah element tree for searchable vector PDF export, including freeform slides.
+
+## 0.3.0 - 2026-09-24
+
+- Add opt-in freeform slide placement with explicit Markdown directives and an editor warning.
+
 ## 0.2.0 - 2026-09-24
 
 - Add APNG export for slide decks.

data/README.md

@@ -1,38 +1,58 @@
-# Hadar
-
-Hadar (β Centauri) is a Markdown-backed presentation app. Its deck model is a
-projection of Beid's source-positioned AST: slide content and slots keep their
-source nodes instead of becoming a second mutable copy. Markdown `---`
-thematic breaks separate slides, and `<!-- layout: ... -->` selects one of
-eight template layouts.
-
-Hadar provides deck/slide/slot parsing, three JSONC themes, layout selection, a
-declarative preview tree, and virtualized thumbnail rows built with Zaniah's
-existing `Describe` and `UniformList` APIs. Its selected-slide editor can switch
-among every declared layout slot. Text slots use Zaniah `RichText` and Beid;
-image slots provide insert/replace actions, while tables and fenced code expose
-source-preserving cell/body editors. Unsupported syntax remains visible but
-read-only. Beid-backed
-`<!-- notes: ... -->` comments provide speaker notes on each slide and are
-excluded from the visible preview. Image slots can insert and replace
-source-backed Markdown references; absolute asset paths are stored relative to
-the opened deck. Local image slots render through Zaniah's image decoder (PNG,
-GIF, and baseline JPEG); relative references resolve from the deck's directory.
-Missing, unreadable, and unsupported images fail preview construction with a
-`Hadar::Error`. Remote URLs are not fetched. Hadar does not copy image files;
-saving continues to write only the Markdown source. Its window host polls for
-external Markdown edits and can show a next-slide, notes, and elapsed-time
-presenter view. The host supports slide navigation, fullscreen, a fuzzy command
-palette, PNG-sequence, and APNG export. When a secondary display is available,
-the owned presenter window opens there fullscreen.
+<h1 align="center">Hadar</h1>
+
+<p align="center">
+  <strong>Markdown-backed slide decks with source-preserving editing, live preview, and presentation export</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/hadar"><img src="https://img.shields.io/gem/v/hadar.svg" alt="Gem version"></a>
+  <a href="https://rubygems.org/gems/hadar"><img src="https://img.shields.io/gem/dt/hadar.svg" alt="Gem downloads"></a>
+  <a href="https://github.com/noxdea/hadar/actions/workflows/main.yml"><img src="https://github.com/noxdea/hadar/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/CRuby-%3E%3D%203.2-cc342d.svg" alt="CRuby 3.2 or newer">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#editing-and-presenting">Editing and presenting</a> ·
+  <a href="#export">Export</a>
+</p>
+
+---
+
+Hadar is a Ruby presentation library built around ordinary Markdown files.
+[Beid](https://github.com/noxdea/beid) keeps the source-positioned document as
+the only editable copy; Hadar projects it into slides, slots, and a live
+[Zaniah](https://github.com/noxdea/zaniah) preview. Use its API to embed a
+presentation window in an app or export a deck without a GUI.
+
+## Features
+
+- Eight automatic or explicitly selected slide templates, plus opt-in freeform placement
+- Source-backed text, image, table-cell, and fenced-code editing with speaker notes
+- Three built-in JSONC themes (`minimal`, `dark`, `warm`) and custom themes
+- Virtualized slide thumbnails, keyboard navigation, command palette, and a secondary-display presenter view
+- Searchable PDF, PNG-sequence, and animated PNG (APNG) export
 
 ## Installation
 
-```ruby
-gem "hadar"
+Hadar requires CRuby 3.2 or newer. Install the gem or add `gem "hadar"` to
+your Gemfile:
+
+```sh
+gem install hadar
 ```
 
-## Usage
+Hadar is a library; it does not install a `hadar` command. Windowed use
+requires a Zaniah-supported display backend. PNG and APNG export use Zaniah's
+headless renderer.
+
+## Quick start
+
+Separate slides with Markdown thematic breaks. Hadar selects a layout from
+each slide's content unless you add a `layout` comment:
 
 ```ruby
 require "hadar"
@@ -59,21 +79,16 @@ deck = Hadar::Deck.parse(<<~MARKDOWN)
   :::
 MARKDOWN
 
-deck.slide(1).layout         # => :two_column
-deck.slide(1).slot(:left).text
-deck.slide(0).notes           # => nil when no speaker notes are present
-
+deck.slide(1).layout          # => :two_column
+deck.slide(1).slot(:left).text # => "Revenue rose 18% year over year."
 tree = Hadar::Renderer.new.describe(deck.slide(0))
-element = Hadar::Renderer.new.build(deck.slide(0))
-
-thumbnails = Hadar::SlideList.new(deck, selected: 0,
-  on_select: ->(slide, index) { puts "Selected slide #{index + 1}: #{slide.title}" })
-list_element = thumbnails.build(width: 280, height: 640)
 ```
 
-Built-in themes are `minimal`, `dark`, and `warm`. Custom JSONC themes can be
-loaded with `Hadar::Theme.load(path)` and passed to `Deck.parse` or
-`Deck.open`.
+`Renderer#build` returns a Zaniah element for embedding in a preview.
+
+## Editing and presenting
+
+### Source-backed slots
 
 Slots remain projections of the current Beid document. `slot.rich_text` returns
 a Zaniah rich-text editor whose bold, italic, link, and code spans come from the
@@ -89,6 +104,7 @@ paragraph styles are rejected rather than flattening or normalizing markup.
 Rich-text projection covers headings, paragraphs, block quotes, and text lists;
 tables, fenced code blocks, and Markdown strikethrough are not editable through
 this API yet.
+
 Slots returned before a successful edit are stale snapshots. Opened decks save
 atomically, preserve file permissions, and refuse to overwrite external changes:
 
@@ -101,22 +117,22 @@ deck.save
 ```
 
 Opened decks can detect and reload external changes directly or through the
-Zaniah platform watcher. A watcher is polled by the host's UI loop; successful
-reloads update the same deck object and invoke `on_reload`. Reload refuses to
-discard local unsaved Markdown edits, leaving both the in-memory and on-disk
-versions untouched. The host can keep its current slide selection and rebuild
-the preview after the callback:
+Zaniah platform watcher. Reload refuses to discard unsaved local edits. A
+watcher is polled by the host's UI loop; successful reloads update the same
+deck object and invoke `on_reload`:
 
 ```ruby
 watcher = deck.watch(on_reload: ->(_deck) { window.request_frame })
 watcher.poll(timeout: 0)
 ```
 
-`deck.reload_if_changed` performs the same safe check without a platform watcher.
-`Hadar::Application` wires this polling into attached windows and retains the
-selected slide by index when a reload changes the deck. Its presenter view shows
-the next slide, current slide's notes, and elapsed time. While presenting, each
-window tick requests a fresh frame so elapsed time stays current:
+`deck.reload_if_changed` performs the same safe check without a watcher.
+
+### Application and controls
+
+`Hadar::Application` wires the watcher into attached windows and keeps the
+selected slide index on reload. Its presenter view shows the next slide,
+current notes, and elapsed time:
 
 ```ruby
 app = Hadar::Application.new(deck)
@@ -125,47 +141,17 @@ app.attach(main_window: main)
 app.run
 ```
 
-`Application#run` polls the deck and ticks all attached windows in one loop.
-When at least two displays are available, Hadar creates its own presenter
-window and places it fullscreen on a secondary display (Wayland compositors may
-choose whether to honor the output request). With one display, it does not
-create a presenter automatically. A presenter window passed by the host is
-used as-is and is never moved or closed by Hadar. The automatically created
-presenter closes when the main window closes. Rich-text slot editors are backed
-by the current Markdown source and recreated after an external reload.
-They keep the caret or selection (and editor focus) when selected text maps
-unambiguously around one contiguous external edit; if an edit overlaps the
-selection or makes the mapping ambiguous, the selection and focus are cleared
-rather than moved to unrelated text. Arrow, Page Up/Down, Home, and End navigate
-slides; `P` or `F5` starts presentation,
-`F11` toggles fullscreen, and `Escape` exits presentation or fullscreen.
-`Ctrl/Cmd-K` opens the fuzzy command palette; `Ctrl/Cmd-S` saves an opened deck
-through its conflict-aware atomic writer.
-
-PDF export produces one searchable 16:9 page for every slide, including all
-eight layouts. Pass a TrueType font that contains every visible character; the
-default font is selected from Zaniah's local font database:
-
-```ruby
-Hadar::Export::PDF.write(deck, "slides.pdf", font: "/path/to/font.ttf")
-```
-
-Okab currently requires TrueType outlines for PDF embedding. Hadar exports local
-PNG and JPEG images; remote images and other image formats are rejected.
-
-PNG sequence export renders all slides at the requested dimensions using
-Zaniah's headless renderer. It refuses to overwrite existing frames:
+`Application#run` polls and ticks its windows. With a second display, Hadar
+opens its own fullscreen presenter window there; an explicitly passed
+`presenter_window:` stays under the host's control. After an external reload,
+rich-text editors are recreated. Their selection and focus survive only when
+they map unambiguously around the edit.
 
-```ruby
-app.export_png_sequence("slides-png", width: 1280, height: 720)
-```
+Arrow keys, Page Up/Down, Home, and End navigate slides. `P` or `F5` starts
+presentation; `F11` toggles fullscreen; `Escape` exits either mode.
+`Ctrl/Cmd-K` opens the command palette, and `Ctrl/Cmd-S` saves an opened deck.
 
-Animated PNG export holds each slide for three seconds by default, loops forever,
-and refuses to replace an existing target unless `overwrite: true` is passed:
-
-```ruby
-app.export_apng("slides.apng", width: 1280, height: 720, duration_ms: 2500)
-```
+### Notes and block editors
 
 Speaker notes can be written as a one-line or multiline HTML comment. Their
 Markdown remains in the source unchanged and does not appear in slide slots or
@@ -206,7 +192,7 @@ For a deck created with `Deck.parse`, pass a new path to `app.save(path)`.
 Replacing an existing unrelated path requires `overwrite: true`. Opened decks
 can use `app.save` or `Ctrl/Cmd-S`; the same external-change check applies.
 
-## Layouts
+### Layouts and themes
 
 `title`, `title+body`, `two-column`, `image+text`, `full-bleed-image`,
 `quote`, `code`, and `blank` are available. Explicit layout directives take
@@ -222,20 +208,76 @@ the referenced assets are not copied. If an absolute selected asset lives
 outside the deck directory, its saved relative reference points outside that
 directory rather than copying the file.
 
+Built-in themes are `minimal`, `dark`, and `warm`. Custom JSONC themes can be
+loaded with `Hadar::Theme.load(path)` and passed to `Deck.parse` or
+`Deck.open`. A deck can also set a built-in theme in YAML front matter with
+`theme: dark`.
+
+Freeform placement is an explicit per-slide opt-in. Add `<!-- layout: freeform -->`
+and one `<!-- place: x,y,width,height -->` immediately before each Markdown
+block. Coordinates are percentages of the slide's inner canvas (after theme
+margins); every rectangle must fit inside 0–100%. An image-only paragraph is
+placed as an image. For example:
+
+```markdown
+<!-- layout: freeform -->
+
+<!-- place: 5,8,90,20 -->
+# Quarterly report
+
+<!-- place: 10,35,80,50 -->
+Revenue increased **18%**.
+```
+
+The content stays readable in a plain Markdown viewer, but its placement does
+not. Hadar marks freeform slides in the editor with a compatibility warning.
+Missing, malformed, or overflowing positions are errors; Hadar never silently
+drops a block. Edit the directives in the Markdown source to reposition items.
+After an external edit reloads a freeform slide, select its block again before
+editing; source-order item numbers may have changed.
+
 `SlideList` creates thumbnail rows only for the visible viewport, using
-`Zaniah::UniformList`; `build(width:, height:)` returns the Zaniah element for
-embedding in an application layout. Its `select(index)` method updates the
-selection and invokes the optional `on_select` callback. Wezen is not involved
-in live thumbnails; it encodes rendered slide frames as APNG.
+`Zaniah::UniformList`. `build(width:, height:)` returns a Zaniah element;
+`select(index)` updates the selection and invokes `on_select` when supplied:
+
+```ruby
+thumbnails = Hadar::SlideList.new(deck, selected: 0,
+  on_select: ->(slide, index) { puts "Selected slide #{index + 1}: #{slide.title}" })
+element = thumbnails.build(width: 280, height: 640)
+```
+
+## Export
+
+```ruby
+Hadar::Export::PDF.write(deck, "slides.pdf", font: "/path/to/font.ttf")
+Hadar::Export::PNGSequence.write(deck, "slides-png", width: 1280, height: 720)
+Hadar::Export::APNG.write(deck, "slides.apng", width: 1280, height: 720,
+  duration_ms: 2500)
+```
+
+PDF creates one searchable 16:9 page per slide from the same element tree used
+by PNG export, including freeform placement.
+It needs a TrueType-outline font containing every visible character; without
+`font:`, Hadar uses Zaniah's local font database. PDF embeds local PNG and JPEG
+images, but rejects remote and other image formats. PNG-sequence export refuses
+to replace existing frames. APNG defaults to three seconds per slide and
+infinite looping; an existing target requires `overwrite: true`.
+`Application#export_png_sequence` and
+`#export_apng` wrap the corresponding exporters.
 
 ## Development
 
-Run the specs with `bundle exec rake`. Check the 100-slide virtual-list
-layout/scene-build budget with `BUDGET=1 bundle exec ruby bench/slide_list.rb`;
-the headless benchmark skips software pixel rasterization. Hadar depends on
-Beid, Antares, Kochab, Okab, Spica, Wezen, Xamidimura, and Zaniah; its
-declarative `Describe`, `UniformList`, and input keymap APIs are reused directly.
+```sh
+bundle install
+bundle exec rake
+```
+
+Check the 100-slide thumbnail layout/scene-build budget with
+`BUDGET=1 bundle exec ruby bench/slide_list.rb`. See the
+[template-layout](docs/adr/001-template-layouts.md) and
+[freeform-placement](docs/adr/002-opt-in-freeform-layout.md) decisions for the
+source model.
 
 ## License
 
-MIT. See [LICENSE.txt](LICENSE.txt).
+Hadar is released under the [MIT License](LICENSE.txt).

data/docs/adr/001-template-layouts.md

@@ -20,3 +20,5 @@ one from the parsed Markdown structure. A free-form canvas is out of scope.
 Template content can remain a projection of the source AST and can be edited
 without duplicating slide state. Users do not get arbitrary element placement;
 reconsider only for a later format that can represent positions explicitly.
+
+The later opt-in format is specified in [ADR 002](002-opt-in-freeform-layout.md).

data/docs/adr/002-opt-in-freeform-layout.md

@@ -0,0 +1,23 @@
+# ADR 002: Opt-in freeform placement in Markdown
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+ADR 001 kept the initial release template-only. Later freeform slides still
+need a source-backed position format and a visible compatibility warning.
+
+## Decision
+
+`<!-- layout: freeform -->` opts in one slide. Each Markdown block has a
+preceding `<!-- place: x,y,width,height -->` comment, measured as percentages
+of the inner slide canvas. Positions must be finite, positive-sized rectangles
+entirely within the canvas. Missing or malformed positions are rejected rather
+than ignored. Hadar's editor warns that a plain Markdown viewer loses layout.
+
+## Consequences
+
+Content remains ordinary Markdown and edits still pass through Beid. Plain
+viewers display the content in source order without the Hadar layout. Positions
+are edited in Markdown; drag-and-drop or independent canvas state is not added.

data/lib/hadar/application.rb

@@ -100,6 +100,9 @@ module Hadar
         editor_pane = Zaniah::Div.new.w(editor_width).h_full.p(12).gap(8)
           .style(flex_direction: :column, border: 1, border_color: deck.theme.colors.fetch("muted"))
         editor_pane.child(Zaniah::UI::Label.new(slot_title, size: :sm))
+        if selected_index && deck.slide(selected_index).layout == :freeform
+          editor_pane.child(Zaniah::UI::Label.new("Freeform — このスライドは素の Markdown ビューアでは崩れます", tone: :muted))
+        end
         editor_pane.child(slot_selector) if selected_index && deck.slide(selected_index).slots.any?
         editor_pane.child(editor.w_full.flex_1) if editor
         editor_pane.child(Zaniah::UI::Label.new("Editing unavailable: #{error}", tone: :muted)) if error
@@ -166,7 +169,7 @@ module Hadar
 
     def insert_or_replace_selected_image(path)
       slot = selected_slot || raise(Error, "there is no selected slot")
-      raise Error, "select the image slot first" unless slot.name == :image
+      raise Error, "select the image slot first" unless image_slot?(slot)
 
       updated = slot.empty? ? slot.insert_image(path) : slot.replace_image(path)
       finish_slot_edit
@@ -427,12 +430,13 @@ module Hadar
     def slot_editor_for_selected_slide
       return [nil, nil] unless selected_index
       unless selected_slot_name
-        @body_editor_error ||= "this slide has no editable slots"
+        @body_editor_error ||= deck.slide(selected_index).layout == :freeform ?
+          "select a block to edit after reloading this freeform slide" : "this slide has no editable slots"
         return [nil, @body_editor_error]
       end
 
       slot = selected_slot
-      if slot.name == :image
+      if image_slot?(slot)
         pending_body_editor_focus(:clear) if @pending_body_editor_reload && @pending_body_editor_reload[:slot] == slot.name
         [image_slot_editor(slot), @body_editor_error]
       elsif slot.nodes.any? { |node| %i[table code_block].include?(node.type) }
@@ -480,7 +484,7 @@ module Hadar
     end
 
     def image_slot_editor(slot)
-      return Zaniah::UI::Label.new("Select an image slot to insert or replace an image.") unless slot.name == :image
+      return Zaniah::UI::Label.new("Select an image slot to insert or replace an image.") unless image_slot?(slot)
       if !slot.empty? && !(slot.nodes.one? && slot.nodes.first.type == :image)
         return Zaniah::UI::Label.new("This image slot contains multiple images and cannot be edited safely.", tone: :muted)
       end
@@ -606,6 +610,10 @@ module Hadar
       slide.slots.key?(:body) ? :body : slide.slots.keys.first
     end
 
+    def image_slot?(slot)
+      slot.name == :image || (slot.nodes.one? && slot.nodes.first.type == :image)
+    end
+
     def key_context(window)
       (window.dispatcher.focused&.ancestors || []).reverse.each_with_object({}) do |handle, context|
         context.merge!(handle.context)
@@ -681,8 +689,13 @@ module Hadar
         [[selected_index || 0, 0].max, deck.length - 1].min
       end
       @pending_body_editor_reload = nil if @selected_index != previous_index
-      @selected_slot_name = @selected_index && deck.slide(@selected_index).slots.key?(previous_slot) ? previous_slot :
-        (@selected_index && default_slot_name(deck.slide(@selected_index)))
+      @selected_slot_name = if @selected_index && deck.slide(@selected_index).layout == :freeform
+        nil # Positional item IDs may now refer to different blocks; require explicit reselection.
+      elsif @selected_index && deck.slide(@selected_index).slots.key?(previous_slot)
+        previous_slot
+      else
+        @selected_index && default_slot_name(deck.slide(@selected_index))
+      end
       reset_slot_editor_state_after_reload
       presenter.reconcile!
       rebuild_slide_list

data/lib/hadar/export/pdf.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "okab/zaniah_vector"
+require "zaniah/vector"
+
 module Hadar
   module Export
     class PDF
@@ -23,10 +26,12 @@ module Hadar
 
       def render
         document = Okab::Document.new(title: @deck.slides.first&.title, creator: "Hadar")
+        renderer = Renderer.new(font: @font.face)
         @deck.slides.each do |slide|
+          ensure_glyphs!(renderer.describe(slide))
+          vector = Zaniah::Vector.record(width: WIDTH, height: HEIGHT) { renderer.build(slide) }
           page = document.page(width: WIDTH, height: HEIGHT)
-          paint_background(page, slide.theme)
-          paint_slide(page, slide)
+          Okab::ZaniahVector.draw(page, vector)
           document.outline(slide.title, page: page) unless slide.title.empty?
         end
         document.render
@@ -52,94 +57,16 @@ module Hadar
         raise Error, "cannot load PDF font: #{error.message}"
       end
 
-      def paint_background(page, theme)
-        page.rect(0, 0, WIDTH, HEIGHT).fill(rgb(theme.colors.fetch("background")))
-      end
-
-      def paint_slide(page, slide)
-        margin = slide.theme.spacing.fetch("margin")
-        gap = slide.theme.spacing.fetch("gap")
-        title_size = slide.theme.font.fetch("title_size")
-        body_size = slide.theme.font.fetch("body_size")
-        text_color = rgb(slide.theme.colors.fetch("text"))
-        muted = rgb(slide.theme.colors.fetch("muted"))
-        width = WIDTH - margin * 2
+      def ensure_glyphs!(node)
+        if %i[text code_token].include?(node.type)
+          missing = node.props.fetch(:text).codepoints.find do |codepoint|
+            next false if codepoint == 0x0a || variation_selector?(codepoint)
 
-        case slide.layout
-        when :title
-          text(page, slide.slot(:title).text, margin, HEIGHT * 0.57, width, title_size, text_color, :center)
-          text(page, slide.slot(:subtitle).text, margin, HEIGHT * 0.40, width, body_size, muted, :center)
-        when :two_column
-          paint_title(page, slide, margin, width, title_size, text_color)
-          column_width = (width - gap) / 2
-          y = HEIGHT - margin - title_size - gap - body_size
-          text(page, slide.slot(:left).text, margin, y, column_width, body_size, text_color)
-          text(page, slide.slot(:right).text, margin + column_width + gap, y, column_width, body_size, text_color)
-        when :image_text
-          paint_title(page, slide, margin, width, title_size, text_color)
-          y = HEIGHT - margin - title_size - gap - body_size
-          text(page, slide.slot(:text).text, margin, y, width * 0.48, body_size, text_color)
-          paint_image(page, slide.slot(:image), margin + width * 0.52, margin,
-            width * 0.48, HEIGHT - margin * 2 - title_size - gap)
-        when :full_bleed_image
-          paint_image(page, slide.slot(:image), 0, 0, WIDTH, HEIGHT, cover: true)
-        when :quote
-          text(page, slide.slot(:quote).text, margin + width * 0.08, HEIGHT * 0.62,
-            width * 0.84, title_size, text_color, :center)
-          text(page, slide.slot(:attribution).text, margin, HEIGHT * 0.28, width, body_size, muted, :center)
-        when :code
-          paint_title(page, slide, margin, width, title_size, text_color)
-          y = HEIGHT - margin - title_size - gap - body_size
-          text(page, slide.slot(:code).text, margin, y, width, body_size, text_color)
-        when :blank
-          nil
-        else
-          paint_title(page, slide, margin, width, title_size, text_color)
-          y = HEIGHT - margin - title_size - gap - body_size
-          text(page, slide.slot(:body).text, margin, y, width, body_size, text_color)
+            @font.face.glyph_id(codepoint).zero?
+          end
+          raise Error, "PDF font does not contain U+#{missing.to_s(16).upcase}; provide a font that covers the deck text" if missing
         end
-      end
-
-      def paint_title(page, slide, margin, width, size, color)
-        text(page, slide.slot(:title).text, margin, HEIGHT - margin - size, width, size, color)
-      end
-
-      def text(page, value, x, y, width, size, color, align = :left)
-        return if value.nil? || value.empty?
-
-        value = value.gsub(/\r\n?/, "\n")
-        ensure_glyphs!(value)
-        page.text_block(value, x: x, y: y, width: width, font: @font, size: size,
-          line_height: size * 1.3, align: align, color: color)
-      end
-
-      def paint_image(page, slot, x, y, width, height, cover: false)
-        return if slot.empty?
-
-        image = Okab::Image.decode(File.binread(slot.resolved_image_path))
-        scales = [width / image.width, height / image.height]
-        scale = cover ? scales.max : scales.min
-        draw_width, draw_height = image.width * scale, image.height * scale
-        page.clip { |path| path.rect(x, y, width, height) } if cover
-        page.image(image, x: x + (width - draw_width) / 2, y: y + (height - draw_height) / 2,
-          width: draw_width, height: draw_height)
-      rescue Okab::Error, SystemCallError => error
-        raise Error, "cannot export image: #{error.message}"
-      end
-
-      def ensure_glyphs!(value)
-        missing = value.codepoints.find do |codepoint|
-          next false if codepoint == 0x0a || variation_selector?(codepoint)
-
-          @font.face.glyph_id(codepoint).zero?
-        end
-        return unless missing
-
-        raise Error, "PDF font does not contain U+#{missing.to_s(16).upcase}; provide a font that covers the deck text"
-      end
-
-      def rgb(color)
-        color.delete_prefix("#").scan(/../).first(3).map { |component| component.to_i(16) / 255.0 }
+        node.children.each { |child| ensure_glyphs!(child) }
       end
 
       def variation_selector?(codepoint)

data/lib/hadar/layout.rb

@@ -12,7 +12,8 @@ module Hadar
       Definition.new(:full_bleed_image, %i[image]),
       Definition.new(:quote, %i[quote attribution]),
       Definition.new(:code, %i[title code]),
-      Definition.new(:blank, [])
+      Definition.new(:blank, []),
+      Definition.new(:freeform, [])
     ].freeze
     private_constant :Definition
 

data/lib/hadar/renderer.rb

@@ -2,9 +2,10 @@
 
 module Hadar
   class Renderer
-    def initialize
+    def initialize(font: nil)
       @font_db = nil
       @fonts = {}
+      @font_override = font
       @vocabulary = build_vocabulary
     end
 
@@ -41,6 +42,12 @@ module Hadar
         node :stack, props: {gap: :number} do |props, children|
           Zaniah::Element.new.flex_col.style(gap: props.fetch(:gap)).children(children)
         end
+        node :placed, props: {x: :number, y: :number, width: :number, height: :number} do |props, children|
+          Zaniah::Element.new.flex_col.style(position: :absolute,
+            left: Zaniah.percent(props.fetch(:x)), top: Zaniah.percent(props.fetch(:y)),
+            width: Zaniah.percent(props.fetch(:width)), height: Zaniah.percent(props.fetch(:height)))
+            .children(children)
+        end
         node :columns, props: {gap: :number} do |props, children|
           Zaniah::Element.new.flex_row.style(gap: props.fetch(:gap)).children(children)
         end
@@ -86,6 +93,8 @@ module Hadar
     end
 
     def font(family)
+      return @font_override if @font_override
+
       @fonts[family] ||= begin
         @font_db ||= Zaniah::TextSystem::FontDB.new
         @font_db.find(family: family == "sans-serif" ? nil : family)
@@ -96,6 +105,21 @@ module Hadar
       theme = slide_theme(slide)
       gap = theme.spacing.fetch("gap")
       case slide.layout
+      when :freeform
+        slide.placements.map do |name, (x, y, width, height)|
+          slot = slide.slot(name)
+          entry = slot.nodes.first
+          children = if entry.type == :image
+            [image_node(slot)]
+          elsif entry.type == :heading
+            [text_node(slot.text, theme.font.fetch("title_size"), theme),
+              *images_in(entry).map { |image| image_node(slot, image: image) }]
+          else
+            [*render_blocks(slot, theme), *images_in(entry).map { |image| image_node(slot, image: image) }]
+          end
+          node(:placed, {x: x, y: y, width: width, height: height}, children.compact,
+            "slide-#{slide.index}-#{name}")
+        end
       when :title
         stack([
           text_node(slide.slot(:title).text, theme.font.fetch("title_size"), theme),
@@ -226,10 +250,14 @@ module Hadar
       Zaniah::Describe::Node.new(type, props, children, key)
     end
 
-    def image_node(slot)
+    def images_in(entry)
+      [entry, *entry.children.flat_map { |child| images_in(child) }].select { |node| node.type == :image }
+    end
+
+    def image_node(slot, image: nil)
       return if slot.empty?
 
-      path = slot.resolved_image_path
+      path = image ? slot.resolved_image_path_for(image) : slot.resolved_image_path
       node(:image, {path: path}, [], "slide-#{slot.slide_index}-#{slot.name}-image")
     end
 

data/lib/hadar/slide.rb

@@ -2,13 +2,15 @@
 
 module Hadar
   class Slide
-    attr_reader :index, :document, :nodes, :layout, :slots, :theme, :notes
+    attr_reader :index, :document, :nodes, :layout, :slots, :theme, :notes, :placements
 
     def initialize(index:, document:, nodes:, layout: nil, theme:, deck:)
       @index, @document, @nodes, @theme, @deck = index, document, nodes.freeze, theme, deck
       @notes, @notes_ranges = extract_notes
       @layout = Layout.select(content_nodes, requested: layout)
+      @placements = {}
       @slots = build_slots.freeze
+      @placements.freeze
       freeze
     end
 
@@ -18,7 +20,11 @@ module Hadar
       end
     end
 
-    def title = slot(:title).text
+    def title
+      return slot(:title).text unless layout == :freeform
+
+      slots.values.find { |entry| entry.nodes.first&.type == :heading }&.text.to_s
+    end
 
     private
 
@@ -75,6 +81,8 @@ module Hadar
 
     def build_slots
       content = content_nodes
+      return build_freeform_slots(content) if layout == :freeform
+
       definition = Layout.fetch(layout)
       mapping = definition.slots.to_h { |name| [name, []] }
       case layout
@@ -114,6 +122,49 @@ module Hadar
       end
     end
 
+    def build_freeform_slots(content)
+      pending = nil
+      slots = {}
+      content.each do |node|
+        next if node.type == :link_definition
+
+        if placement_directive?(node)
+          raise Error, "freeform placement must be followed by one content block" if pending
+
+          pending = parse_placement(node.attributes.dig(:values, "place"))
+          next
+        end
+        raise Error, "freeform content requires a preceding place directive" unless pending
+
+        name = :"item_#{slots.length + 1}"
+        body = node.type == :paragraph && node.children.one? && node.children.first.type == :image ? node.children.first : node
+        slots[name] = Slot.new(name: name, nodes: [body], document: document,
+          deck: @deck, slide_index: index)
+        @placements[name] = pending.freeze
+        pending = nil
+      end
+      raise Error, "freeform placement must be followed by one content block" if pending
+
+      slots
+    end
+
+    def placement_directive?(node)
+      node.type == :directive && node.attributes[:kind] == :html_comment &&
+        node.attributes[:values]&.key?("place")
+    end
+
+    def parse_placement(value)
+      unless value.to_s.match?(/\A\s*\d+(?:\.\d+)?\s*,\s*\d+(?:\.\d+)?\s*,\s*\d+(?:\.\d+)?\s*,\s*\d+(?:\.\d+)?\s*\z/)
+        raise Error, "place must contain x,y,width,height percentages"
+      end
+      x, y, width, height = value.split(",").map { |part| Float(part) }
+      unless width.positive? && height.positive? && x + width <= 100 && y + height <= 100
+        raise Error, "freeform placement must fit within the slide (0–100%)"
+      end
+
+      [x, y, width, height]
+    end
+
     def layout_directive?(node)
       node.type == :directive && node.attributes[:kind] == :html_comment &&
         node.attributes[:values]&.key?("layout")

data/lib/hadar/slot.rb

@@ -44,8 +44,7 @@ module Hadar
       return if nodes.empty?
       raise Error, "image_path requires a slot containing exactly one image" unless nodes.one? && nodes.first.type == :image
 
-      destination = nodes.first.attributes.fetch(:destination)
-      destination.match?(/\Ahttps?:\/\//i) ? destination : URI::DEFAULT_PARSER.unescape(destination)
+      destination_path(nodes.first)
     end
 
     def resolved_image_path
@@ -53,6 +52,14 @@ module Hadar
       path && @deck.resolve_image_path(path)
     end
 
+    def resolved_image_path_for(node)
+      unless node.is_a?(Beid::Node) && node.type == :image && nodes.any? { |entry| contains_node?(entry, node) }
+        raise Error, "image is not part of this slot"
+      end
+
+      @deck.resolve_image_path(destination_path(node))
+    end
+
     def replace_text(text)
       @deck.replace_text(self, text)
     end
@@ -95,6 +102,15 @@ module Hadar
 
     private
 
+    def contains_node?(entry, target)
+      entry.equal?(target) || entry.children.any? { |child| contains_node?(child, target) }
+    end
+
+    def destination_path(node)
+      destination = node.attributes.fetch(:destination)
+      destination.match?(/\Ahttps?:\/\//i) ? destination : URI::DEFAULT_PARSER.unescape(destination)
+    end
+
     def table_nodes = nodes.select { |node| node.type == :table }
 
     def valid_index!(index, name)

data/lib/hadar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hadar
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/sig/hadar.rbs

@@ -30,6 +30,7 @@ module Hadar
     def text_for: (Beid::Node node) -> String
     def image_path: () -> String?
     def resolved_image_path: () -> String?
+    def resolved_image_path_for: (Beid::Node node) -> String
     def table_rows: (?table: Integer) -> Array[Array[String]]
     def replace_text: (String text) -> Slot
     def rich_text: (?editable: bool) -> Zaniah::UI::RichText
@@ -49,6 +50,7 @@ module Hadar
     attr_reader slots: Hash[Symbol, Slot]
     attr_reader theme: Theme
     attr_reader notes: String?
+    attr_reader placements: Hash[Symbol, Array[Float]]
 
     def initialize: (index: Integer, document: Beid::Document, nodes: Array[Beid::Node],
       ?layout: String | Symbol | nil, theme: Theme, deck: Deck) -> void
@@ -182,7 +184,7 @@ module Hadar
   end
 
   class Renderer
-    def initialize: () -> void
+    def initialize: (?font: Alhena::Font?) -> void
     def describe: (Slide slide) -> Zaniah::Describe::Node
     def build: (Slide slide) -> Zaniah::Element
     def surface: (Slide slide) -> Zaniah::Describe::Surface

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hadar
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: spica
   requirement: !ruby/object:Gem::Requirement
@@ -113,14 +113,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.9.0
 description: Projects Beid Markdown ASTs into template-based slide decks, edits supported
   source-backed text, and exports PDF or PNG.
 email:
@@ -136,6 +136,7 @@ files:
 - assets/themes/minimal.jsonc
 - assets/themes/warm.jsonc
 - docs/adr/001-template-layouts.md
+- docs/adr/002-opt-in-freeform-layout.md
 - lib/hadar.rb
 - lib/hadar/application.rb
 - lib/hadar/command_palette.rb