hadar 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7b4c769b40f5836617885858a50bc58e93ef8072b97430520ec2315ed81edbb
-  data.tar.gz: e8379cf1cc2f8039429d0fba6a650d8d7f059801e30c0df69864bf5ed94be8b0
+  metadata.gz: b0bc8dd031f42ad45785dbcf360c9f075e8d71758be0a5e2df0e158abc77ef8d
+  data.tar.gz: 0702a59cfdcfd8987311f08e178a9390ec31b3442de35b4414fb1b3dc5c301d3
 SHA512:
-  metadata.gz: b44313439e6fcc8a411c8b7fbc379a2050c843b8758dfa42352c4f007f5334141b45ced44d8d139a14dc030332d826744feaab621678e7e671760710f2ee1edd
-  data.tar.gz: 46f5d21160a6b804ba95067906abcc9f0277bf263a5aa51281ebe93ae0c1712982d8ebf0f328a3ca0dc2670a3f0a7573d67509b75f1787f6f477a64de1714d61
+  metadata.gz: a234432c82f1b580bc19b3f4c29211a98556f277f28f5cdbd9da7c1f08172b9fcddea6f64c9a9dba1bcbe3204e071391f20ad6c48a8aa87ec04f19643f59fc83
+  data.tar.gz: ca5aadb8917b2aa2761592ecec9a7adc98e0d22b24fe1e30f20d398afac625c6ba5b10e5c60f13b84ceeff3e2a44769e732eea2fa55d8f060705ceb90bc0c0c0

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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

@@ -222,6 +222,29 @@ 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.
 
+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

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/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

@@ -41,6 +41,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
@@ -96,6 +102,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 +247,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.3.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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hadar
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -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