fontisan 0.4.23 → 0.4.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7e00355898ff37e38b4948f9a607bf95b96b73df17225c81ebe0b6f6b757b1d
-  data.tar.gz: 9009d6fb96c8168a098236d7b80355749d6c65463376119695ab2a65c20de01d
+  metadata.gz: 4f8c0752461168f5fa647b8a581455a1daa4ed17f7649b1b28cf3850b1453748
+  data.tar.gz: 99e14f77bfdb9cf1303b51d9f236a82c2cfbf284885d56fbe79be56fb338a237
 SHA512:
-  metadata.gz: 0c82bc6f0d6a871e84d85e4ac6bd51260a39f2b1d373b3055801354c89d99eda1ce3f78ba62ce640e5193eededeba9c8f5101146378124b5d5ac8e5c52bb60c0
-  data.tar.gz: 3e957b040dd2660ce7b8ddea3d4592cfef37ad8d434dd5e43d1be4417459992150fcd414f7547ead7f89a9ad8fd4ea8e01a847eb57ef352a70335e691cb386d6
+  metadata.gz: 15960f305c5c9f6cfef40e55adf0b5eb95a54f51aa902dae77d2db6c7735b821d7b3bb320582eebed3141a3a5d72cf396e51a3a7845a9222f283c6ca4e9a0e90
+  data.tar.gz: 70d21559793f7c48965c8bf2601788dccf6f63c7c66db70cd49a3822b280664d30a333db717b61ad7348fbb831a31ab158ef22dc117f8e683321da131b52dad5

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,21 +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'
-    # Subset strategies share a uniform (context:, tag:, table:) interface
-    # so the dispatcher can call every registered class the same way. Not
-    # every strategy reads every arg; the interface contract justifies the
-    # unused warnings here.
-    - 'lib/fontisan/subset/table_strategy/**/*'
+  Enabled: false
 
 # Offense count: 5
 Lint/UselessConstantScoping:
@@ -100,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:
@@ -123,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:
@@ -187,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
@@ -204,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
@@ -226,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
@@ -278,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:
@@ -294,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:
@@ -303,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
 
@@ -335,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:
@@ -346,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:
@@ -366,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:
@@ -400,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/TODO.improvements/01-cbdt-cblc-gid-stable-propagation.md

@@ -0,0 +1,73 @@
+# 01 — CBDT/CBLC GID-stable propagation
+
+## Priority
+P0
+
+## Problem
+
+`Stitcher::CbdtPropagator#propagate_tables_into` (`lib/fontisan/stitcher/cbdt_propagator.rb:147`) copies CBDT/CBLC bytes raw from the CBDT source into the compiled font. CBLC indexes glyphs by **source GID**. But the Stitcher's compile order is:
+
+1. `inject_notdef`      → compiled GID 0
+2. `copy_outlines`      → compiled GIDs 1..N (outline donor glyphs)
+3. `add_placeholder_glyphs` → compiled GIDs N+1..M (CBDT placeholders, often renamed to `"gid{N}.1"` to avoid name collisions per PR #108)
+
+So the CBDT source's GID 110 may end up at compiled GID 4027+ — but the raw-bytes CBLC still says "GID 110 → bitmap for source GID 110". The bitmap data dangles, pointing at whatever outline glyph happens to be at compiled GID 110.
+
+This is masked in the cited Essenfont use case because FSung-3 (Ext G outlines) and NotoColorEmoji (emoji bitmaps) cover disjoint codepoint ranges. But for any stitch where CBDT and outline donors cover overlapping codepoint ranges (e.g. assembling a combined Latin+emoji font from a single source that has both glyf and CBDT), the bitmap-to-glyph mapping is wrong.
+
+Documented as a known limitation in `docs/STITCHER_GUIDE.adoc` (added in PR #110).
+
+## Goal
+
+After compile, `propagate_tables_into` rebuilds the CBLC by:
+1. Walking the compiled font's cmap to find each compiled GID for every CBDT-covered codepoint.
+2. Mapping source GID → compiled GID via the Stitcher's `GlyphMapping`.
+3. Building a new CBLC whose `BitmapSize.startGlyphIndex`/`endGlyphIndex` and IndexSubTableArray entries reference compiled GIDs.
+4. Building a new CBDT that lays out bitmap blocks in compiled-GID order so each block matches its CBLC offset.
+
+The result: any stitch — overlapping codepoint ranges or not — produces a font where CBLC's GID references line up with the compiled GIDs that actually have the right bitmaps.
+
+## Approach
+
+Reuse the CBDT/CBLC BinData models from PR #106:
+- `Tables::Cblc`, `Tables::CblcBitmapSize`, `Tables::CblcIndexSubTableArrayEntry`, `Tables::CblcIndexSubTable`
+- `Subset::TableStrategy::ColorBitmapSubsetter` and its plan classes — already do the offset-remap math for the subsetter; same algorithm shape, different mapping source
+
+New collaborator: `Stitcher::CbdtReindexer`. Sits between compile and table propagation:
+
+```
+compile TTF
+  ↓
+CbdtReindexer.reindex(source_cblc, source_cbdt, glyph_mapping) → new (CBLC, CBDT) bytes
+  ↓
+FontWriter.write_to_file(tables.merge("CBLC" => new_cblc, "CBDT" => new_cbdt))
+```
+
+The reindexer is stateless given inputs — testable in isolation.
+
+Update `propagate_tables_into` to call the reindexer instead of raw-bytes copy.
+
+Update `docs/STITCHER_GUIDE.adoc` to remove the "known limitation" note.
+
+## Out of scope
+
+- Handling IndexSubTable format 4 (bit-packed offsets) — already unsupported in the subsetter; same gap.
+- Multi-strike CBLC where each strike has a different glyph range — covered (reindexer iterates strikes).
+- Subsetting the source CBDT before stitching — separate concern (the subsetter already does this for `Subset::Builder`).
+
+## Effort
+
+~1 day.
+
+## Dependencies
+
+None. Unblocks TODO 02.
+
+## Acceptance criteria
+
+- New spec `spec/fontisan/stitcher/cbdt_reindexer_spec.rb` covers:
+  - Disjoint-range stitch: CBLC's compiled GID references line up.
+  - Overlapping-range stitch: CBDT placeholder at compiled GID N gets the bitmap originally at source GID M (mapping via GlyphMapping).
+  - Multi-strike CBLC: every strike's bitmap data lands at the right compiled GID.
+- Existing `spec/fontisan/stitcher/outline_priority_spec.rb` collection-mode test (currently skipped) is unblocked and passes.
+- The "GID-stability limitation" section in `docs/STITCHER_GUIDE.adoc` is removed.

data/TODO.improvements/02-collection-outline-priority.md

@@ -0,0 +1,48 @@
+# 02 — Collection-mode outline-priority regression
+
+## Priority
+P0
+
+## Problem
+
+`spec/fontisan/stitcher/outline_priority_spec.rb:160` ("write_collection preserves outline-first cmap priority across faces") was unblocked for single-face mode in PR #108 but the **collection variant** is still skipped:
+
+```ruby
+skip "Stitcher currently raises on a CBDT source without at least one outline codepoint in each face — " \
+     "collection-mode coverage needs CbdtPropagator hardening tracked separately."
+```
+
+When the Stitcher builds a TTC/OTC, each face compiles independently. The CBDT source is global — its placeholders need to land in EVERY face that covers any of its codepoints. The current `CbdtPropagator#add_placeholder_glyphs` raises if a face has no outline glyph from any other donor (the CBDT source alone can't seed a face).
+
+## Goal
+
+The skipped test passes. A CBDT source can be stitched into a collection where some faces cover only CBDT codepoints (no outline donor coverage). Each face gets the CBDT/CBLC tables propagated.
+
+## Approach
+
+Two pieces:
+
+1. **`CbdtPropagator#add_placeholder_glyphs`** — relax the "must have an outline codepoint" precondition. Allow a face to be seeded with just CBDT placeholders (plus the `.notdef` that's always required).
+
+2. **`CbdtPropagator#propagate_tables_into`** — for collections, run per-face rather than once. The collection writer already iterates faces; this is a matter of plumbing.
+
+This depends on TODO 01 (GID-stable propagation) because the collection case multiplies the GID-mapping complexity — each face has its own compiled GID space.
+
+## Out of scope
+
+- Multi-CBDT-source support (the `MultipleCbdtSourcesError` guard remains).
+- Cross-face glyph deduplication (already handled by the existing dedup pass).
+
+## Effort
+
+~2 hours once TODO 01 lands.
+
+## Dependencies
+
+- TODO 01 (CBDT/CBLC GID-stable propagation).
+
+## Acceptance criteria
+
+- The skipped test at `outline_priority_spec.rb:160` is unskipped and passes.
+- A new test covers the "CBDT-only face" case (a face with no outline donor coverage, only CBDT placeholders).
+- `MultipleCbdtSourcesError` is still raised when two CBDT sources are declared.