idml 0.1.0

data/lib/idml/text_engine/justifier.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Idml
+  module TextEngine
+    # Distributes slack space within a line per the paragraph's
+    # alignment. Adjusts x_offset and optionally scales inter-word
+    # spaces for justified text.
+    class Justifier
+      def self.justify(line:, frame_width:, alignment: :left)
+        new(frame_width, alignment).justify(line)
+      end
+
+      def initialize(frame_width, alignment)
+        @frame_width = frame_width
+        @alignment = alignment
+      end
+
+      def justify(line)
+        case @alignment
+        when :left, :start then line.x_offset = 0
+        when :center, :middle
+          line.x_offset = (@frame_width - line.width) / 2
+        when :right, :end
+          line.x_offset = @frame_width - line.width
+        when :justified then justify_line(line)
+        end
+        line
+      end
+
+      private
+
+      def justify_line(line)
+        spaces = line.glyphs.count(&:is_space)
+        slack = @frame_width - line.width
+        return if spaces.zero? || slack <= 0
+
+        extra = slack / spaces
+        line.glyphs.each do |glyph|
+          next unless glyph.is_space
+
+          glyph.width += extra
+        end
+      end
+    end
+  end
+end

data/lib/idml/text_engine/line_breaker.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Idml
+  module TextEngine
+    # A line of shaped glyphs with its natural width.
+    Line = Struct.new(:glyphs, :width, :x_offset)
+
+    # Greedy word-wrap line breaker. Accumulates glyphs until
+    # exceeding the frame width, then breaks at the last space.
+    class LineBreaker
+      def self.break(glyphs:, frame_width:)
+        new(frame_width).break(glyphs)
+      end
+
+      def initialize(frame_width)
+        @frame_width = frame_width
+      end
+
+      def break(glyphs)
+        lines = []
+        current = []
+        current_width = 0
+        last_space_idx = -1
+        width_at_space = 0
+
+        glyphs.each_with_index do |glyph, _idx|
+          current << glyph
+          current_width += glyph.width
+
+          if glyph.is_space
+            last_space_idx = current.length - 1
+            width_at_space = current_width
+          end
+
+          next unless current_width > @frame_width && current.length > 1
+
+          if last_space_idx >= 0
+            line_glyphs = current[0..last_space_idx]
+            lines << Line.new(line_glyphs, width_at_space, 0)
+            current = current[(last_space_idx + 1)..]
+            current_width = current.sum(&:width)
+            last_space_idx = -1
+          else
+            lines << Line.new(current, current_width, 0)
+            current = []
+            current_width = 0
+          end
+        end
+
+        lines << Line.new(current, current_width, 0) if current.any?
+        lines
+      end
+    end
+  end
+end

data/lib/idml/text_engine/shaper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Idml
+  module TextEngine
+    # Converts a text string + font metrics into a sequence of shaped
+    # glyphs, each carrying its advance width at the given size.
+    ShapedGlyph = Struct.new(:codepoint, :width, :is_space)
+
+    class Shaper
+      def self.shape(text:, font:, size:)
+        new(font, size).shape(text)
+      end
+
+      def initialize(font, size)
+        @font = font
+        @size = size
+        @scale = size.to_f / font.units_per_em
+      end
+
+      def shape(text)
+        glyphs = []
+        text.each_codepoint do |cp|
+          raw_width = @font.glyph_width(cp)
+          width = raw_width * @scale
+          glyphs << ShapedGlyph.new(cp, width, cp == 32)
+        end
+        glyphs
+      end
+
+      def measure(glyphs)
+        glyphs.sum(&:width)
+      end
+    end
+  end
+end

data/lib/idml/text_engine/vertical_layout.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Idml
+  module TextEngine
+    # A glyph with absolute (x, y) position, ready for rendering.
+    PositionedGlyph = Struct.new(:codepoint, :x, :y, :font_size)
+
+    # Positions justified lines vertically within a text frame.
+    # Applies leading, paragraph spacing, first-line indent, and
+    # left/right insets.
+    class VerticalLayout
+      Frame = Struct.new(:x, :y, :width, :height,
+                         :inset_top, :inset_bottom,
+                         :inset_left, :inset_right)
+
+      def self.layout(lines:, frame:, font_size:,
+                      leading: nil, space_before: 0, space_after: 0,
+                      first_line_indent: 0, left_indent: 0)
+        new(frame, font_size, leading, space_before, space_after,
+            first_line_indent, left_indent).layout(lines)
+      end
+
+      def initialize(frame, font_size, leading, space_before,
+                     space_after, first_line_indent, left_indent)
+        @frame = frame
+        @font_size = font_size
+        @leading = leading || (font_size * 1.2)
+        @space_before = space_before
+        @space_after = space_after
+        @first_line_indent = first_line_indent
+        @left_indent = left_indent
+      end
+
+      def layout(lines)
+        result = []
+        y = top_y - @space_before
+        lines.each_with_index do |line, idx|
+          y -= @leading
+          x = frame_left + (idx.zero? ? @first_line_indent : @left_indent)
+          x += line.x_offset.to_f
+          current_x = x
+          line.glyphs.each do |glyph|
+            result << PositionedGlyph.new(glyph.codepoint,
+                                          current_x,
+                                          y,
+                                          @font_size)
+            current_x += glyph.width
+          end
+        end
+        result
+      end
+
+      private
+
+      def top_y
+        @frame.y - (@frame.inset_top || 0)
+      end
+
+      def frame_left
+        @frame.x + (@frame.inset_left || 0)
+      end
+    end
+  end
+end

data/lib/idml/text_engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Idml
+  # Pure-Ruby text layout engine. Takes styled text runs + frame
+  # geometry and produces positioned glyphs using font metrics from
+  # .ttf/.otf files. IDML-agnostic — works on any styled text.
+  module TextEngine
+    autoload :FontMetrics,     "#{__dir__}/text_engine/font_metrics"
+    autoload :FontResolver,    "#{__dir__}/text_engine/font_resolver"
+    autoload :Shaper,          "#{__dir__}/text_engine/shaper"
+    autoload :ShapedGlyph,     "#{__dir__}/text_engine/shaper"
+    autoload :LineBreaker,     "#{__dir__}/text_engine/line_breaker"
+    autoload :Line,            "#{__dir__}/text_engine/line_breaker"
+    autoload :Justifier,       "#{__dir__}/text_engine/justifier"
+    autoload :VerticalLayout,  "#{__dir__}/text_engine/vertical_layout"
+    autoload :PositionedGlyph, "#{__dir__}/text_engine/vertical_layout"
+    autoload :CjkLayout,       "#{__dir__}/text_engine/cjk_layout"
+  end
+end

data/lib/idml/validation/result.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Idml
+  module Validation
+    # Immutable result of validating one part against its RNG schema.
+    # `#ok?` is true when there are no errors. `#errors` is an Array of
+    # Jing-formatted error strings (with line numbers).
+    Result = Struct.new(:part_name, :ok, :errors) do
+      def ok?
+        ok
+      end
+    end
+  end
+end

data/lib/idml/validation/validator.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Idml
+  module Validation
+    # Validates IDML parts against RelaxNG-Compact schemas using Jing.
+    #
+    # Jing is bundled in the InDesign Plug-in SDK at
+    # `reference-docs/plugin_sdk_21/devtools/idmltools/jing/bin/jing.jar`.
+    # The gem does not vendor Jing — users point Validator at a local
+    # jar via the `jing_jar:` argument.
+    #
+    # Schemas are not vendored either. The default schema_root points at
+    # the development tree; users override via `schema_root:`.
+    class Validator
+      DEFAULT_JING_JAR = File.expand_path(
+        "../../../../reference-docs/plugin_sdk_21/" \
+        "devtools/idmltools/jing/bin/jing.jar",
+        __dir__,
+      )
+
+      NON_SCHEMATIZED_PARTS = %w[
+        mimetype
+        META-INF/container.xml
+        META-INF/metadata.xml
+      ].freeze
+
+      SCHEMA_PATHS = {
+        "designmap.xml" => ["designmap.rnc"],
+        %r{\AMasterSpreads/} => ["MasterSpreads", "MasterSpread.rnc"],
+        %r{\ASpreads/} => ["Spreads", "Spread.rnc"],
+        %r{\AStories/} => ["Stories", "Story.rnc"],
+        "Resources/Fonts.xml" => ["Resources", "Fonts.rnc"],
+        "Resources/Graphic.xml" => ["Resources", "Graphic.rnc"],
+        "Resources/Styles.xml" => ["Resources", "Styles.rnc"],
+        "Resources/Preferences.xml" => ["Resources", "Preferences.rnc"],
+        "XML/BackingStory.xml" => ["XML", "BackingStory.rnc"],
+        "XML/Tags.xml" => ["XML", "Tags.rnc"],
+        "XML/Mapping.xml" => ["XML", "Mapping.rnc"],
+      }.freeze
+      private_constant :SCHEMA_PATHS
+
+      def initialize(schema_root: Idml::Validation::DEFAULT_SCHEMA_ROOT,
+                     jing_jar: DEFAULT_JING_JAR)
+        @schema_root = schema_root
+        @jing_jar = jing_jar
+      end
+
+      attr_reader :schema_root, :jing_jar
+
+      def validate_part(part_name, xml)
+        schema = schema_path_for(part_name)
+        unless schema
+          return Result.new(part_name, false,
+                            ["no schema mapping for #{part_name}"])
+        end
+
+        output, status = run_jing(schema, xml)
+        ok = status.success? && output.empty?
+        errors = ok ? [] : output.split("\n").grep(/error:/)
+        Result.new(part_name, ok, errors)
+      end
+
+      # Tolerate DOMVersion mismatches by blanking the attribute before
+      # validation. Useful for older IDML files: catches every schema
+      # violation except version drift, which is expected.
+      def loose_validate_part(part_name, xml)
+        loosened = xml.gsub(/DOMVersion="[^"]*"/, 'DOMVersion=""')
+        result = validate_part(part_name, loosened)
+        return result if result.ok?
+
+        non_version_errors = result.errors.reject do |e|
+          e.include?("DOMVersion")
+        end
+        Result.new(part_name, non_version_errors.empty?, non_version_errors)
+      end
+
+      def validate_package(package)
+        package.part_names.filter_map do |name|
+          next if NON_SCHEMATIZED_PARTS.include?(name)
+
+          validate_part(name, package.read_part(name))
+        end
+      end
+
+      private
+
+      def schema_path_for(part_name)
+        _, segments = SCHEMA_PATHS.find do |pattern, _|
+          if pattern.is_a?(Regexp)
+            pattern.match?(part_name)
+          else
+            pattern == part_name
+          end
+        end
+        return nil unless segments
+
+        File.join(@schema_root, *segments)
+      end
+
+      def run_jing(schema, xml)
+        raise JavaUnavailable, "java not found on PATH" unless java_available?
+
+        Tempfile.create("idml-validate") do |tmp|
+          tmp.write(xml)
+          tmp.close
+          stdout, status = Open3.capture2e("java", "-jar", @jing_jar, "-c",
+                                           schema, tmp.path)
+          [stdout, status]
+        end
+      end
+
+      def java_available?
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+          File.executable?(File.join(dir, "java"))
+        end
+      end
+    end
+  end
+end

data/lib/idml/validation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Idml
+  module Validation
+    autoload :Validator, "#{__dir__}/validation/validator"
+    autoload :Result,    "#{__dir__}/validation/result"
+
+    # Default schema root: the development tree's generated schemas.
+    # Override per-call by passing `schema_root:` to Validator.new.
+    DEFAULT_SCHEMA_ROOT = File.expand_path(
+      "../../../reference-docs/schemas/package", __dir__
+    )
+  end
+end

data/lib/idml/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Idml
+  VERSION = "0.1.0"
+end

data/lib/idml.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require "zip"
+require "fileutils"
+require "tempfile"
+
+module Idml
+  autoload :VERSION,            "#{__dir__}/idml/version"
+  autoload :Errors,             "#{__dir__}/idml/errors"
+  autoload :PackagingNamespace, "#{__dir__}/idml/namespace"
+  autoload :Part,               "#{__dir__}/idml/part"
+  autoload :Parts,              "#{__dir__}/idml/parts"
+  autoload :Elements,           "#{__dir__}/idml/elements"
+  autoload :Package,            "#{__dir__}/idml/package"
+  autoload :Document,           "#{__dir__}/idml/document"
+  autoload :Validation,         "#{__dir__}/idml/validation"
+  autoload :Composition,        "#{__dir__}/idml/composition"
+  autoload :Geometry,           "#{__dir__}/idml/geometry"
+  autoload :TextEngine,         "#{__dir__}/idml/text_engine"
+  autoload :Render,             "#{__dir__}/idml/render"
+  autoload :CLI,                "#{__dir__}/idml/cli"
+
+  # Convenience: open an IDML file. Equivalent to Package.new(path).
+  def self.open(path)
+    Package.new(path)
+  end
+
+  # Convenience: wrap a Package in a Document for cross-part queries.
+  def self.document(package)
+    Document.new(package)
+  end
+end

data/reference-docs/schemas/README.md

@@ -0,0 +1,79 @@
+# IDML Schemas
+
+Relax-NG Compact syntax (`.rnc`) schemas for Adobe IDML, generated by
+InDesign's `app.generateIDMLSchema()` API.
+
+## Source
+
+- **InDesign version**: 2026 (21.5.0.64)
+- **DOMVersion**: `21.5`
+- **Generator**: `app.generateIDMLSchema()` (Adobe InDesign IDML Cookbook, "How do I generate a schema?")
+- **Generation scripts**: `../plugin_sdk_21/devtools/idmltools/scripts/{GenerateSchema,GeneratePackageSchema}.jsx` (edited to write into this directory)
+- **Generation date**: 2026-08-01
+- **Validator**: Jing 20030619 at `../plugin_sdk_21/devtools/idmltools/jing/bin/jing.jar`
+
+## Layout
+
+```
+schemas/
+├── package/                      # IDML package schema (ZIP-of-XML-parts)
+│   ├── datatype.rnc              # shared types — PATCHED, see below
+│   ├── designmap.rnc
+│   ├── MasterSpreads/MasterSpread.rnc
+│   ├── Spreads/Spread.rnc
+│   ├── Stories/Story.rnc
+│   ├── Resources/{Fonts,Graphic,Preferences,Styles}.rnc
+│   └── XML/{BackingStory,Mapping,Tags}.rnc
+├── single/                       # consolidated non-package schema
+│   ├── datatype.rnc              # PATCHED
+│   └── IDMarkupLanguage.rnc      # full document grammar
+├── fix-adobe-schema-bug.rb       # reapplies the patch below
+└── README.md                     # this file
+```
+
+## Known Adobe bug (patched)
+
+`app.generateIDMLSchema()` leaks raw documentation prose into `datatype.rnc`
+at lines 177–196 — a wiki-style table about Folio metadata that should have
+been emitted as RNC comments. The leaked range is invalid RNC, and every
+downstream part file fails validation because the parse failure cascades:
+all `*_EnumValue` references declared in `datatype.rnc` become undefined.
+
+The patch (in `fix-adobe-schema-bug.rb`) comments out the broken prose
+range idempotently. It matches the fix PatrickAgostini applied in their
+pre-extracted schemas at `~/src/external/idml/schema/rnc/Packaging/datatype.rnc`.
+
+## Regeneration procedure
+
+1. In InDesign 2026, open `Window → Utilities → Scripts` (⌘⌥F11).
+2. Double-click `GeneratePackageSchema.jsx` (under the **User** folder). Output lands at `reference-docs/schemas/package/`. Wait 30–60s.
+3. Double-click `GenerateSchema.jsx`. Output lands at `reference-docs/schemas/single/`.
+4. Run `ruby reference-docs/schemas/fix-adobe-schema-bug.rb` to patch both `datatype.rnc` files.
+5. Sanity-check with Jing:
+   ```bash
+   java -jar ../plugin_sdk_21/devtools/idmltools/jing/bin/jing.jar -c \
+     package/Spreads/Spread.rnc /path/to/Spreads/Spread_*.xml
+   ```
+
+## Version compatibility
+
+These schemas are tied to InDesign 2026 (DOMVersion `21.5`). IDML files
+saved by older InDesign versions will fail strict validation on:
+
+- `DOMVersion` attribute mismatch (the schema hardcodes `"21.5"`).
+- Attributes added after the file's source version (e.g. `TitleCheck`,
+  `IsAnEndnoteStory`, `ParagraphBorderLineWeight`,
+  `ParagraphShadeTopLeftCornerOption`).
+
+This is expected. For round-trip testing, use IDML fixtures exported from
+InDesign 2026. For round-trip of older IDML, strict schema validation is
+unavailable — rely on byte-equivalence per part instead.
+
+## Schema authority priority
+
+For the `idml` gem, this directory is the highest-priority schema source
+(canonical for the user's InDesign version). Lower-priority fallbacks,
+in order: pre-extracted RNG/RNC at `~/src/external/idml/schema/{rng,rnc}/`,
+spec markdown at `~/src/external/idml-schema/docs/idml-specification/`,
+and Adobe's idmltools Java source for behavioral edge cases. See the
+top-level `CLAUDE.md` for the full reference-material table.

data/reference-docs/schemas/fix-adobe-schema-bug.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Patches Adobe's known bug in datatype.rnc output from
+# app.generateIDMLSchema(). The generator leaks raw documentation prose
+# (a wiki-style table about Folio metadata) into the RNC between the
+# last valid comment and the next valid type definition. The leaked
+# range is invalid RNC, and every downstream part file fails validation
+# because the datatype.rnc parse failure cascades — every *_EnumValue
+# reference becomes undefined.
+#
+# The fix: comment out the broken range. Matches the fix
+# PatrickAgostini applied in their pre-extracted schemas at
+# ~/src/external/idml/schema/rnc/Packaging/datatype.rnc.
+#
+# Affects both the package and the single (consolidated) schema variants.
+# Idempotent: detects already-commented sections and skips them.
+#
+# Usage:
+#   ruby fix-adobe-schema-bug.rb                       # patch every datatype.rnc under this dir
+#   ruby fix-adobe-schema-bug.rb path/to/datatype.rnc  # patch specific file(s)
+
+# Markers delimiting the broken prose block. The block starts AFTER
+# this comment line (which is valid RNC) and ends RIGHT BEFORE this
+# RNC definition (also valid). Every line strictly between needs
+# commenting.
+START_MARKER = /# Metadata information for an exported folio\.\s*\z/
+END_MARKER = /\AExportFolioMetaData_TypeDef\s*=/
+
+def patched?(lines)
+  start_idx = lines.index { |l| l.match?(START_MARKER) }
+  return false unless start_idx && lines[start_idx + 1]
+
+  # If the line immediately after the start marker is already commented
+  # (a blank-comment "#" or any "# ..."), the file has been patched.
+  lines[start_idx + 1].start_with?("#")
+end
+
+def patch(path)
+  return :missing unless File.file?(path)
+
+  lines = File.readlines(path, chomp: true)
+  return :already_patched if patched?(lines)
+
+  start_idx = lines.index { |l| l.match?(START_MARKER) }
+  end_idx = lines.index { |l| l.match?(END_MARKER) }
+  return :markers_not_found unless start_idx && end_idx && end_idx > start_idx
+
+  ((start_idx + 1)...end_idx).each do |i|
+    line = lines[i]
+    next if line.start_with?("#")
+
+    lines[i] = line.strip.empty? ? "#" : "# #{line}"
+  end
+
+  File.write(path, lines.join("\n") + "\n")
+  :patched
+end
+
+default_glob = File.expand_path("**/datatype.rnc", __dir__)
+paths = ARGV.empty? ? Dir[default_glob] : ARGV
+
+if paths.empty?
+  warn "no datatype.rnc files found"
+  exit 1
+end
+
+results = paths.map { |p| [p, patch(p)] }
+results.each { |p, r| puts "#{p}: #{r}" }