fontisan 0.4.22 → 0.4.24

data/docs/cli/subset.md

@@ -18,8 +18,23 @@ fontisan subset <font> [options]
 |--------|-------------|
 | `--chars TEXT` | Characters to include |
 | `--file FILE` | File containing characters |
+| `--unicodes RANGE` | Unicode ranges (`"U+0000-007F"`) |
+| `--glyphs LIST` | Glyph names/IDs |
 | `--output FILE` | Output file path |
-| `--format FORMAT` | Output format |
+| `--format FORMAT` | Output format (`ttf`, `woff`, `woff2`, …) |
+| `--profile PROFILE` | Subsetting profile (default: `pdf`) |
+| `--retain-gids` | Preserve original glyph IDs |
+
+## Profiles
+
+| Profile | Tables included | Use case |
+|---------|-----------------|----------|
+| `pdf` | core + glyf/loca | PDF embedding (smallest) |
+| `web` | core + glyf/loca + GSUB/GPOS + **CBDT/CBLC** | Web fonts that retain color-emoji bitmaps |
+| `minimal` | core only | Smallest valid font |
+| `full` | every standard table | Lossless re-export |
+
+The `web` profile is the one to reach for when the subset must still render color emoji in a browser: it preserves the CBDT (bitmap data) and CBLC (bitmap location) tables, and the paired subsetter rewrites them to keep only the bitmaps for the retained glyphs.
 
 ## Examples
 
@@ -27,13 +42,17 @@ fontisan subset <font> [options]
 # Subset to specific characters
 fontisan subset font.ttf --chars "ABCDEF" --output subset.ttf
 
-# Subset from file
-fontisan subset font.ttf --file chars.txt --output subset.ttf
+# Web subset that retains color-emoji bitmaps
+fontisan subset NotoColorEmoji.ttf \
+  --chars "😀😁😂🤣😊" \
+  --profile web \
+  --format woff2 \
+  --output emoji.woff2
 
-# Subset and convert format
-fontisan subset font.ttf --chars "Hello" --format woff2
+# PDF embedding profile (drops CBDT/CBLC, smaller output)
+fontisan subset font.ttf --chars "ABC" --profile pdf --output pdf-subset.ttf
 ```
 
 ## Detailed Documentation
 
-For comprehensive documentation including unicode ranges and advanced subsetting, see the [subset command guide](/guide/cli/subset).
+For comprehensive documentation including unicode ranges, profile selection, and CBDT/CBLC behavior, see the [subset command guide](/guide/cli/subset).

data/docs/guide/cli/subset.md

@@ -28,6 +28,7 @@ fontisan subset FONT [options]
 | `--glyphs LIST` | Glyph names/IDs |
 | `--output PATH` | Output file |
 | `--output-format FORMAT` | Output format |
+| `--profile PROFILE` | Subsetting profile (`pdf`, `web`, `minimal`, `full`; default `pdf`) |
 | `--retain-gids` | Retain glyph IDs |
 
 ## Examples
@@ -86,6 +87,36 @@ fontisan subset font.ttf --chars "ABC" --output-format woff2 --output subset.wof
 
 ## Subsetting Strategies
 
+### Profile selection
+
+The `--profile` option controls which font tables the subset retains. The right choice depends on what the subset is for:
+
+| Profile | When to use | Notable tables dropped |
+|---------|-------------|------------------------|
+| `pdf` (default) | PDF embedding, smallest valid output | GSUB, GPOS, CBDT, CBLC |
+| `web` | Browser/web font, **retains color-emoji bitmaps** | nothing that browsers need |
+| `minimal` | Absolute smallest core that still renders | glyf/loca, CBDT/CBLC, GSUB/GPOS |
+| `full` | Lossless re-export | (none) |
+
+```bash
+# Web subset that keeps color-emoji bitmaps so 😀 renders in color
+fontisan subset NotoColorEmoji.ttf \
+  --chars "😀😁😂🤣😊" \
+  --profile web \
+  --output-format woff2 \
+  --output emoji.woff2
+
+# PDF embedding — drops color bitmaps for size
+fontisan subset NotoColorEmoji.ttf \
+  --chars "😀" \
+  --profile pdf \
+  --output emoji-pdf.ttf
+```
+
+#### Web profile and CBDT/CBLC
+
+The `web` profile is the only built-in profile that retains CBDT (Color Bitmap Data) and CBLC (Color Bitmap Location) tables. The subsetter walks CBLC to find each retained glyph's bitmap block, rewrites CBDT to keep only those blocks, and rebuilds CBLC's IndexSubTableArray to point at the new offsets. Glyph IDs are remapped through the subset's `GlyphMapping`, so the output CBLC references subset GIDs, not source GIDs.
+
 ### Web Font Optimization
 
 ```bash

data/docs/guide/color-fonts/bitmaps.md

@@ -144,6 +144,23 @@ fontisan convert bitmap-font.ttf --to ttf --output bitmap-font.ttf
 fontisan convert bitmap-font.ttf --to ttf --no-bitmaps --output outline-only.ttf
 ```
 
+### Subsetting color-emoji fonts
+
+The `web` subsetting profile retains CBDT and CBLC tables and rewrites them to keep only the bitmaps for retained glyphs. Use it when subsetting a color-emoji source for browser delivery:
+
+```bash
+# Keep only 😀 + 😁 bitmaps; output WOFF2 for web
+fontisan subset NotoColorEmoji.ttf \
+  --chars "😀😁" \
+  --profile web \
+  --output-format woff2 \
+  --output emoji-subset.woff2
+```
+
+Other profiles (`pdf`, `minimal`, `full`) drop CBDT/CBLC — pick them when the subset doesn't need color-emoji rendering (e.g. PDF embedding where the subsetter is just selecting glyphs for outlines).
+
+See the [subset CLI docs](/cli/subset) and `docs/STITCHER_GUIDE.adoc` (CBDT/CBLC passthrough section) for the full story, including the GID-stability caveat when CBDT and outline donors cover overlapping codepoint ranges in stitch mode.
+
 ## Comparison
 
 | Feature | sbix | CBDT/CBLC |

data/lib/fontisan/cli.rb

@@ -360,7 +360,8 @@ module Fontisan
 
       # Handle --show-options
       if options[:show_options]
-        show_recommended_options(source_format, options[:to].is_a?(Array) ? options[:to].first : options[:to])
+        show_recommended_options(source_format,
+                                 options[:to].is_a?(Array) ? options[:to].first : options[:to])
         return
       end
 

data/lib/fontisan/collection/writer.rb

@@ -95,7 +95,8 @@ module Fontisan
       #
       # @return [String] TTC header binary
       def write_ttc_header
-        [TTC_TAG, VERSION_1_0_MAJOR, VERSION_1_0_MINOR, @fonts.size].pack("a4nnN")
+        [TTC_TAG, VERSION_1_0_MAJOR, VERSION_1_0_MINOR,
+         @fonts.size].pack("a4nnN")
       end
 
       # Write offset table

data/lib/fontisan/commands/validate_collection_command.rb

@@ -81,7 +81,13 @@ module Fontisan
         Check.new(
           name: :glyph_cap,
           passed: over.empty?,
-          message: over.empty? ? nil : "faces over cap: #{over.map { |s| "##{s.index}=#{s.glyph_count}" }.join(', ')}",
+          message: if over.empty?
+                     nil
+                   else
+                     "faces over cap: #{over.map do |s|
+                       "##{s.index}=#{s.glyph_count}"
+                     end.join(', ')}"
+                   end,
         )
       end
 

data/lib/fontisan/commands.rb

@@ -21,7 +21,8 @@ module Fontisan
     autoload :TablesCommand, "fontisan/commands/tables_command"
     autoload :UnicodeCommand, "fontisan/commands/unicode_command"
     autoload :UnpackCommand, "fontisan/commands/unpack_command"
-    autoload :ValidateCollectionCommand, "fontisan/commands/validate_collection_command"
+    autoload :ValidateCollectionCommand,
+             "fontisan/commands/validate_collection_command"
     autoload :ValidateCommand, "fontisan/commands/validate_command"
     autoload :VariableCommand, "fontisan/commands/variable_command"
   end

data/lib/fontisan/config/subset_profiles.yml

@@ -55,6 +55,8 @@ web:
     - glyf
     - GSUB
     - GPOS
+    - CBDT
+    - CBLC
 
 # Minimal Profile: Absolute minimum tables for font rendering
 minimal:

data/lib/fontisan/converters/collection_converter.rb

@@ -173,7 +173,12 @@ module Fontisan
             io.read(8) # signature + flavor
             io.rewind
             flavor = File.binread(path, 4, 4)&.unpack1("N")
-            flavor == Woff2::CollectionDecoder::TTC_FLAVOR ? :woff2_collection : (raise Error, "Not a WOFF2 collection: #{path}")
+            if flavor == Woff2::CollectionDecoder::TTC_FLAVOR
+              :woff2_collection
+            else
+              (raise Error,
+                     "Not a WOFF2 collection: #{path}")
+            end
           elsif Parsers::DfontParser.dfont?(io)
             :dfont
           else

data/lib/fontisan/converters/svg_generator.rb

@@ -192,7 +192,9 @@ palette_index: 0)
       def build_glyph_to_codepoints(cmap)
         return {} unless cmap
 
-        cmap.unicode_mappings.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(cp, gid), h|
+        cmap.unicode_mappings.each_with_object(Hash.new do |h, k|
+          h[k] = []
+        end) do |(cp, gid), h|
           h[gid] << cp
         end
       rescue StandardError => e

data/lib/fontisan/stitcher/cbdt_propagator.rb

@@ -60,6 +60,19 @@ module Fontisan
       # Outline data is intentionally absent — the bitmap lives in
       # the CBDT table that #propagate_tables_into will copy later.
       #
+      # == Why placeholders are name-deconflicted
+      #
+      # Placeholders are named after the CBDT source's gid ("gid{N}").
+      # Outline donors compiled earlier into the same target use the
+      # SAME naming scheme (see Source#extract_truetype_glyph), so a
+      # CBDT placeholder at "gid110" would collide with an outline
+      # glyph at "gid110" from a different donor. Layer#add raises on
+      # conflict (it never silently overwrites — that path previously
+      # erased real outline glyphs and dropped their cmap entries,
+      # causing the CJK Ext G loss in Essenfont-Regular.ttc). We
+      # allocate a unique name via UniqueGlyphName so each placeholder
+      # lands at its own GID slot without touching the outlines.
+      #
       # Glyphs are NOT registered with the deduplicator: each CBDT
       # glyph is unique to its source, and deduplication would
       # incorrectly collapse distinct bitmaps.
@@ -69,7 +82,10 @@ module Fontisan
       def add_placeholder_glyphs(source, target)
         ufo = source.font.is_a?(Ufo::Font) ? source.font : nil
         if ufo
-          ufo.glyphs.each_value { |g| target.layers.default_layer.add(clone_glyph(g, name: g.name)) }
+          ufo.glyphs.each_value do |g|
+            name = UniqueGlyphName.in(target, g.name)
+            target.layers.default_layer.add(GlyphCloner.clone(g, name: name))
+          end
           return
         end
 
@@ -82,7 +98,8 @@ module Fontisan
         mappings.each { |cp, gid| gid_cps[gid] << cp }
 
         num_glyphs.times do |gid|
-          name = gid.zero? ? ".notdef" : "gid#{gid}"
+          base_name = gid.zero? ? ".notdef" : "gid#{gid}"
+          name = UniqueGlyphName.in(target, base_name)
           glyph = Ufo::Glyph.new(name: name)
           glyph.width = 0
           gid_cps[gid].each { |cp| glyph.add_unicode(cp) }
@@ -100,6 +117,31 @@ module Fontisan
       #
       # No-op when called with a non-CBDT source or nil.
       #
+      # == Limitation: GID stability
+      #
+      # The propagation copies CBDT/CBLC bytes verbatim. CBLC indexes
+      # glyphs by SOURCE GID — the GIDs of the CBDT donor. The compiled
+      # font's GIDs may differ because:
+      #
+      #   1. +add_placeholder_glyphs+ renames CBDT placeholders via
+      #      UniqueGlyphName when their default "gid{N}" name collides
+      #      with outline glyphs sharing the same donor-gid scheme
+      #      (see Layer's naming contract).
+      #   2. The compiler assigns GIDs in target-namespace order, which
+      #      is not the same as source-GID order once renaming happens.
+      #
+      # The bitmaps line up correctly only when the CBDT source and
+      # every outline source cover disjoint codepoint ranges (the
+      # Essenfont TTC case: emoji vs CJK Ext G). When ranges overlap,
+      # CBLC's source-GID-indexed bitmaps may point at the wrong
+      # compiled glyphs and the colour rendering for affected
+      # codepoints will fall back to outlines.
+      #
+      # A proper fix requires a CBLC rebuild pass: walk the compiled
+      # font's cmap to find the new GID for every CBDT-covered source
+      # glyph, then rewrite CBLC's IndexSubTableArray + IndexSubTable
+      # offsets to match. Tracked as a follow-up.
+      #
       # @param source [Stitcher::Source, nil] the CBDT source
       # @param path [String] compiled font file to rewrite
       def propagate_tables_into(source, path)
@@ -126,26 +168,6 @@ module Fontisan
         sfnt = tables.key?("CFF ") || tables.key?("CFF2") ? 0x4F54544F : 0x00010000
         FontWriter.write_to_file(tables, path, sfnt_version: sfnt)
       end
-
-      private
-
-      def clone_glyph(original, name:)
-        copy = Ufo::Glyph.new(name: name)
-        copy.width = original.width
-        copy.height = original.height
-        original.contours.each { |c| copy.add_contour(clone_contour(c)) }
-        original.components.each { |c| copy.add_component(c) }
-        original.anchors.each { |a| copy.add_anchor(a) }
-        original.guidelines.each { |g| copy.add_guideline(g) }
-        copy
-      end
-
-      def clone_contour(original)
-        points = original.points.map do |p|
-          Ufo::Point.new(x: p.x, y: p.y, type: p.type, smooth: p.smooth)
-        end
-        Ufo::Contour.new(points)
-      end
     end
   end
 end

data/lib/fontisan/stitcher/collection_result.rb

@@ -9,7 +9,8 @@ module Fontisan
 
     # Return value of {Stitcher#write_collection}. Carries the output path,
     # total bytes, and one {SubfontStats} per declared subfont.
-    CollectionResult = Struct.new(:path, :bytes, :subfonts, keyword_init: true) do
+    CollectionResult = Struct.new(:path, :bytes, :subfonts,
+                                  keyword_init: true) do
       def face_count
         subfonts.size
       end

data/lib/fontisan/stitcher/glyph_cloner.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    # Deep-clone helper for UFO glyphs. Stateless — every call returns
+    # a fresh +Ufo::Glyph+ with copied contours, components, anchors,
+    # and guidelines plus the original's width/height.
+    #
+    # Extracted as a collaborator so +GlyphCopier+ and +CbdtPropagator+
+    # share one implementation of the clone algorithm. Both previously
+    # defined identical +clone_glyph+ / +clone_contour+ private methods
+    # — a DRY violation that risked drifting apart as the glyph model
+    # gained fields.
+    module GlyphCloner
+      # @param original [Ufo::Glyph] glyph to copy
+      # @param name [String, nil] name for the copy; defaults to the
+      #   original's name (used by callers that have already allocated
+      #   a unique name via +UniqueGlyphName+).
+      # @return [Ufo::Glyph] a fresh glyph with the original's geometry
+      #   and metrics, sharing no mutable state with it.
+      def self.clone(original, name: nil)
+        copy = Ufo::Glyph.new(name: name || original.name)
+        copy.width = original.width
+        copy.height = original.height
+        original.contours.each { |c| copy.add_contour(clone_contour(c)) }
+        original.components.each { |c| copy.add_component(c) }
+        original.anchors.each { |a| copy.add_anchor(a) }
+        original.guidelines.each { |g| copy.add_guideline(g) }
+        copy
+      end
+
+      def self.clone_contour(original)
+        points = original.points.map do |p|
+          Ufo::Point.new(x: p.x, y: p.y, type: p.type, smooth: p.smooth)
+        end
+        Ufo::Contour.new(points)
+      end
+      private_class_method :clone_contour
+    end
+  end
+end

data/lib/fontisan/stitcher/glyph_copier.rb

@@ -1,4 +1,4 @@
-# frozen_string: true
+# frozen_string_literal: true
 
 module Fontisan
   class Stitcher
@@ -74,7 +74,7 @@ module Fontisan
           if canonical && target.glyphs.key?(canonical)
             add_extra_unicode(target, canonical, binding[:codepoint])
           else
-            name = unique_target_name(target, glyph.name)
+            name = UniqueGlyphName.in(target, glyph.name)
             copy_glyph_into(target, name: name, source: binding[:source],
                                     donor_gid: binding[:donor_gid],
                                     codepoint: binding[:codepoint])
@@ -89,11 +89,12 @@ module Fontisan
         bindings.sort_by { |b| [b[:codepoint] || Float::INFINITY, b[:donor_gid]] }
       end
 
-      def copy_glyph_into(target_font, name:, source:, donor_gid:, codepoint: nil)
+      def copy_glyph_into(target_font, name:, source:, donor_gid:,
+codepoint: nil)
         original = source.glyph_for_gid(donor_gid)
         return unless original
 
-        copy = clone_glyph(original, name: name)
+        copy = GlyphCloner.clone(original, name: name)
         copy.add_unicode(codepoint) if codepoint
         target_font.layers.default_layer.add(copy)
       end
@@ -104,36 +105,6 @@ module Fontisan
         glyph = target_font.glyph(glyph_name)
         glyph.add_unicode(codepoint) unless glyph.unicodes.include?(codepoint)
       end
-
-      def unique_target_name(target_font, base_name)
-        return base_name unless target_font.glyphs.key?(base_name)
-
-        suffix = 1
-        loop do
-          candidate = "#{base_name}.#{suffix}"
-          return candidate unless target_font.glyphs.key?(candidate)
-
-          suffix += 1
-        end
-      end
-
-      def clone_glyph(original, name:)
-        copy = Ufo::Glyph.new(name: name)
-        copy.width = original.width
-        copy.height = original.height
-        original.contours.each { |c| copy.add_contour(clone_contour(c)) }
-        original.components.each { |c| copy.add_component(c) }
-        original.anchors.each { |a| copy.add_anchor(a) }
-        original.guidelines.each { |g| copy.add_guideline(g) }
-        copy
-      end
-
-      def clone_contour(original)
-        points = original.points.map do |p|
-          Ufo::Point.new(x: p.x, y: p.y, type: p.type, smooth: p.smooth)
-        end
-        Ufo::Contour.new(points)
-      end
     end
   end
 end

data/lib/fontisan/stitcher/partition_strategy/by_block.rb

@@ -403,7 +403,9 @@ module Fontisan
         private
 
         def group_by_block(cp_map)
-          cp_map.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(cp, label), h|
+          cp_map.each_with_object(Hash.new do |h, k|
+            h[k] = []
+          end) do |(cp, label), h|
             block_label = find_block_label(cp) || :other
             h[block_label] << [cp, label]
           end

data/lib/fontisan/stitcher/partition_strategy/by_script.rb

@@ -274,14 +274,18 @@ module Fontisan
         private
 
         def group_by_script(cp_map)
-          cp_map.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(cp, label), h|
+          cp_map.each_with_object(Hash.new do |h, k|
+            h[k] = []
+          end) do |(cp, label), h|
             script = script_of_codepoint(cp)
             h[script] << [cp, label]
           end
         end
 
         def script_of_codepoint(cp)
-          block_label = ByBlock::BLOCKS.find { |_label, range| range.cover?(cp) }&.first
+          block_label = ByBlock::BLOCKS.find do |_label, range|
+            range.cover?(cp)
+          end&.first
           return :other unless block_label
 
           SCRIPT_OF_BLOCK[block_label] || :other

data/lib/fontisan/stitcher/source.rb

@@ -321,7 +321,8 @@ module Fontisan
         compound.components.each do |component|
           next unless component.args_are_xy?
 
-          raw = cache[:glyf].glyph_for(component.glyph_index, cache[:loca], cache[:head])
+          raw = cache[:glyf].glyph_for(component.glyph_index, cache[:loca],
+                                       cache[:head])
           next unless raw
 
           matrix = component.transformation_matrix

data/lib/fontisan/stitcher/unique_glyph_name.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    # Stateless glyph-name deconfliction for the Stitcher's target UFO.
+    #
+    # The Layer's contract (see +Ufo::Layer+) is that two glyphs cannot
+    # share a name — +#add+ raises on conflict. Most Stitcher call sites
+    # already know the name they want is free (e.g. they just synthesised
+    # it). The two that don't — GlyphCopier (outline donors may share
+    # post-table names) and CbdtPropagator (placeholders named "gid{N}"
+    # collide with outline glyphs sharing the same donor-gid scheme) —
+    # ask this helper to allocate a non-colliding name first.
+    #
+    # Centralising the rule here keeps the deconfliction algorithm in
+    # one place: the suffix-search loop, the separator, the order in
+    # which candidates are tried. Changing the rule (e.g. to a UUID
+    # scheme) is a one-file edit.
+    module UniqueGlyphName
+      # Separator between the base name and the disambiguating suffix.
+      # A literal period so the generated name ("gid110.1") still
+      # reads as a variant of the original.
+      SUFFIX_SEPARATOR = "."
+
+      # @param target [Ufo::Font, #glyphs] the target whose +#glyphs+
+      #   hash is the namespace being deconflicted against. Accepts the
+      #   UFO font directly so callers don't have to dig out the layer.
+      # @param base_name [String, #to_s] the requested name.
+      # @return [String] +base_name+ unchanged if no glyph with that
+      #   name exists in +target.glyphs+; otherwise the first
+      #   +"base.1"+, +"base.2"+, ... that does not exist.
+      def self.in(target, base_name)
+        base = base_name.to_s
+        return base unless target.glyphs.key?(base)
+
+        suffix = 1
+        loop do
+          candidate = "#{base}#{SUFFIX_SEPARATOR}#{suffix}"
+          return candidate unless target.glyphs.key?(candidate)
+
+          suffix += 1
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/stitcher.rb

@@ -35,7 +35,9 @@ module Fontisan
     autoload :FormatMetadata,   "fontisan/stitcher/format_metadata"
     autoload :PartitionStrategy, "fontisan/stitcher/partition_strategy"
     autoload :CbdtPropagator,   "fontisan/stitcher/cbdt_propagator"
+    autoload :GlyphCloner,      "fontisan/stitcher/glyph_cloner"
     autoload :GlyphCopier,      "fontisan/stitcher/glyph_copier"
+    autoload :UniqueGlyphName,  "fontisan/stitcher/unique_glyph_name"
 
     # Internal: pairs a compiled loaded font with its stats so
     # +write_collection+ can build the collection and the result from a
@@ -148,7 +150,8 @@ module Fontisan
       Dir.mktmpdir do |dir|
         sub_path = File.join(dir, "sub#{subfont_name}#{metadata.extension}")
         metadata.compiler_class.new(target).compile(output_path: sub_path)
-        cbdt_propagator.propagate_tables_into(cbdt_propagator.cbdt_source, sub_path)
+        cbdt_propagator.propagate_tables_into(cbdt_propagator.cbdt_source,
+                                              sub_path)
 
         loaded = Fontisan::FontLoader.load(sub_path)
         stats = SubfontStats.new(

data/lib/fontisan/subset/shared_state.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Subset
+    # Per-subsetting shared state.
+    #
+    # Several subset strategies depend on values computed by earlier
+    # strategies during the same subsetting run:
+    #
+    #   - `subset_max_advance` is computed by the Hmtx strategy and read
+    #     by Hhea (because hhea is processed alphabetically before hmtx).
+    #   - `glyf_data`, `loca_offsets`, and `subset_bbox` are computed by
+    #     the Glyf strategy and consumed by Loca and Head.
+    #
+    # Rather than giving each TableStrategy access to the entire
+    # TableSubsetter (which would couple them to internals), the
+    # cross-strategy state lives here. Each strategy receives a Context
+    # exposing [font], [mapping], [options], and this [SharedState].
+    class SharedState
+      # @return [String, nil] binary glyf data built by the Glyf strategy
+      attr_accessor :glyf_data
+
+      # @return [Array<Integer>, nil] loca offsets produced by the Glyf strategy
+      attr_accessor :loca_offsets
+
+      # @return [Array(Integer, Integer, Integer, Integer), nil] union
+      #   xMin/yMin/xMax/yMax over the subset's glyphs
+      attr_accessor :subset_bbox
+
+      # @return [Integer] largest advanceWidth seen while subsetting hmtx
+      attr_accessor :subset_max_advance
+
+      # @return [TableStrategy::ColorBitmapSubsetter, nil] cached paired
+      #   CBDT+CBLC subsetter so both strategies reuse the same pass
+      attr_accessor :color_bitmap_subsetter
+
+      def initialize
+        @subset_max_advance = 0
+      end
+    end
+  end
+end

data/lib/fontisan/subset/subset_context.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Subset
+    # Value object handed to every TableStrategy. Encapsulates the inputs
+    # (font, mapping, options) plus the cross-strategy [SharedState] so
+    # strategies don't need a back-reference to the TableSubsetter.
+    #
+    # @!attribute font
+    #   @return [SfntFont]
+    # @!attribute mapping
+    #   @return [GlyphMapping]
+    # @!attribute options
+    #   @return [Options]
+    # @!attribute state
+    #   @return [SharedState]
+    SubsetContext = Struct.new(:font, :mapping, :options, :state,
+                               keyword_init: true)
+  end
+end

data/lib/fontisan/subset/table_strategy/cbdt.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Subset
+    module TableStrategy
+      # CBDT strategy: delegate to [ColorBitmapSubsetter], which produces
+      # both CBDT and CBLC bytes in a single pass. The Cblc strategy
+      # reads from the same collaborator so the two tables stay
+      # consistent.
+      class Cbdt
+        # @param context [SubsetContext]
+        # @param tag [String] "CBDT"
+        # @param table [Cbdt] parsed CBDT table (unused)
+        # @return [String] subset CBDT bytes
+        def self.call(context:, tag:, table:)
+          color_bitmap_subsetter(context).cbdt_bytes
+        end
+
+        # @param context [SubsetContext]
+        # @return [ColorBitmapSubsetter] cached on the shared state so the
+        #   Cblc strategy reuses the same pass
+        def self.color_bitmap_subsetter(context)
+          context.state.color_bitmap_subsetter ||= ColorBitmapSubsetter.new(font: context.font,
+                                                                            mapping: context.mapping).build
+        end
+        private_class_method :color_bitmap_subsetter
+      end
+    end
+  end
+end

data/lib/fontisan/subset/table_strategy/cblc.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Subset
+    module TableStrategy
+      # CBLC strategy: delegate to [ColorBitmapSubsetter] (the same
+      # collaborator used by the Cbdt strategy) so both tables stay
+      # consistent. The subsetter is built lazily on first access and
+      # cached on [SharedState].
+      class Cblc
+        # @param context [SubsetContext]
+        # @param tag [String] "CBLC"
+        # @param table [Cblc] parsed CBLC table (unused)
+        # @return [String] subset CBLC bytes
+        def self.call(context:, tag:, table:)
+          color_bitmap_subsetter(context).cblc_bytes
+        end
+
+        def self.color_bitmap_subsetter(context)
+          context.state.color_bitmap_subsetter ||= ColorBitmapSubsetter.new(font: context.font,
+                                                                            mapping: context.mapping).build
+        end
+        private_class_method :color_bitmap_subsetter
+      end
+    end
+  end
+end