fontisan 0.4.22 → 0.4.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 208fa8e2c44bdea2e800ecb13639d50e06e6914406822f6e3c92152d21414fd7
-  data.tar.gz: cdce57d3a157d5a5549b45104f93de38263697989bae6a66572907bc54b58bb0
+  metadata.gz: 556befd056a62c96c03bfaab023a7027b098df4145148415f4735db53da719ee
+  data.tar.gz: 41ddfe5df546ee2b1855644d0eddb1caed472f61e88030ad653038e536393ee6
 SHA512:
-  metadata.gz: c87e9ec10e9cadd168dda76b38ef225c1e286bc63501b75268a7cd29fcdfbef3d86abacac211052d529d153aebf1f8db29aaab7445c51a5a83e3eb091f752ab4
-  data.tar.gz: 4632d882fe8ab4897ed32722ec17efb942819ded33e2005bf51c3032384466164d2c2c09a1a8f4388f1889b5c169f42b9dc14ae5cafce72ef5680c94d2333c02
+  metadata.gz: 057fc2598f2ad7a02b1847d502f6c0363f6f23382806de361a5dd87bb2b4c99d00993f2e272ab3f2c35697dc0b8843235df05301047b1c3cdbf0e0147498282d
+  data.tar.gz: 1669c95792cc2a7731f4495e2d91e2e89b545412e213f8aff78e0dfc625a60c9f9403dc9960e4e487da1563e794fb2d3a6d5126f4ab6ef35e6ebe42e9950fd5d

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-07-08 08:05:45 UTC using RuboCop version 1.86.1.
+# on 2026-07-09 14:55:09 UTC using RuboCop version 1.86.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -12,20 +12,190 @@ Gemspec/RequiredRubyVersion:
     - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
     - 'fontisan.gemspec'
 
-# Offense count: 2116
+# Offense count: 276
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Enabled: false
+
+# Offense count: 22
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_element, with_fixed_indentation
+Layout/ArrayAlignment:
+  Exclude:
+    - 'lib/fontisan/collection/writer.rb'
+    - 'lib/fontisan/tables/cff2/index_builder.rb'
+    - 'lib/fontisan/ufo/compile/cbdt_cblc.rb'
+    - 'lib/fontisan/ufo/compile/cff.rb'
+    - 'lib/fontisan/ufo/compile/cmap.rb'
+    - 'lib/fontisan/ufo/compile/cpal.rb'
+    - 'lib/fontisan/ufo/compile/gvar.rb'
+    - 'lib/fontisan/ufo/compile/item_variation_store.rb'
+    - 'lib/fontisan/ufo/compile/sbix.rb'
+    - 'lib/fontisan/ufo/compile/stat.rb'
+    - 'lib/fontisan/ufo/info.rb'
+    - 'spec/fontisan/stitcher/glyph_signature_spec.rb'
+    - 'spec/fontisan/svg_to_glyf/contour_builder_spec.rb'
+    - 'spec/fontisan/ufo/compile/feature_writers/mkmk_spec.rb'
+    - 'spec/fontisan/ufo/compile/filters/transformations_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: IndentationWidth.
+Layout/AssignmentIndentation:
+  Exclude:
+    - 'lib/fontisan/woff2/glyf_loca_reconstruct.rb'
+
+# Offense count: 58
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Enabled: false
+
+# Offense count: 55
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Enabled: false
+
+# Offense count: 29
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ClosingParenthesisIndentation:
+  Exclude:
+    - 'benchmark/compile_benchmark.rb'
+    - 'lib/fontisan/ufo/compile/fvar.rb'
+    - 'lib/fontisan/ufo/writer.rb'
+    - 'spec/fontisan/stitcher/deduplicator_spec.rb'
+    - 'spec/fontisan/stitcher/include_codepoints_map_spec.rb'
+    - 'spec/fontisan/svg_to_glyf/affine_transform_spec.rb'
+    - 'spec/fontisan/ufo/compile/filters/propagate_anchors_spec.rb'
+    - 'spec/fontisan/ufo/compile_gvar_spec.rb'
+    - 'spec/fontisan/ufo/compile_item_variation_store_spec.rb'
+    - 'spec/fontisan/ufo/filters_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment.
+Layout/CommentIndentation:
+  Exclude:
+    - 'lib/fontisan/ufo/compile/cff.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ElseAlignment:
+  Exclude:
+    - 'lib/fontisan/commands/validate_collection_command.rb'
+    - 'lib/fontisan/converters/collection_converter.rb'
+    - 'spec/fontisan/woff2/sfnt_checksum_spec.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/fontisan/commands/validate_collection_command.rb'
+    - 'lib/fontisan/converters/collection_converter.rb'
+    - 'spec/fontisan/woff2/sfnt_checksum_spec.rb'
+
+# Offense count: 29
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
+Layout/FirstArgumentIndentation:
+  Exclude:
+    - 'benchmark/compile_benchmark.rb'
+    - 'lib/fontisan/ufo/compile/fvar.rb'
+    - 'lib/fontisan/ufo/writer.rb'
+    - 'spec/fontisan/stitcher/deduplicator_spec.rb'
+    - 'spec/fontisan/stitcher/include_codepoints_map_spec.rb'
+    - 'spec/fontisan/svg_to_glyf/affine_transform_spec.rb'
+    - 'spec/fontisan/ufo/compile/filters/propagate_anchors_spec.rb'
+    - 'spec/fontisan/ufo/compile_gvar_spec.rb'
+    - 'spec/fontisan/ufo/compile_item_variation_store_spec.rb'
+    - 'spec/fontisan/ufo/filters_spec.rb'
+
+# Offense count: 14
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: special_inside_parentheses, consistent, align_brackets
+Layout/FirstArrayElementIndentation:
+  Exclude:
+    - 'spec/fontisan/stitcher/glyph_signature_spec.rb'
+    - 'spec/fontisan/ufo/compile/feature_writers/mark_spec.rb'
+
+# Offense count: 194
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Enabled: false
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: normal, indented_internal_methods
+Layout/IndentationConsistency:
+  Exclude:
+    - 'lib/fontisan/ufo/compile/cff.rb'
+
+# Offense count: 121
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Enabled: false
+
+# Offense count: 2235
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
+# Offense count: 7
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineArrayBraceLayout:
+  Exclude:
+    - 'spec/fontisan/stitcher/glyph_signature_spec.rb'
+    - 'spec/fontisan/ufo/compile/feature_writers/mark_spec.rb'
+
+# Offense count: 29
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineMethodCallBraceLayout:
+  Exclude:
+    - 'benchmark/compile_benchmark.rb'
+    - 'lib/fontisan/ufo/compile/fvar.rb'
+    - 'lib/fontisan/ufo/writer.rb'
+    - 'spec/fontisan/stitcher/deduplicator_spec.rb'
+    - 'spec/fontisan/stitcher/include_codepoints_map_spec.rb'
+    - 'spec/fontisan/svg_to_glyf/affine_transform_spec.rb'
+    - 'spec/fontisan/ufo/compile/filters/propagate_anchors_spec.rb'
+    - 'spec/fontisan/ufo/compile_gvar_spec.rb'
+    - 'spec/fontisan/ufo/compile_item_variation_store_spec.rb'
+    - 'spec/fontisan/ufo/filters_spec.rb'
+
+# Offense count: 225
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Enabled: false
+
 # Offense count: 2
 Lint/CopDirectiveSyntax:
   Exclude:
     - 'lib/fontisan/woff2_font.rb'
     - 'spec/fontisan/variation/cache_spec.rb'
 
-# Offense count: 52
+# Offense count: 54
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
@@ -78,16 +248,12 @@ Lint/StructNewOverride:
   Exclude:
     - 'lib/fontisan/optimizers/pattern_analyzer.rb'
 
-# Offense count: 5
+# Offense count: 24
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
 # NotImplementedExceptions: NotImplementedError
 Lint/UnusedMethodArgument:
-  Exclude:
-    - 'lib/fontisan.rb'
-    - 'lib/fontisan/tables/cff2/private_dict_blend_handler.rb'
-    - 'lib/fontisan/variation/table_accessor.rb'
-    - 'lib/fontisan/woff_font.rb'
+  Enabled: false
 
 # Offense count: 5
 Lint/UselessConstantScoping:
@@ -95,12 +261,12 @@ Lint/UselessConstantScoping:
     - 'lib/fontisan/conversion_options.rb'
     - 'lib/fontisan/type1/charstrings.rb'
 
-# Offense count: 705
+# Offense count: 715
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 36
+# Offense count: 34
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
@@ -118,28 +284,28 @@ Metrics/CollectionLiteralLength:
     - 'lib/fontisan/type1/agl.rb'
     - 'lib/fontisan/type1/encodings.rb'
 
-# Offense count: 366
+# Offense count: 367
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 978
+# Offense count: 990
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 135
 
-# Offense count: 27
+# Offense count: 30
 # Configuration parameters: CountKeywordArgs.
 Metrics/ParameterLists:
   Max: 39
   MaxOptionalParameters: 4
 
-# Offense count: 278
+# Offense count: 279
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
 
-# Offense count: 208
+# Offense count: 202
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
 Naming/MethodParameterName:
@@ -182,7 +348,7 @@ Naming/VariableName:
     - 'lib/fontisan/type1/pfm_generator.rb'
     - 'lib/fontisan/type1/pfm_parser.rb'
 
-# Offense count: 120
+# Offense count: 124
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
 # AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
@@ -199,13 +365,13 @@ RSpec/AnyInstance:
     - 'spec/fontisan/variation/parallel_generator_spec.rb'
     - 'spec/integration/format_conversion_spec.rb'
 
-# Offense count: 127
+# Offense count: 128
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 38
+# Offense count: 39
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -221,7 +387,7 @@ RSpec/DescribeMethod:
     - 'spec/fontisan/type1/seac_expander_spec.rb'
     - 'spec/fontisan/type1_real_fonts_spec.rb'
 
-# Offense count: 1673
+# Offense count: 1710
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 66
@@ -273,7 +439,7 @@ RSpec/IteratedExpectation:
   Exclude:
     - 'spec/fontisan/tables/glyf_spec.rb'
 
-# Offense count: 25
+# Offense count: 27
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: have_received, receive
 RSpec/MessageSpies:
@@ -289,6 +455,7 @@ RSpec/MessageSpies:
     - 'spec/fontisan/subset/builder_spec.rb'
     - 'spec/fontisan/variation/instance_writer_spec.rb'
     - 'spec/fontisan/woff2_font_spec.rb'
+    - 'spec/support/fixture_downloader_spec.rb'
 
 # Offense count: 4
 RSpec/MultipleDescribes:
@@ -298,7 +465,7 @@ RSpec/MultipleDescribes:
     - 'spec/fontisan/utils/thread_pool_spec.rb'
     - 'spec/fontisan/variation/cache_spec.rb'
 
-# Offense count: 2105
+# Offense count: 2126
 RSpec/MultipleExpectations:
   Max: 19
 
@@ -330,7 +497,7 @@ RSpec/RepeatedExample:
     - 'spec/fontisan/metrics_calculator_spec.rb'
     - 'spec/fontisan/tables/os2_spec.rb'
 
-# Offense count: 48
+# Offense count: 51
 # Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
 # SupportedInflectors: default, active_support
 RSpec/SpecFilePathFormat:
@@ -341,10 +508,11 @@ RSpec/SpecFilePathSuffix:
   Exclude:
     - 'spec/benchmarks/subroutine_optimization_benchmark.rb'
 
-# Offense count: 1
+# Offense count: 2
 RSpec/StubbedMock:
   Exclude:
     - 'spec/fontisan/woff2_font_spec.rb'
+    - 'spec/support/fixture_downloader_spec.rb'
 
 # Offense count: 10
 RSpec/SubjectStub:
@@ -361,6 +529,16 @@ Rake/MethodDefinitionInTask:
   Exclude:
     - 'Rakefile'
 
+# Offense count: 68
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Enabled: false
+
 # Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 Style/ComparableClamp:
@@ -395,9 +573,47 @@ Style/HashLikeCase:
     - 'lib/fontisan/commands/unpack_command.rb'
     - 'lib/fontisan/models/validation_report.rb'
 
+# Offense count: 16
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/fontisan/svg/standalone_glyph.rb'
+    - 'lib/fontisan/svg_to_glyf/geometry/transform_parser.rb'
+    - 'lib/fontisan/ufo/cli.rb'
+    - 'lib/fontisan/ufo/convert.rb'
+    - 'lib/fontisan/ufo/convert/from_bin_data.rb'
+    - 'lib/fontisan/ufo/convert/to_dfont.rb'
+    - 'lib/fontisan/ufo/convert/to_otc.rb'
+    - 'lib/fontisan/ufo/convert/to_postscript.rb'
+    - 'lib/fontisan/ufo/convert/to_woff.rb'
+    - 'lib/fontisan/ufo/convert/to_woff2.rb'
+    - 'lib/fontisan/ufo/plist.rb'
+    - 'lib/fontisan/woff2/collection_decoder.rb'
+    - 'lib/fontisan/woff2/collection_encoder.rb'
+    - 'spec/support/fixture_downloader.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineTernaryOperator:
+  Exclude:
+    - 'lib/fontisan/commands/validate_collection_command.rb'
+    - 'lib/fontisan/converters/collection_converter.rb'
+    - 'spec/fontisan/woff2/sfnt_checksum_spec.rb'
+
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/fontisan/conversion_options.rb'
+
+# Offense count: 22
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArguments:
+  Exclude:
+    - 'benchmark/compile_benchmark.rb'
+    - 'spec/fontisan/ufo/compile/filters/propagate_anchors_spec.rb'
+    - 'spec/fontisan/ufo/compile_gvar_spec.rb'
+    - 'spec/fontisan/ufo/filters_spec.rb'

data/Gemfile

@@ -10,6 +10,12 @@ gem "benchmark"
 gem "bigdecimal"
 gem "canon", "~> 0.1.3"
 gem "get_process_mem", "~> 0.2"
+# Octokit provides authenticated GitHub API access for the test-only
+# fixture downloader (spec/support/fixture_downloader.rb). CI sets
+# GITHUB_TOKEN, the downloader auto-detects it and routes GitHub URLs
+# through Octokit to lift the 60/hr anonymous rate limit. NOT in
+# fontisan.gemspec — production installs never pull this in.
+gem "octokit", group: :test
 gem "openssl", "~> 3.0"
 gem "rake"
 gem "rspec"

data/Rakefile

@@ -10,21 +10,24 @@ RuboCop::RakeTask.new
 
 # rubocop:disable Metrics/BlockLength
 namespace :fixtures do
-  # Load centralized fixture configuration
+  # Load centralized fixture configuration and the test-only downloader.
+  # The downloader lives under spec/support (not lib/) because it is
+  # purely test infrastructure — fontisan-the-gem never downloads
+  # fonts at runtime.
   require_relative "spec/support/fixture_fonts"
-  require "fontisan/tasks"
+  require_relative "spec/support/fixture_downloader"
 
   # Helper method to download a single file
   def download_single_file(name, url, target_path)
     puts "[fixtures:download] Downloading #{name}..."
 
-    Fontisan::Tasks::FixtureDownloader.new(
+    FixtureFonts::Downloader.new(
       url: url,
       destination: target_path,
     ).call
 
     puts "[fixtures:download] #{name} downloaded successfully"
-  rescue Fontisan::Tasks::FixtureDownloader::Error => e
+  rescue FixtureFonts::Downloader::Error => e
     warn "[fixtures:download] #{name} failed after retries: #{e.message}"
     raise
   end
@@ -41,7 +44,7 @@ namespace :fixtures do
                           "fontisan_#{name}_#{Process.pid}_#{rand(10000)}.zip")
 
     begin
-      Fontisan::Tasks::FixtureDownloader.new(
+      FixtureFonts::Downloader.new(
         url: url,
         destination: temp_path,
       ).call
@@ -89,7 +92,7 @@ namespace :fixtures do
     end
 
     puts "[fixtures:download] #{name} downloaded successfully"
-  rescue Fontisan::Tasks::FixtureDownloader::Error => e
+  rescue FixtureFonts::Downloader::Error => e
     warn "[fixtures:download] #{name} failed after retries: #{e.message}"
     raise
   rescue LoadError => e

data/benchmark/compile_benchmark.rb

@@ -24,10 +24,17 @@ module FontisanBench
       g.width = 500
       g.add_unicode(0xE000 + i) if i < 0x1000
       g.add_contour(Fontisan::Ufo::Contour.new([
-                                                 Fontisan::Ufo::Point.new(x: 0, y: 0, type: "line"),
-                                                 Fontisan::Ufo::Point.new(x: 100, y: 0, type: "line"),
-                                                 Fontisan::Ufo::Point.new(x: 100, y: 100, type: "offcurve"),
-                                                 Fontisan::Ufo::Point.new(x: 50, y: 150, type: "curve"),
+                                                 Fontisan::Ufo::Point.new(x: 0,
+                                                                          y: 0, type: "line"),
+                                                 Fontisan::Ufo::Point.new(
+                                                   x: 100, y: 0, type: "line",
+                                                 ),
+                                                 Fontisan::Ufo::Point.new(
+                                                   x: 100, y: 100, type: "offcurve",
+                                                 ),
+                                                 Fontisan::Ufo::Point.new(
+                                                   x: 50, y: 150, type: "curve",
+                                                 ),
                                                ]))
       font.glyphs["g#{i}"] = g
     end
@@ -38,7 +45,8 @@ module FontisanBench
     start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     yield
     elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
-    puts format("%-40<label>s %8.<elapsed>.2f ms", label: label, elapsed: elapsed * 1000)
+    puts format("%-40<label>s %8.<elapsed>.2f ms", label: label,
+                                                   elapsed: elapsed * 1000)
     elapsed
   end
 end

data/docs/.vitepress/config.ts

@@ -322,6 +322,7 @@ export default defineConfig({
             { text: "ConversionOptions", link: "/api/conversion-options" },
             { text: "SfntFont", link: "/api/sfnt-font" },
             { text: "Type1Font", link: "/api/type1-font" },
+            { text: "Ufo::Layer", link: "/api/layer" },
           ],
         },
         {

data/docs/STITCHER_GUIDE.adoc

@@ -364,12 +364,56 @@ stitcher.write_to("out.ttf", format: :ttf, subfont: :main)
 # → out.ttf has glyf + CBDT + CBLC, emoji renders correctly
 ----
 
-Constraints:
+=== Outline-first cmap priority
+
+When a codepoint is covered by BOTH an outline donor and the CBDT
+donor, the cmap maps it to the outline glyph — never to the CBDT
+placeholder. The Cmap compiler follows first-wins semantics, and
+`GlyphCopier` runs before `CbdtPropagator` so the outline GID is
+registered first. This was the fix for the Emoticons cmap-loss bug
+where shared codepoints silently dropped out of the cmap.
+
+=== Placeholder name deconfliction
+
+CBDT placeholders are named after the source's glyph IDs
+(`"gid1"`, `"gid2"`, …), which is the SAME naming scheme
+`Source#extract_truetype_glyph` uses for outline glyphs from TTF
+donors. Without protection, a placeholder at `"gid110"` would
+silently overwrite an outline glyph at `"gid110"` from a different
+donor via `Layer#add` — the original cmap-loss vector for the
+Essenfont CJK Ext G regression.
+
+The Stitcher resolves this with two pieces:
+
+* `Ufo::Layer#add` RAISES `Ufo::GlyphExistsError` on name conflict.
+  Silent overwrites are no longer possible. Callers that want to
+  replace an existing glyph use the explicit `Ufo::Layer#put`.
+* `Stitcher::UniqueGlyphName.in(target, base)` allocates a
+  non-colliding name (`"gid110"`, then `"gid110.1"`, `"gid110.2"`,
+  …). `GlyphCopier` and `CbdtPropagator` both call it before every
+  `Layer#add`, so each glyph lands at its own GID slot without
+  touching the others.
+
+=== Limitations
 
 * Only ONE CBDT source per Stitcher. Multiple CBDT sources raise
   `Fontisan::MultipleCbdtSourcesError`.
-* The CBDT source is processed first (GIDs 0..N-1) so the CBLC's GID
-  references remain valid in the output.
+* **GID stability for overlapping codepoint ranges.** The raw-bytes
+  CBDT/CBLC propagation (`CbdtPropagator#propagate_tables_into`)
+  copies the source's CBLC verbatim. CBLC indexes glyphs by SOURCE
+  GID. After placeholder renaming (`"gid110"` → `"gid110.1"`), the
+  compiled GID no longer matches the source GID, so CBLC's source-
+  GID-indexed bitmaps can dangle. This is masked in the typical
+  Essenfont case (CBDT donor NotoColorEmoji and outline donors
+  cover disjoint codepoint ranges) but would produce wrong bitmaps
+  for any stitch where CBDT and outline sources share codepoint
+  ranges. A proper fix requires a CBLC rebuild pass that walks the
+  compiled cmap to remap source GIDs to compiled GIDs — tracked as
+  follow-up.
+* **Collection-mode single-face coverage.** Each face is compiled
+  independently; `CbdtPropagator` currently requires at least one
+  outline codepoint per face. Collection-mode coverage of the
+  outline-first cmap-priority invariant is tracked as follow-up.
 
 == CLI
 

data/docs/api/layer.md

@@ -0,0 +1,89 @@
+---
+title: Ufo::Layer
+---
+
+# `Ufo::Layer`
+
+A single layer in a UFO source. A `Layer` holds a set of glyphs keyed by name. The default layer is `public.default` per UFO 3.
+
+```ruby
+layer = Fontisan::Ufo::Layer.new                       # => "public.default"
+layer.add(Fontisan::Ufo::Glyph.new(name: "A"))
+layer["A"]                                             # => the glyph
+layer.size                                             # => 1
+```
+
+## Naming contract
+
+Glyph names are the layer's primary key. Two distinct glyphs with the same name cannot coexist — adding the second would silently destroy the first, a class of bug that has historically cost real data (e.g. the CJK Ext G cmap loss when CBDT placeholders collided with outline glyphs sharing `"gid{N}"` names).
+
+To make that contract unbreakable, the API exposes two methods with named semantics:
+
+| Method | Behavior on conflict |
+|--------|----------------------|
+| `Layer#add(glyph)` | **Raises** `Ufo::GlyphExistsError` (the safe default) |
+| `Layer#put(glyph)` | Overwrites the existing glyph (explicit replace) |
+
+Callers that need auto-renaming — insert without giving up on a collision — call `Stitcher::UniqueGlyphName.in(target, base)` first to allocate a free name, then `Layer#add` the glyph under that name.
+
+## API
+
+### `Layer.new(name = "public.default")`
+
+Initialize an empty layer.
+
+### `#add(glyph) -> Glyph`
+
+Insert `glyph`. Raises `Ufo::GlyphExistsError` if a glyph with the same name is already present.
+
+```ruby
+layer = Fontisan::Ufo::Layer.new
+layer.add(Fontisan::Ufo::Glyph.new(name: "A"))
+
+layer.add(Fontisan::Ufo::Glyph.new(name: "A"))
+# => raises Fontisan::Ufo::GlyphExistsError: a glyph named "A" already exists
+```
+
+The original glyph is preserved when the second `add` raises — the layer is never partially mutated.
+
+### `#put(glyph) -> Glyph`
+
+Insert `glyph`, replacing any existing glyph with the same name. Use this when the caller has positively decided the previous glyph (if any) should be discarded.
+
+```ruby
+layer.put(Fontisan::Ufo::Glyph.new(name: "A"))  # overwrites the prior "A"
+```
+
+### `#[](glyph_name) -> Glyph, nil`
+
+Look up a glyph by name.
+
+### `#each { |glyph| ... }`
+
+Iterate over glyphs (no ordering guarantee).
+
+### `#size -> Integer`
+
+Number of glyphs in the layer.
+
+## `Ufo::GlyphExistsError`
+
+Raised by `Layer#add` on a name conflict. Carries the colliding name so callers can branch programmatically:
+
+```ruby
+begin
+  layer.add(glyph)
+rescue Fontisan::Ufo::GlyphExistsError => e
+  puts "name #{e.name.inspect} already taken"
+  # Decide: layer.put(glyph) to overwrite, or
+  # unique = Fontisan::Stitcher::UniqueGlyphName.in(target, e.name)
+  # layer.add(glyph.dup_as(name: unique))
+end
+```
+
+The error class is a sibling of `Layer` (not nested inside it) so the namespace stays flat — both `Ufo::Layer` and `Ufo::GlyphExistsError` live directly under `Fontisan::Ufo`.
+
+## See also
+
+- `docs/STITCHER_GUIDE.adoc` — `UniqueGlyphName`, `GlyphCopier`, and `CbdtPropagator` all build on the Layer naming contract.
+- `docs/UFO_COMPILATION.adoc` — how layers feed the TTF/OTF/CFF2 compilers.