fontico 0.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e650a7b2e4dd27bd57a0318811c9e5557b229c7b21151fd40b670f6d513532b1
-  data.tar.gz: 0a59aa8f304d339c3d5a151c3359473c585ef1c9fe438252d24147a19462c937
+  metadata.gz: 1ee86cae31c0f7f4acb9b303bfd2c06638ea383d86e27ff603452537ec58cfed
+  data.tar.gz: cf9b3485369dd8601822dad9b1e367bccb41c440620071412b595b755afa97c9
 SHA512:
-  metadata.gz: 07f21c106e47d7dbc23e73a0c8d091d7b9284bc6a32b0d2fde04a7fef5fc9d11e3b650a9e223dfd204214511d35ae454ffa67602e2e0e48426295456cd72d682
-  data.tar.gz: fccdc71296e585a335f9a7539234ced2cf6fe1e8f51721aa288825cb840e9a3866db1e31cd1c947e2293383828068dcd112263d31cfeffbfa2548c04e1be913a
+  metadata.gz: e9e776c9fb99a18085b38a4069f23b72c808ba48c45b321d7948a166c99dd0bf9e93f413dd13a729a5a085148ffdf8e4a1feef544c4babec168e37d037e3b316
+  data.tar.gz: c5e3727514c2ebaff8c1b879ca9c2468bd2b14df0bef16797f983580b5830ac52b75fd93b9b3f639d433b7e11bac28aedc4c6cacf1d448d66bb2a715cdeccbc5

data/README.md

@@ -1,6 +1,16 @@
-# fontico
+```
+╔═╗╔═╗╔╗╔╔╦╗╦╔═╗╔═╗
+╠╣ ║ ║║║║ ║ ║║  ║ ║
+╚  ╚═╝╝╚╝ ╩ ╩╚═╝╚═╝
+```
+
+**Name icons by intent. Source them from anywhere. Ship one artifact.**
 
-Name icons by intent. Source them from anywhere. Ship one artifact.
+[![Gem](https://img.shields.io/gem/v/fontico)](https://rubygems.org/gems/fontico)
+[![CI](https://github.com/fireho/fontico/actions/workflows/ci.yml/badge.svg)](https://github.com/fireho/fontico/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE.txt)
+
+---
 
 ```erb
 <%= icon "save" %>      <%# Lucide            %>
@@ -11,6 +21,32 @@ Name icons by intent. Source them from anywhere. Ship one artifact.
 Three providers, one call. Templates never name a vendor, so re-skinning the
 app — or surviving an upstream rename — is a diff in one file.
 
+|                          |                                                                                     |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| **353,000 icons**        | any of[Iconify's 238 sets](https://icon-sets.iconify.design/), plus your own folder |
+| **One request**          | a single sprite, 2.3KB brotli, not render-blocking                                  |
+| **361ms cold, 2ms warm** | measured on 35 icons across two remote providers and five local files               |
+| **No Node, no npm**      | the sprite target is pure Ruby; deploys rebuild offline from the lockfile           |
+| **Also PDFs**            | a real TTF for Prawn, with pinned codepoints                                        |
+| **Also firmware**        | `icons.h` for C/C++, same names, 7KB of font instead of 357KB                        |
+| **Also bare metal**      | a `GFXfont` compiled in — 11KB for 221 icons, no renderer, no filesystem            |
+
+## Install
+
+```ruby
+# Gemfile
+gem "fontico"
+```
+
+```bash
+bundle install
+$EDITOR icons.yml     # the manifest, below
+rake fontico:build
+```
+
+No JS bundle, no `package.json`, no importmap pin. Artifacts land in
+`app/assets/builds/`, which Propshaft already serves.
+
 ## The manifest
 
 `icons.yml`, one line per icon:
@@ -35,26 +71,25 @@ icons:
 ```
 
 Like pokemon, you gotta catch 'em all.
-Any of [Iconify's 200k+ icons](https://icon-sets.iconify.design/) work as a
-provider prefix. Your own SVGs go in `app/assets/icons/`, filename as slug.
+Any of [Iconify's sets](https://icon-sets.iconify.design/) work as a provider
+prefix. Your own SVGs go in `app/assets/icons/`, filename as slug.
+
+A Rails engine that ships `config/icons.yml` (or `icons.yml` at its root) is
+merged under the app's file, the same way `config/locales/` layers. Later
+wins a name — the app always has the last word. Nested groups merge, so an
+engine can ship `auth.google` and the app can add `auth.apple` without
+copying the rest. `rake fontico:build` reads the same list.
 
 ## Build
 
 ```bash
 rake fontico:build     # resolve, normalise, emit
-rake fontico:update    # re-fetch, ignoring icons.lock
+rake fontico:update    # re-fetch bodies; codepoints stay pinned
 ```
 
-Artifacts land in `app/assets/builds/`, which Propshaft serves automatically —
-no manifest, no precompile list. `rake assets:precompile` is hooked, so deploys
-need no extra step.
+`rake assets:precompile` is hooked, so deploys need no extra step.
 
-That directory is gitignored in a stock Rails app, so nothing is committed from
-it. **`icons.lock` is the thing you commit**: it holds every normalised body,
-so a deploy rebuilds the sprite from it in milliseconds with no network access
-and no Node.
-
-In development you rarely type either one. Saving `icons.yml` — or a local
+**In development you rarely type either one.** Saving `icons.yml` — or a local
 SVG — rebuilds the artifacts and drops the cached manifest, so the icon is live
 on the next request: no rake, no restart. A save that only reshuffles known
 icons costs a couple of milliseconds; a brand-new one pays its provider fetch
@@ -73,13 +108,14 @@ there — is named in red and left out; the rest of the manifest still builds.
 It keeps its codepoint reserved, so fixing the entry and rebuilding brings it
 back with the same glyph. A provider that is unreachable is still fatal.
 
-Measured on 35 icons across two remote providers and five local files:
-**361ms cold, 2ms warm.** Vendor icons are fetched in one batched request per
-provider — not one per icon.
+Vendor icons are fetched in one batched request per provider — not one per
+icon.
 
 ## Why there is a lockfile
 
-`icons.lock` pins two things that must not drift:
+`app/assets/builds/` is gitignored in a stock Rails app, so nothing is
+committed from it. **`icons.lock` is the thing you commit.** It pins two things
+that must not drift:
 
 - **Codepoints**, append-only. Adding an icon must not renumber the others, or
   every glyph in a built font moves and the committed artifact churns
@@ -88,20 +124,21 @@ provider — not one per icon.
   Iconify API serves *latest*; without this an icon can silently change shape
   between two builds of the same manifest.
 
-Commit it.
+A deploy rebuilds the sprite from it in milliseconds, with no network access
+and no Node. Commit it.
 
 ## What happens to your SVGs
 
 First-party exports are not uniform the way vendor icons are, so everything
 entering `app/assets/icons/` is normalised first:
 
-| | |
-| --- | --- |
-| Editor chrome | `sodipodi:`, `inkscape:`, `<metadata>`, RDF, empty `<defs>` stripped |
-| Ids | rewritten to `slug__id`, with `url(#…)`, `href`, `clip-path`, `mask` following |
-| viewBox | any source box refitted into the target, centred, aspect preserved |
-| Colour | folded to `currentColor`, unless the icon is detected as multicolour |
-| Safety | `<script>`, `on*` handlers, `<foreignObject>`, external refs removed |
+|               |                                                                                |
+| ------------- | ------------------------------------------------------------------------------ |
+| Editor chrome | `sodipodi:`, `inkscape:`, `<metadata>`, RDF, empty `<defs>` stripped           |
+| Ids           | rewritten to`slug__id`, with `url(#…)`, `href`, `clip-path`, `mask` following |
+| viewBox       | any source box refitted into the target, centred, aspect preserved             |
+| Colour        | folded to`currentColor`, unless the icon is detected as multicolour            |
+| Safety        | `<script>`, `on*` handlers, `<foreignObject>`, external refs removed           |
 
 The id rewriting is not optional hygiene. Across 40 SVGs sampled from a real
 machine, **34 shared `id="layer1"`** and 11 shared `id="path1"` — merging any
@@ -184,11 +221,11 @@ codepoint, so nothing gets hardcoded.
 A font glyph is filled contours; it has no strokes and no colour. Each icon
 takes one of three routes:
 
-| | |
-| --- | --- |
-| **filled** | used as-is — Material Symbols, most Iconify sets, flat first-party exports |
+|               |                                                                                                                         |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **filled**    | used as-is — Material Symbols, most Iconify sets, flat first-party exports                                             |
 | **extracted** | stroke-based, but the provider ships a font whose glyphs are already expanded — lifted from there, losslessly (Lucide) |
-| **refused** | stroke-based with no provider font — the build stops and names the icon |
+| **refused**   | stroke-based with no provider font — the build stops and names the icon                                                |
 
 There is deliberately no raster-trace fallback. Both published JS expanders
 (`svg-outline-stroke`, `oslllo-svg-fixer`) run artwork through potrace and hand
@@ -204,12 +241,126 @@ build names each one it dropped.
 Font targets need Node, installed on demand into `~/.cache/fontico`. A manifest
 with `targets: [sprite]` never touches it and stays pure Ruby.
 
+## Firmware, and C
+
+The `c` target emits `icons.h`, so a device names icons by intent like every
+other consumer. It draws them out of the same TTF, which is why `c` implies
+`ttf` the way `sprite` implies `css`.
+
+`targets:` takes a mapping when an artifact belongs somewhere specific — a
+firmware header goes in the device's `include/`, not in `app/assets/builds`
+next to the web files:
+
+```yaml
+targets:
+  sprite:                                 # default location
+  ttf:  devs/esplay/data/icons.ttf
+  c:    devs/esplay/include/icons.h
+```
+
+```c
+#include "icons.h"
+
+display.drawIcon(ICON_WIFI, 86, 5, COLOR_WHITE, 20);   /* "\xEE\x80\x81" */
+```
+
+The UTF-8 bytes are literals decided at build time, so nothing parses
+`"U+e63e"` or builds a `String` on the heap inside a draw loop. For an icon
+named at runtime rather than compiled in — arriving in an MQTT payload, say —
+the header also carries a name-sorted table:
+
+```c
+#define FONTICO_ICONS_IMPLEMENTATION   /* in exactly one translation unit */
+#include "icons.h"
+
+const char *glyph = fontico_icon(payload["icon"]);   /* NULL if unknown */
+```
+
+Two reasons this is a better deal than a vendor icon font on the device:
+
+- **Size.** The font carries only the icons your manifest names. 35 icons
+  build a 7KB TTF, against the 357KB an unsubsetted Material Symbols drop-in
+  costs — and flash is the budget that actually binds.
+- **Codepoints that cannot move.** They are pinned append-only in
+  `icons.lock`, which matters more here than anywhere else: a codepoint
+  compiled into a flashed image cannot be hotfixed. If adding an icon
+  renumbered the others, every board in the field would draw the wrong
+  picture after an OTA.
+
+Names become macros — `nav.menu` is `ICON_NAV_MENU`. Two names that fold to
+the same macro are refused rather than silently redefined, and non-ASCII
+names are refused too: the table is sorted here and `bsearch`ed there, and a
+byte above `0x7F` orders the other way under a signed `char`.
+
+Multicolour icons are left out, the same as they are left out of the font —
+there would be no glyph behind the codepoint. The build names each one.
+
+### `gfxfont`: no font renderer on the device at all
+
+The `c` target still needs something on the device that can read a TTF. The
+`gfxfont` target removes that: it emits an Adafruit `GFXfont` — 1-bit bitmaps
+and a glyph table, compiled straight into the binary. No FreeType, no
+OpenFontRender, no filesystem partition to flash. `Adafruit_GFX` and
+`Arduino_GFX` both take it as-is:
+
+```yaml
+targets:
+  sprite:
+  gfxfont:
+    path: devs/include/icons_font.h
+    size: 24
+```
+
+```c
+#include <Arduino_GFX_Library.h>
+#include "icons_font.h"
+
+gfx->setFont(&fontico_icons24);
+gfx->drawChar(x, y, ICON_WIFI, fg, bg, 1);
+```
+
+221 icons at 24px come to **9,961 bytes of bitmap** plus a 1,547-byte glyph
+table — about 11KB for the set, against 357KB for an unsubsetted vendor font
+on a filesystem. Bitmaps are rasterised out of the TTF fontico already
+builds, not from the SVGs, so they inherit the same normalised geometry the
+PDF uses instead of drifting from it through a second pipeline.
+
+Two things follow from the format. A `GFXfont` is **fixed size**, so ask for
+the size you will draw at rather than scaling one up. And it is indexed off a
+byte, so it holds 224 icons; past that the build says so and points you at the
+`c` target, which addresses codepoints directly. The char codes are positional
+for that reason, which is why they and the bitmaps are emitted into one file —
+they cannot disagree. Their order follows the append-only codepoints in
+`icons.lock`, so adding an icon appends instead of renumbering what is already
+flashed.
+
+At one bit deep, thin strokes fall through the threshold at small sizes. An
+icon that rasterises to nothing is refused rather than shipped as an icon that
+draws as nothing.
+
+## How it compares
+
+|                              | vendor gems (`lucide-rails`, `heroicon`) | `iconify-icon` web component   | fontico               |
+| ---------------------------- | ---------------------------------------- | ------------------------------ | --------------------- |
+| Icon sets                    | one, per gem                             | 238                            | 238 + your own       |
+| Where the SVG comes from     | inlined per render                       | fetched at runtime, per client | one build-time sprite |
+| Requests                     | 0, but repeated in every response body   | 1+ per icon, per visitor       | 1, cached             |
+| JS required                  | no                                       | yes                            | no                    |
+| Rename-proof templates       | no —`lucide_icon "pencil"`              | no —`icon="lucide:pencil"`    | yes —`icon "edit"`   |
+| Offline / reproducible build | yes                                      | no                             | yes, via`icons.lock`  |
+| PDF                          | no                                       | no                             | yes, TTF for Prawn    |
+
 ## Status
 
 - ✅ Manifest, resolver, preprocessor, lockfile, sprite emitter, Rails helper
 - ✅ TTF emitter with glyph extraction, codepoint API, Prawn helpers
+- ✅ `c` target: `icons.h` for firmware, with per-target output paths
+- ✅ `gfxfont` target: 1-bit bitmaps compiled in, for Adafruit_GFX / Arduino_GFX
 - ⏳ `woff2` — declared targets are skipped with a notice
+- ⏳ `variant:` — accepted and ignored by the helper; see [TODO.md](TODO.md)
 
 ## License
 
-MIT
+MIT.
+Icons keep their upstream licenses:
+`icons.lock` records what you declared and shipped.

data/lib/fontico/builder.rb

@@ -12,11 +12,13 @@ module Fontico
     Report = Struct.new(:written, :warnings, :skipped, :cached, :fetched, :pending,
                         :missing, keyword_init: true)
 
-    def initialize(manifest, root: Dir.pwd, output: "app/assets/builds", offline: false)
+    def initialize(manifest, root: Dir.pwd, output: "app/assets/builds",
+                   offline: false, force: false)
       @manifest = manifest
       @root = root
       @output = File.join(root, output)
       @offline = offline
+      @force = force
       @lock = Lockfile.new(File.join(root, "icons.lock"))
     end
 
@@ -25,11 +27,28 @@ module Fontico
       cached, fetched = [], []
       missing = {}
 
-      stale = @manifest.icons.reject { @lock.fresh?(_1.name, _1.source) }
+      # The lock caches Iconify bodies so deploys run offline. Local files
+      # are already on disk: treating them as fresh meant editing logo.svg
+      # rebuilt nothing. Force is `rake fontico:update` — re-fetch remotes,
+      # keep the append-only codepoints.
+      # A lock from before sizes were recorded is taken at the manifest's word
+      # once, here, so an upgrade does not re-fetch everything. From then on a
+      # change to `defaults: size:` is caught like any other input change.
+      @lock.assume_size(@manifest.size)
+
+      stale = @manifest.icons.select do |icon|
+        icon.local? || @force ||
+          !@lock.fresh?(icon.name, icon.source, size: @manifest.size, multicolor: icon.multicolor)
+      end
       cached = @manifest.icons.map(&:name) - stale.map(&:name)
 
       unless stale.empty?
-        raise Error, "icons.lock is missing #{stale.size} icon(s) and --offline was given" if @offline
+        remote_stale = stale.reject(&:local?)
+        # Local files do not need the network. Offline is a hard fail only
+        # when a remote body has to come off the wire — which under force is
+        # every remote, lock or no lock. Saying "missing" there would be a
+        # lie: the bodies are present, force is what made them stale.
+        raise Error, "cannot #{offline_blocker(remote_stale)} and --offline was given" if @offline && remote_stale.any?
 
         resolver = Resolver.new(@manifest, root: @root)
         sources = resolver.call(only: stale.map(&:name))
@@ -43,9 +62,16 @@ module Fontico
 
           pre = Preprocessor.new(icon, size: @manifest.size)
                             .call(src.markup, width: src.width, height: src.height)
-          @lock.store(icon.name, source: icon.source, body: pre.body,
+          # Locals are re-read every build, so "stale" does not mean changed.
+          # Compare the stored digest to keep an untouched logo.svg counted as
+          # cached rather than reported as a fetch that never happened. A
+          # remote is judged by the wire, not the digest: under force it was
+          # genuinely re-fetched even when it came back byte-identical.
+          before = @lock.entry(icon.name)&.fetch("digest", nil)
+          @lock.store(icon.name, source: icon.source, body: pre.body, size: @manifest.size,
                       multicolor: pre.multicolor, warnings: pre.warnings)
-          fetched << icon.name
+          unchanged = icon.local? && @lock.entry(icon.name)["digest"] == before
+          (unchanged ? cached : fetched) << icon.name
         end
       end
 
@@ -68,6 +94,25 @@ module Fontico
 
     private
 
+    # "missing from icons.lock" is a lie when every body is present and
+    # something else invalidated them, so name the thing that actually did.
+    # A body carries its refit baked in, so a new size needs the original
+    # geometry back off the wire — there is nothing on disk to redo it from.
+    def offline_blocker(remote_stale)
+      count = remote_stale.size
+      return "re-fetch #{count} icon(s)" if @force
+      return "resolve #{count} icon(s) missing from icons.lock" unless remote_stale.all? { locked?(_1) }
+
+      "re-preprocess #{count} icon(s) at size: #{@manifest.size}"
+    end
+
+    # Present in the lock, with a body, for this source — so not "missing",
+    # only invalidated by one of the inputs #fresh? checks alongside it.
+    def locked?(icon)
+      e = @lock.entry(icon.name)
+      !e.nil? && !e["body"].nil? && e["source"] == icon.source
+    end
+
     def emit(icons)
       FileUtils.mkdir_p(@output)
       written = []
@@ -75,9 +120,18 @@ module Fontico
 
       targets = @manifest.targets - PENDING
       targets += ["css"] if targets.include?("sprite") && !targets.include?("css")
+      # Both C targets lean on the font: the header is a map into it, and the
+      # gfxfont is rasterised out of it. Same implication as sprite -> css.
+      needs_font = targets.include?("c") || targets.include?("gfxfont")
+      targets += ["ttf"] if needs_font && !targets.include?("ttf")
+      # And the gfxfont reads the .ttf off disk, so it has to run after it.
+      targets = targets.partition { _1 != "gfxfont" }.flatten
 
       targets.each do |target|
-        path = File.join(@output, filename_for(target))
+        path = path_for(target)
+        # Before the emitter runs, not after it returns: a font target writes
+        # its own file through Node and needs the directory already there.
+        FileUtils.mkdir_p(File.dirname(path))
         emitter = emitter_for(target, [], path: path)
 
         accepted = icons.select { emitter.accepts?(_1) }
@@ -94,12 +148,29 @@ module Fontico
       [written, skipped]
     end
 
+    # An explicit path in the manifest wins, so a firmware header can land in
+    # the device's include/ directory instead of among the web artifacts.
+    #
+    # Always absolute: a font target hands its path to Node, which runs from
+    # its own toolchain directory and cannot resolve a relative one.
+    def path_for(target)
+      override = @manifest.target_path(target)
+      return File.expand_path(override, @root) if override
+
+      File.expand_path(filename_for(target), @output)
+    end
+
     def emitter_for(target, build = [], path: nil)
       case target
       when "sprite" then Emitters::Sprite.new(@manifest, build)
       when "css"    then Emitters::Stylesheet.new(@manifest, build)
       when "ttf"    then Emitters::Font.new(@manifest, build, lock: @lock, output: path)
-      else raise Error, "unknown target #{target.inspect} (have: sprite, ttf)"
+      when "c"      then Emitters::Header.new(@manifest, build, lock: @lock)
+      when "gfxfont"
+        opts = @manifest.target_options(target)
+        Emitters::GfxFont.new(@manifest, build, lock: @lock, ttf: path_for("ttf"),
+                                                size: (opts["size"] || 24).to_i)
+      else raise Error, "unknown target #{target.inspect} (have: sprite, ttf, c, gfxfont)"
       end
     end
 
@@ -107,7 +178,9 @@ module Fontico
       case target
       when "sprite" then "icons.svg"
       when "css"    then "icons.css"
-      when "ttf"    then "icons.ttf"
+      when "ttf"     then "icons.ttf"
+      when "c"       then "icons.h"
+      when "gfxfont" then "icons_font.h"
       else raise Error, "unknown target #{target.inspect}"
       end
     end

data/lib/fontico/emitters/font.rb

@@ -26,9 +26,16 @@ module Fontico
         outlines = @outliner.outlines(@build, size: @manifest.size)
 
         glyphs = @build.map do |icon, body|
-          { name: icon.key,
-            codepoint: @lock.codepoint_for(icon.name),
-            svg: document(outlines[icon.name], body) }
+          # Never fall back to allocating here. The builder has already
+          # save!d the lock by the time it emits, so a codepoint minted now
+          # would never reach disk: the font would ship a glyph that
+          # Fontico.glyph cannot name. A nil is worse still — it reaches
+          # String.fromCodePoint as null and maps the glyph to U+0000
+          # without complaint.
+          cp = @lock.codepoint_for(icon.name)
+          raise Fontico::Error, "#{icon.name} has no codepoint in icons.lock" if cp.nil?
+
+          { name: icon.key, codepoint: cp, svg: document(outlines[icon.name], body) }
         end
 
         result = @outliner.instance_variable_get(:@runner)

data/lib/fontico/emitters/gfx_font.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Fontico
+  module Emitters
+    # An Adafruit GFXfont, for a display driven by Adafruit_GFX or Arduino_GFX.
+    # It compiles into the binary, so unlike the TTF target there is no
+    # FreeType on the device, no font renderer, and no filesystem to flash.
+    #
+    # The trade is that a GFXfont is a fixed size and one bit deep. Ask for the
+    # size you will draw at; scaling one up is what the built-in 6x8 font
+    # already does badly.
+    #
+    # Char codes rather than codepoints, because that is what the draw path
+    # takes: Adafruit_GFX and Arduino_GFX both index glyphs as `c - first` off
+    # a byte. They are therefore positional, which is exactly why the codes and
+    # the bitmaps are emitted into one file — they cannot fall out of step with
+    # each other. What keeps them stable across builds is the order, and the
+    # order comes from the append-only codepoints in icons.lock.
+    class GfxFont
+      # 0x20..0xFF. Below 0x20 is control characters, which some print paths
+      # intercept before the font ever sees them.
+      FIRST = 0x20
+      LAST  = 0xFF
+      CAPACITY = LAST - FIRST + 1
+
+      def initialize(manifest, build, lock: nil, ttf: nil, size: 24, runner: nil)
+        @manifest = manifest
+        @build = build
+        @lock = lock
+        @ttf = ttf
+        @size = size
+        @runner = runner || NodeRunner.new
+      end
+
+      # Same rule as the font it is rasterised from: one bit cannot hold
+      # colour, so a multicolour icon has nothing to become.
+      def accepts?(icon) = !(@lock&.multicolor?(icon.name) || icon.multicolor?)
+      def rules_only? = false
+
+      def call
+        icons = @build.map(&:first).sort_by { codepoint!(_1) }
+        # A GFXfont with no glyphs is not a font. This is reachable when every
+        # icon in the manifest was dropped as multicolour.
+        raise Fontico::Error, "the gfxfont target has no icons left to rasterise" if icons.empty?
+
+        guard_capacity!(icons)
+
+        result = @runner.run("rasterize.mjs", {
+                               ttf: @ttf, size: @size,
+                               glyphs: icons.map { { name: _1.name, codepoint: codepoint!(_1) } }
+                             })
+        rows = rows_for(result["glyphs"], icons)
+        guard_blank!(rows)
+
+        render(rows, result["yAdvance"])
+      end
+
+      private
+
+      def codepoint!(icon)
+        @lock&.codepoint_for(icon.name) ||
+          raise(Fontico::Error, "#{icon.name} has no codepoint in icons.lock")
+      end
+
+      def rows_for(glyphs, icons)
+        by_name = glyphs.to_h { [_1["name"], _1] }
+        offset = 0
+        icons.each_with_index.map do |icon, i|
+          g = by_name.fetch(icon.name)
+          row = { name: icon.name, source: icon.source, char: FIRST + i,
+                  ident: Header.identifier(icon.name), offset: offset, glyph: g }
+          offset += g["bytes"].size
+          row
+        end
+      end
+
+      # A GFXfont has room for one byte's worth of glyphs and no more. Failing
+      # here beats emitting a font that silently stops at icon 224.
+      def guard_capacity!(icons)
+        return if icons.size <= CAPACITY
+
+        raise Fontico::Error,
+              "the gfxfont target holds #{CAPACITY} icons (a GFXfont is indexed off a byte) " \
+              "and this manifest has #{icons.size}. Split the icons across two fonts, or " \
+              "build the c target instead, which addresses codepoints directly."
+      end
+
+      # An icon that rasterised to nothing would draw as empty space with no
+      # complaint, on a screen nobody is watching.
+      def guard_blank!(rows)
+        blank = rows.select { _1[:glyph]["blank"] }
+        return if blank.empty?
+
+        raise Fontico::Error, <<~MSG
+          #{blank.size} icon(s) rasterised blank at #{@size}px and would draw as nothing:
+
+            #{blank.map { _1[:name] }.join("\n  ")}
+
+          Thin strokes fall through a one-bit threshold at small sizes. Either
+          raise the gfxfont size, or drop these from the target.
+        MSG
+      end
+
+      def render(rows, y_advance)
+        bytes = rows.flat_map { _1[:glyph]["bytes"] }
+        tag = "fontico_icons#{@size}"
+
+        <<~HEADER
+          /* generated by fontico — do not edit.
+           *
+           * #{rows.size} icon(s) as an Adafruit GFXfont, rasterised at #{@size}px, one bit
+           * deep. #{bytes.size} bytes of bitmap. Include this after your GFX library
+           * header; it defines the GFXglyph/GFXfont structs only if that has
+           * not already done so.
+           *
+           *   gfx->setFont(&#{tag});
+           *   gfx->drawChar(x, y, #{rows.first[:ident]}, fg, bg, 1);
+           *
+           * The char codes below are positional, so they and the bitmaps are
+           * one artifact and are regenerated together. Their order follows the
+           * append-only codepoints in icons.lock, so adding an icon appends
+           * rather than renumbering what is already flashed.
+           */
+          #ifndef FONTICO_GFXFONT_H
+          #define FONTICO_GFXFONT_H
+
+          #include <stdint.h>
+
+          /* Adafruit_GFX's own guard, so the library wins when it is present. */
+          #ifndef _GFXFONT_H_
+          #define _GFXFONT_H_
+          typedef struct {
+            uint16_t bitmapOffset;
+            uint8_t  width, height, xAdvance;
+            int8_t   xOffset, yOffset;
+          } GFXglyph;
+          typedef struct {
+            uint8_t  *bitmap;
+            GFXglyph *glyph;
+            uint16_t  first, last;
+            uint8_t   yAdvance;
+          } GFXfont;
+          #endif
+
+          #ifndef PROGMEM
+          #define PROGMEM
+          #endif
+
+          #{defines(rows).join("\n")}
+
+          /* One continuous MSB-first bitstream, no padding between rows. */
+          static const uint8_t #{tag}_bitmaps[] PROGMEM = {
+          #{bitmap_lines(bytes).join("\n")}
+          };
+
+          static const GFXglyph #{tag}_glyphs[] PROGMEM = {
+          #{rows.map { glyph_line(_1) }.join("\n")}
+          };
+
+          static const GFXfont #{tag} PROGMEM = {
+            (uint8_t *)#{tag}_bitmaps,
+            (GFXglyph *)#{tag}_glyphs,
+            0x#{format("%02X", FIRST)}, 0x#{format("%02X", rows.last[:char])}, #{y_advance}
+          };
+
+          #endif /* FONTICO_GFXFONT_H */
+        HEADER
+      end
+
+      def defines(rows)
+        width = rows.map { _1[:ident].length }.max.to_i
+        rows.map do |r|
+          format("#define %-#{width}s 0x%02X /* %s  %s */",
+                 r[:ident], r[:char], r[:name], r[:source])
+        end
+      end
+
+      def bitmap_lines(bytes)
+        bytes.each_slice(16).map { "  #{_1.map { |b| format("0x%02X", b) }.join(", ")}," }
+      end
+
+      def glyph_line(row)
+        g = row[:glyph]
+        format("  { %5d, %3d, %3d, %3d, %4d, %4d }, /* %s */",
+               row[:offset], g["width"], g["height"], g["xAdvance"],
+               g["xOffset"], g["yOffset"], row[:name])
+      end
+    end
+  end
+end