uniword 1.3.0 → 1.4.1

data/lib/uniword/ooxml/part_definition.rb

@@ -5,9 +5,11 @@ module Uniword
     # Declarative description of one OOXML package part kind.
     #
     # A PartDefinition is the single source of truth for a part's
-    # package path, content type, relationship type, and the form its
+    # package path, content type, relationship type, the form its
     # [Content_Types].xml entry takes (Default by extension or Override
-    # by part name). Instances are immutable value objects registered
+    # by part name), how it is loaded from extracted ZIP content, and
+    # where it lives on both Wordprocessingml::DocumentRoot and
+    # Docx::Package. Instances are immutable value objects registered
     # in {PartRegistry}; consumers derive every literal from them.
     #
     # Parts with instance-numbered paths (headers, footers, charts,
@@ -15,12 +17,21 @@ module Uniword
     # +format+-style placeholders (e.g. "word/header%<counter>d.xml")
     # instead of a fixed path.
     #
+    # Load behavior beyond this data (parse rules for special part
+    # kinds) lives in named Docx::PartLoader strategy classes selected
+    # by +loader+; the definition itself stays a value object.
+    #
     # @example Fixed part
     #   PartDefinition.new(
     #     key: :styles, path: "word/styles.xml", target: "styles.xml",
     #     content_type: "...styles+xml",
     #     rel_type: ".../relationships/styles",
     #     required: true, kind: :override, rels_scope: :document,
+    #     loader: :xml_model,
+    #     loader_model: Uniword::Wordprocessingml::StylesConfiguration,
+    #     load_priority: 50,
+    #     package_attribute: :styles,
+    #     document_attribute: :styles_configuration,
     #   )
     class PartDefinition
       # @return [Symbol] unique registry key (e.g. :styles)
@@ -65,11 +76,60 @@ module Uniword
       #   the comprehensive [Content_Types].xml for new DOCX packages
       attr_reader :standard
 
-      # rubocop:disable Metrics/ParameterLists
+      # @return [Symbol, nil] Docx::PartLoader strategy key
+      #   (:xml_model, :custom_xml, :header_footer, :chart, :image,
+      #   :embedding, :theme_media); nil when the part is not loaded
+      #   from ZIP content
+      attr_reader :loader
+
+      # @return [Class, nil] model class parsing the part's XML
+      #   (responds to +.from_xml+); used by loaders that parse
+      attr_reader :loader_model
+
+      # @return [Symbol, nil] dynamic path resolution rule:
+      #   :office_document (resolve the main document path from the
+      #   package-level officeDocument relationship) or
+      #   :office_document_rels (sidecar .rels of the resolved main
+      #   document); nil for fixed paths
+      attr_reader :path_resolution
+
+      # @return [Integer, nil] load ordering weight — lower loads
+      #   first; entries sharing a priority load in registration order
+      attr_reader :load_priority
+
+      # @return [Symbol, nil] attribute (reader/writer) holding this
+      #   part on Wordprocessingml::DocumentRoot
+      attr_reader :document_attribute
+
+      # @return [Symbol, nil] attribute (reader/writer) holding this
+      #   part on Docx::Package
+      attr_reader :package_attribute
+
+      # @return [Boolean] whether the package→document copy includes
+      #   this part (false when the loader already places the part on
+      #   the document, or the part is never read from ZIP content)
+      attr_reader :copy_to_document
+
+      # @return [Symbol, nil] predicate on the document guarding the
+      #   document→package copy (e.g. :numbering_configuration_loaded?
+      #   for the lazily-initialized numbering configuration)
+      attr_reader :to_package_guard
+
+      # @return [Class, nil] class the value must be an instance of
+      #   for the document→package copy (e.g. CommentsPart, since
+      #   DocumentRoot#comments can hold non-part values)
+      attr_reader :to_package_type
+
+      # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+      # rubocop:disable Metrics/AbcSize
       def initialize(key:, kind:, path: nil, path_pattern: nil,
                      target: nil, target_pattern: nil,
                      content_type: nil, rel_type: nil, extension: nil,
-                     required: false, rels_scope: nil, standard: false)
+                     required: false, rels_scope: nil, standard: false,
+                     loader: nil, loader_model: nil, path_resolution: nil,
+                     load_priority: nil, document_attribute: nil,
+                     package_attribute: nil, copy_to_document: true,
+                     to_package_guard: nil, to_package_type: nil)
         @key = key.to_sym
         @kind = kind
         @path = path
@@ -82,8 +142,18 @@ module Uniword
         @required = required
         @rels_scope = rels_scope
         @standard = standard
+        @loader = loader
+        @loader_model = loader_model
+        @path_resolution = path_resolution
+        @load_priority = load_priority
+        @document_attribute = document_attribute
+        @package_attribute = package_attribute
+        @copy_to_document = copy_to_document
+        @to_package_guard = to_package_guard
+        @to_package_type = to_package_type
       end
-      # rubocop:enable Metrics/ParameterLists
+      # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize
 
       # @return [Boolean] true for [Content_Types].xml Override entries
       def override?
@@ -110,6 +180,40 @@ module Uniword
         rels_scope == :package
       end
 
+      # @return [Boolean] true when the part loads from ZIP content
+      def loadable?
+        !loader.nil?
+      end
+
+      # @return [Boolean] true when the package→document copy mirrors
+      #   this part onto Wordprocessingml::DocumentRoot
+      def copy_to_document?
+        !!copy_to_document
+      end
+
+      # Whether a package path matches this definition's fixed path or
+      # path pattern. Accepts both "word/styles.xml" and
+      # "/word/styles.xml" forms, and matches numbered paths against
+      # the pattern ("word/header2.xml" → :header).
+      #
+      # @param candidate [String] package-relative path
+      # @return [Boolean]
+      def match_path?(candidate)
+        normalized = candidate.to_s.delete_prefix("/")
+        return true if path == normalized
+        return false unless path_pattern
+
+        normalized.match?(template_regex(path_pattern))
+      end
+
+      # Static prefix of the path pattern up to the first placeholder
+      # (e.g. "word/theme/media/" for "word/theme/media/%<name>s").
+      #
+      # @return [String, nil] nil for fixed-path definitions
+      def pattern_prefix
+        path_pattern&.split(/%<\w+>[ds]/)&.first
+      end
+
       # Resolve the package-relative path, interpolating pattern
       # placeholders for instance-numbered parts.
       #
@@ -143,6 +247,21 @@ module Uniword
         path && "/#{path}"
       end
 
+      # Package paths this part kind emits for the given package.
+      #
+      # Single-instance kinds emit their fixed +path+ when the backing
+      # model is present; collection families emit each stored part's
+      # own paths (each part object answers +package_paths+).
+      #
+      # @param package [Docx::Package] Package to enumerate for
+      # @return [Array<String>] emitted package paths (possibly empty)
+      def emitted_paths(package)
+        source = attribute_source(package)
+        return [] if source.nil?
+
+        collection? ? collection_paths(source) : [path]
+      end
+
       # Two definitions are equal when every field matches.
       def ==(other)
         other.is_a?(PartDefinition) && fields == other.fields
@@ -152,20 +271,59 @@ module Uniword
 
       # @return [Array] field values in declaration order, used for
       #   value equality
+      # rubocop:disable Metrics/AbcSize
       def fields
         [key, kind, path, path_pattern, target, target_pattern,
          content_type, rel_type, extension, required, rels_scope,
-         standard]
+         standard, loader, loader_model, path_resolution,
+         load_priority, document_attribute, package_attribute,
+         copy_to_document, to_package_guard, to_package_type]
       end
+      # rubocop:enable Metrics/AbcSize
 
       private
 
+      # The model object backing this part kind on the package: the
+      # package attribute when set, else the document attribute read
+      # through the package's document.
+      def attribute_source(package)
+        value = package_attribute && package.method(package_attribute).call
+        return value if value
+
+        document_attribute &&
+          package.document&.method(document_attribute)&.call
+      end
+
+      # Families (path_pattern, no fixed path) enumerate their parts;
+      # single-instance kinds do not.
+      def collection?
+        path.nil?
+      end
+
+      def collection_paths(source)
+        values = source.is_a?(Docx::PartCollection) ? source.values : source
+        values.flat_map(&:package_paths)
+      end
+
       def expand(template, vars)
         return nil unless template
         return template if vars.empty?
 
         format(template, vars)
       end
+
+      # Convert a pattern like "word/header%<counter>d.xml" into a
+      # matching regexp: %<name>d → digits, %<name>s → any path run.
+      def template_regex(template)
+        source = template.split(/(%<\w+>[ds])/).map do |part|
+          case part
+          when /%<\w+>d/ then "\\d+"
+          when /%<\w+>s/ then ".+?"
+          else Regexp.escape(part)
+          end
+        end.join
+        /\A#{source}\z/
+      end
     end
   end
 end

data/lib/uniword/ooxml/part_registry.rb

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Uniword
   module Ooxml
     # Single source of truth for OOXML package part metadata.
     #
-    # Maps every part kind the library writes to its package path,
-    # content type, relationship type, and [Content_Types].xml entry
-    # form (Default vs Override). Content type and relationship type
-    # literals live ONLY here; consumers (Uniword::ContentTypes,
-    # Docx::PackageDefaults, Docx::Reconciler::PackageStructure, and
-    # the Docx::PackageSerialization inject_* methods) derive from
-    # this registry instead of holding their own literals.
+    # Maps every part kind the library reads or writes to its package
+    # path, content type, relationship type, [Content_Types].xml entry
+    # form (Default vs Override), loader strategy, and document/package
+    # attributes. Content type and relationship type literals live ONLY
+    # here; consumers (Uniword::ContentTypes, Docx::PackageDefaults,
+    # Docx::Reconciler::PackageStructure, Docx::PartLoader,
+    # DocumentFactory, and the Docx::PackageSerialization inject_*
+    # methods) derive from this registry instead of holding their own
+    # literals.
     #
     # Open/closed: a new part kind is added by registering a
     # PartDefinition — consumers need no further changes.
@@ -46,6 +50,14 @@ module Uniword
       # jpeg, png, gif, rels, xml — then overrides in the historic
       # order). Non-standard parts follow; consumers select their own
       # ordered subsets by key.
+      #
+      # Loader metadata: +loader+ selects the Docx::PartLoader
+      # strategy, +loader_model+ the parsing model class,
+      # +load_priority+ orders the load (content types and package
+      # rels first; the main document before the parts its rels
+      # describe), and +document_attribute+/+package_attribute+ name
+      # where the part lives on Wordprocessingml::DocumentRoot and
+      # Docx::Package for the two registry-driven copy loops.
       BUILT_INS = [
         # -- Content-type Defaults (extension → content type) --
         { key: :jpeg, kind: :default, extension: "jpeg",
@@ -65,104 +77,189 @@ module Uniword
         { key: :document, kind: :override, path: "word/document.xml",
           content_type: "#{CT_WML}.document.main+xml",
           rel_type: "#{OFFICE_REL_BASE}/officeDocument",
-          required: true, standard: true, rels_scope: :package },
+          required: true, standard: true, rels_scope: :package,
+          loader: :xml_model,
+          loader_model: Uniword::Wordprocessingml::DocumentRoot,
+          path_resolution: :office_document, load_priority: 40,
+          package_attribute: :document },
         { key: :numbering, kind: :override, path: "word/numbering.xml",
           target: "numbering.xml", content_type: "#{CT_WML}.numbering+xml",
           rel_type: "#{OFFICE_REL_BASE}/numbering",
-          standard: true, rels_scope: :document },
+          standard: true, rels_scope: :document,
+          loader: :xml_model,
+          loader_model: Uniword::Wordprocessingml::NumberingConfiguration,
+          load_priority: 50,
+          package_attribute: :numbering,
+          document_attribute: :numbering_configuration,
+          to_package_guard: :numbering_configuration_loaded? },
         { key: :styles, kind: :override, path: "word/styles.xml",
           target: "styles.xml", content_type: "#{CT_WML}.styles+xml",
           rel_type: "#{OFFICE_REL_BASE}/styles",
-          required: true, standard: true, rels_scope: :document },
+          required: true, standard: true, rels_scope: :document,
+          loader: :xml_model,
+          loader_model: Uniword::Wordprocessingml::StylesConfiguration,
+          load_priority: 50,
+          package_attribute: :styles,
+          document_attribute: :styles_configuration },
         { key: :settings, kind: :override, path: "word/settings.xml",
           target: "settings.xml", content_type: "#{CT_WML}.settings+xml",
           rel_type: "#{OFFICE_REL_BASE}/settings",
-          required: true, standard: true, rels_scope: :document },
+          required: true, standard: true, rels_scope: :document,
+          loader: :xml_model,
+          loader_model: Uniword::Wordprocessingml::Settings,
+          load_priority: 50,
+          package_attribute: :settings, document_attribute: :settings },
         { key: :web_settings, kind: :override, path: "word/webSettings.xml",
           target: "webSettings.xml",
           content_type: "#{CT_WML}.webSettings+xml",
           rel_type: "#{OFFICE_REL_BASE}/webSettings",
-          required: true, standard: true, rels_scope: :document },
+          required: true, standard: true, rels_scope: :document,
+          loader: :xml_model,
+          loader_model: Uniword::Wordprocessingml::WebSettings,
+          load_priority: 50,
+          package_attribute: :web_settings,
+          document_attribute: :web_settings },
         { key: :font_table, kind: :override, path: "word/fontTable.xml",
           target: "fontTable.xml",
           content_type: "#{CT_WML}.fontTable+xml",
           rel_type: "#{OFFICE_REL_BASE}/fontTable",
-          required: true, standard: true, rels_scope: :document },
+          required: true, standard: true, rels_scope: :document,
+          loader: :xml_model,
+          loader_model: Uniword::Wordprocessingml::FontTable,
+          load_priority: 50,
+          package_attribute: :font_table,
+          document_attribute: :font_table },
         { key: :theme, kind: :override, path: "word/theme/theme1.xml",
           target: "theme/theme1.xml",
           content_type: "#{CT_OFFICE}.theme+xml",
           rel_type: "#{OFFICE_REL_BASE}/theme",
-          standard: true, rels_scope: :document },
+          standard: true, rels_scope: :document,
+          loader: :xml_model, loader_model: Uniword::Drawingml::Theme,
+          load_priority: 70,
+          package_attribute: :theme, document_attribute: :theme },
         { key: :core_properties, kind: :override, path: "docProps/core.xml",
           content_type: "#{CT_PACKAGE}.core-properties+xml",
           rel_type: "#{PACKAGE_REL_BASE}/metadata/core-properties",
-          required: true, standard: true, rels_scope: :package },
+          required: true, standard: true, rels_scope: :package,
+          loader: :xml_model, loader_model: CoreProperties,
+          load_priority: 30,
+          package_attribute: :core_properties,
+          document_attribute: :core_properties },
         { key: :app_properties, kind: :override, path: "docProps/app.xml",
           content_type: "#{CT_OFFICE}.extended-properties+xml",
           rel_type: "#{OFFICE_REL_BASE}/extended-properties",
-          required: true, standard: true, rels_scope: :package },
+          required: true, standard: true, rels_scope: :package,
+          loader: :xml_model, loader_model: AppProperties,
+          load_priority: 30,
+          package_attribute: :app_properties,
+          document_attribute: :app_properties },
 
         # -- Optional document parts --
         { key: :footnotes, kind: :override, path: "word/footnotes.xml",
           target: "footnotes.xml",
           content_type: "#{CT_WML}.footnotes+xml",
           rel_type: "#{OFFICE_REL_BASE}/footnotes",
-          rels_scope: :document },
+          rels_scope: :document,
+          loader: :xml_model,
+          loader_model: Uniword::Wordprocessingml::Footnotes,
+          load_priority: 80,
+          package_attribute: :footnotes, document_attribute: :footnotes },
         { key: :endnotes, kind: :override, path: "word/endnotes.xml",
           target: "endnotes.xml",
           content_type: "#{CT_WML}.endnotes+xml",
           rel_type: "#{OFFICE_REL_BASE}/endnotes",
-          rels_scope: :document },
+          rels_scope: :document,
+          loader: :xml_model,
+          loader_model: Uniword::Wordprocessingml::Endnotes,
+          load_priority: 80,
+          package_attribute: :endnotes, document_attribute: :endnotes },
         { key: :comments, kind: :override, path: "word/comments.xml",
           target: "comments.xml",
           content_type: "#{CT_WML}.comments+xml",
           rel_type: "#{OFFICE_REL_BASE}/comments",
-          rels_scope: :document },
+          rels_scope: :document,
+          loader: :xml_model, loader_model: Uniword::CommentsPart,
+          load_priority: 80,
+          package_attribute: :comments, document_attribute: :comments,
+          to_package_type: Uniword::CommentsPart },
+        # Bibliography sources live only on the document (single home:
+        # DocumentRoot#bibliography_sources); nothing reads
+        # word/sources.xml back, so there is no loader.
         { key: :bibliography, kind: :override, path: "word/sources.xml",
           target: "sources.xml",
           content_type: "#{CT_OFFICE}.bibliography+xml",
           rel_type: "#{OFFICE_REL_BASE}/bibliography",
-          rels_scope: :document },
+          rels_scope: :document,
+          document_attribute: :bibliography_sources },
         { key: :header, kind: :override,
           path_pattern: "word/header%<counter>d.xml",
           target_pattern: "header%<counter>d.xml",
           content_type: "#{CT_WML}.header+xml",
           rel_type: "#{OFFICE_REL_BASE}/header",
-          rels_scope: :document },
+          rels_scope: :document,
+          loader: :header_footer,
+          loader_model: Uniword::Wordprocessingml::Header,
+          load_priority: 90,
+          document_attribute: :header_footer_parts },
         { key: :footer, kind: :override,
           path_pattern: "word/footer%<counter>d.xml",
           target_pattern: "footer%<counter>d.xml",
           content_type: "#{CT_WML}.footer+xml",
           rel_type: "#{OFFICE_REL_BASE}/footer",
-          rels_scope: :document },
+          rels_scope: :document,
+          loader: :header_footer,
+          loader_model: Uniword::Wordprocessingml::Footer,
+          load_priority: 90,
+          document_attribute: :header_footer_parts },
         { key: :custom_properties, kind: :override,
           path: "docProps/custom.xml",
           content_type: "#{CT_OFFICE}.custom-properties+xml",
           rel_type: "#{OFFICE_REL_BASE}/custom-properties",
-          rels_scope: :package },
+          rels_scope: :package,
+          loader: :xml_model, loader_model: CustomProperties,
+          load_priority: 30,
+          package_attribute: :custom_properties,
+          document_attribute: :custom_properties },
+        # The chart loader keys parts by document relationship id, so
+        # they land directly on the document — the single home for
+        # chart parts (DocumentRoot#chart_parts).
         { key: :chart, kind: :override,
           path_pattern: "word/charts/chart%<n>d.xml",
           target_pattern: "charts/chart%<n>d.xml",
           content_type: "#{CT_OFFICE}.drawingml.chart+xml",
           rel_type: "#{OFFICE_REL_BASE}/chart",
-          rels_scope: :document },
+          rels_scope: :document,
+          loader: :chart, load_priority: 100,
+          document_attribute: :chart_parts },
         # Images carry a per-extension Default content type resolved
         # from the image data at save time, so content_type is nil.
         { key: :image, kind: :default,
           path_pattern: "word/media/%<name>s",
           target_pattern: "media/%<name>s",
           rel_type: "#{OFFICE_REL_BASE}/image",
-          rels_scope: :document },
+          rels_scope: :document,
+          loader: :image, load_priority: 110,
+          document_attribute: :image_parts },
+        # The embedding loader keys parts by target on the package's
+        # embeddings collection; no package→document copy.
         { key: :ole_object, kind: :override,
           path_pattern: "word/embeddings/%<name>s",
           target_pattern: "embeddings/%<name>s",
           content_type: "#{CT_OFFICE}.oleObject",
           rel_type: "#{OFFICE_REL_BASE}/oleObject",
-          rels_scope: :document },
+          rels_scope: :document,
+          loader: :embedding, load_priority: 120,
+          package_attribute: :embeddings,
+          document_attribute: :embeddings,
+          copy_to_document: false },
         # customXml items themselves fall under the "xml" Default;
-        # only their itemProps parts get an Override.
+        # only their itemProps parts get an Override. The :custom_xml
+        # loader also pulls each item's itemProps and .rels sidecars.
         { key: :custom_xml_item, kind: :none,
-          path_pattern: "customXml/item%<index>d.xml" },
+          path_pattern: "customXml/item%<index>d.xml",
+          loader: :custom_xml, load_priority: 30,
+          package_attribute: :custom_xml_items,
+          document_attribute: :custom_xml_items },
         { key: :custom_xml_item_props, kind: :override,
           path_pattern: "customXml/itemProps%<index>d.xml",
           content_type: "#{CT_OFFICE}.customXmlProperties+xml" },
@@ -174,6 +271,73 @@ module Uniword
         # Theme part of THMX (theme) packages, rooted at /theme.
         { key: :thmx_theme, kind: :override, path: "theme/theme1.xml",
           content_type: "#{CT_OFFICE}.theme+xml", required: true },
+
+        # -- Read-side infrastructure parts (no content-type entry
+        #    of their own; kind :none keeps emission untouched) --
+        { key: :content_types, kind: :none, path: "[Content_Types].xml",
+          loader: :xml_model, loader_model: Uniword::ContentTypes::Types,
+          load_priority: 10,
+          package_attribute: :content_types,
+          document_attribute: :content_types },
+        { key: :package_rels, kind: :none, path: "_rels/.rels",
+          loader: :xml_model,
+          loader_model: Relationships::PackageRelationships,
+          load_priority: 20,
+          package_attribute: :package_rels,
+          document_attribute: :package_rels },
+        { key: :document_rels, kind: :none,
+          path: "word/_rels/document.xml.rels",
+          loader: :xml_model,
+          loader_model: Relationships::PackageRelationships,
+          path_resolution: :office_document_rels, load_priority: 60,
+          package_attribute: :document_rels,
+          document_attribute: :document_rels },
+        { key: :settings_rels, kind: :none,
+          path: "word/_rels/settings.xml.rels",
+          loader: :xml_model,
+          loader_model: Relationships::PackageRelationships,
+          load_priority: 50,
+          package_attribute: :settings_rels,
+          document_attribute: :settings_rels },
+        { key: :theme_rels, kind: :none,
+          path: "word/theme/_rels/theme1.xml.rels",
+          loader: :xml_model,
+          loader_model: Relationships::PackageRelationships,
+          load_priority: 75,
+          package_attribute: :theme_rels,
+          document_attribute: :theme_rels },
+        { key: :footnotes_rels, kind: :none,
+          path: "word/_rels/footnotes.xml.rels",
+          loader: :xml_model,
+          loader_model: Relationships::PackageRelationships,
+          load_priority: 85,
+          package_attribute: :footnotes_rels,
+          document_attribute: :footnotes_rels },
+        { key: :endnotes_rels, kind: :none,
+          path: "word/_rels/endnotes.xml.rels",
+          loader: :xml_model,
+          loader_model: Relationships::PackageRelationships,
+          load_priority: 85,
+          package_attribute: :endnotes_rels,
+          document_attribute: :endnotes_rels },
+        # Theme media files live on the theme's media_files, not on a
+        # package/document attribute; loads only when a theme part was
+        # parsed (see PartLoader::ThemeMediaLoader).
+        { key: :theme_media, kind: :none,
+          path_pattern: "word/theme/media/%<name>s",
+          loader: :theme_media, load_priority: 72 },
+        # Fallback passthrough for parts no definition claims
+        # (unmodelled parts such as docProps/meta.xml, glossary
+        # documents, VBA projects): the :raw loader runs last and
+        # carries the remainder byte-for-byte on the package's
+        # raw_parts collection. Emission is derived from the stored
+        # parts like any collection family, so emitted_paths — and
+        # with it the reconciler's dangling-relationship sweep — sees
+        # raw-carried parts as first-class.
+        { key: :raw_parts, kind: :none,
+          loader: :raw, load_priority: 130,
+          package_attribute: :raw_parts,
+          document_attribute: :raw_parts },
       ].freeze
 
       class << self
@@ -278,6 +442,51 @@ module Uniword
           definitions.filter_map { |d| d.rel_type if d.package_rel? }
         end
 
+        # Definitions loadable from extracted ZIP content, in load
+        # order: ascending PartDefinition#load_priority, registration
+        # order within a priority (explicit index tiebreak — Ruby's
+        # sort_by is not stable).
+        #
+        # @return [Array<PartDefinition>]
+        def loadable
+          definitions.select(&:loadable?).each_with_index
+            .sort_by { |d, i| [d.load_priority || 100, i] }
+            .map(&:first)
+        end
+
+        # Definitions mirrored package→document by
+        # DocumentFactory.copy_package_parts_to_document.
+        #
+        # @return [Array<PartDefinition>] in registration order
+        def copied_to_document
+          definitions.select do |d|
+            d.document_attribute && d.package_attribute &&
+              d.copy_to_document?
+          end
+        end
+
+        # Definitions mirrored document→package by
+        # Docx::PackageDefaults.copy_document_parts_to_package.
+        #
+        # @return [Array<PartDefinition>] in registration order
+        def copied_to_package
+          definitions.select { |d| d.document_attribute && d.package_attribute }
+        end
+
+        # Package paths the given package will emit, derived from the
+        # definitions: single-instance kinds by model presence,
+        # collection families by their stored parts.
+        #
+        # Single authority for "will this part be emitted?" — used by
+        # the reconciler's dangling-relationship sweep.
+        #
+        # @param package [Docx::Package] Package to enumerate for
+        # @return [Set<String>] emitted package paths
+        def emitted_paths(package)
+          all.flat_map { |definition| definition.emitted_paths(package) }
+            .compact.to_set
+        end
+
         private
 
         def definitions
@@ -285,23 +494,7 @@ module Uniword
         end
 
         def path_match?(definition, normalized_path)
-          return true if definition.path == normalized_path
-
-          pattern = definition.path_pattern
-          !pattern.nil? && normalized_path.match?(template_regex(pattern))
-        end
-
-        # Convert a pattern like "word/header%<counter>d.xml" into a
-        # matching regexp: %<name>d → digits, %<name>s → any path run.
-        def template_regex(template)
-          source = template.split(/(%<\w+>[ds])/).map do |part|
-            case part
-            when /%<\w+>d/ then "\\d+"
-            when /%<\w+>s/ then ".+?"
-            else Regexp.escape(part)
-            end
-          end.join
-          /\A#{source}\z/
+          definition.match_path?(normalized_path)
         end
       end
 

data/lib/uniword/ooxml/relationships/image_relationship.rb

@@ -9,9 +9,12 @@ module Uniword
       #
       # Used for image relationships in documents
       class ImageRelationship < Relationship
-        def initialize(target:)
+        # @param id [String] relationship ID (allocated by
+        #   Docx::IdAllocator — the single rId authority)
+        # @param target [String] image part target (e.g. "media/image1.png")
+        def initialize(id:, target:)
           super(
-            id: "rId#{SecureRandom.hex(4)}",
+            id: id,
             type: PartRegistry.find_by_key(:image).rel_type,
             target: target
           )

data/lib/uniword/ooxml.rb

@@ -10,6 +10,7 @@ module Uniword
   module Ooxml
     # Core OOXML packages
     autoload :DotxPackage, "#{__dir__}/ooxml/dotx_package"
+    autoload :ElementOrder, "#{__dir__}/ooxml/element_order"
     autoload :ThmxPackage, "#{__dir__}/ooxml/thmx_package"
     autoload :MhtmlPackage, "#{__dir__}/ooxml/mhtml_package"
     autoload :StylesetPackage, "#{__dir__}/ooxml/styleset_package"