@olegkoval/agent-skills 1.19.0 → 1.20.0

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: garmin-watchface
+description: Build, test, screenshot and publish Garmin Connect IQ watch faces in Monkey C. Use when working on a Connect IQ watch face or app - creating one, fixing layout that clips or overlaps, capturing simulator screenshots, adding app settings, widening device support, or preparing a Connect IQ Store submission. Encodes the traps that silently produce a passing build and a broken face.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires macOS, the Connect IQ SDK, a JDK, and Python 3 (Pillow for screenshot cropping).
+metadata:
+  targets: [_source-only]
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Garmin Connect IQ watch faces
+
+Monkey C gives you almost no safety net. The compiler is happy to build a face
+that draws off the bottom of the screen, a test suite that contains no tests, and
+a colour that is not the colour you get. Everything below is a failure mode that
+looked like success first.
+
+**Read `references/` files as needed — do not read them all up front.**
+
+| File | When |
+| --- | --- |
+| `references/display.md` | Choosing colours, anything about brightness or legibility |
+| `references/layout.md` | Positioning anything; content clipped, overlapping, or off-screen |
+| `references/testing.md` | Writing tests; a suspiciously clean test run |
+| `references/simulator.md` | Screenshots, settings not applying, monkeydo hanging |
+| `references/devices.md` | Adding device support, launcher icons, API levels |
+| `references/store.md` | Publishing, listing copy, IP questions |
+
+## Tools
+
+Run these rather than reinventing them. All are standalone.
+
+```bash
+<skill-dir>/scripts/ciq-doctor                    # toolchain check: SDK, JDK, key, devices
+<skill-dir>/scripts/ciq-devices                   # survey installed devices by resolution
+<skill-dir>/scripts/ciq-devices --same-as fenix6pro   # products you can add with no code change
+<skill-dir>/scripts/ciq-capture out.png           # calibrated simulator screenshot
+<skill-dir>/scripts/ciq-capture out.png --face --size 260   # cropped + masked to the round display
+<skill-dir>/scripts/ciq-calibrate                 # re-derive the display rect if capture looks wrong
+```
+
+`<skill-dir>/scripts/ciq-capture` exists because `screencapture -R` grabs a screen *region*, not
+a window: without a frontmost check it silently photographs whatever is on top,
+and the window moves between simulator restarts. Both failure modes produce a
+plausible PNG of the wrong thing.
+
+## The five things that will bite you
+
+### 1. `make test` can compile zero tests and report success
+
+If `monkey.jungle` sets `base.excludeAnnotations = test`, every `(:test)`
+function is stripped from **every** target, including the unit-test build. You
+get `BUILD SUCCESSFUL` and a green run with nothing compiled — even when the test
+files reference symbols that no longer exist.
+
+Fix: a second jungle passed as an additional `-f`. See
+`<skill-dir>/templates/monkey.test.jungle` and the `test` target in `<skill-dir>/templates/Makefile`.
+
+**Prove it before you trust it.** Put a deliberately unresolvable symbol in one
+test and confirm the build fails:
+
+```monkeyc
+return ThisDoesNotExist.definitelyNotAFunction();
+```
+
+### 2. Never hardcode a Y coordinate or assume a font height
+
+`dc.getFontHeight()` is the only source of truth, and the numbers are larger than
+they look. Measured on fenix 6 Pro:
+
+| Font | Height |
+| --- | --- |
+| `FONT_XTINY` | 19 |
+| `FONT_TINY` | 29 |
+| `FONT_SMALL` | 32 |
+| `FONT_NUMBER_MEDIUM` | 74 |
+
+Content drawn past the screen height is simply invisible — no error, no warning,
+no clipping indicator. A two-line `FONT_NUMBER_MEDIUM` block is 148px of a 260px
+face.
+
+Derive every Y at draw time, and **clamp** so a bottom row cannot be pushed off:
+
+```monkeyc
+function clampRuleY(derived as Number, footerH as Number) as Number {
+    var reserved = (footerH * 2) + GAP_BELOW_RULE + GAP_BETWEEN_ROWS;
+    var maxRuleY = SCREEN - BOTTOM_MARGIN - reserved;
+    return derived > maxRuleY ? maxRuleY : derived;
+}
+```
+
+See `references/layout.md`.
+
+### 3. The screen is round; your layout is not
+
+Check content against the bezel curve, not the bounding square. A rectangle
+inscribed in a circle fails at its **corners** long before its sides.
+
+```monkeyc
+function halfWidthAt(y as Number) as Number {
+    var dy = y - CENTER;
+    var inside = (CENTER * CENTER) - (dy * dy);
+    return inside <= 0 ? 0 : Math.sqrt(inside).toNumber();
+}
+```
+
+### 4. Colours are quantised, and brightness is reflectance
+
+Many devices snap to a 4×4×4 lattice: `0x00 / 0x55 / 0xAA / 0xFF` per channel. A
+colour not already on it is not the colour that ships.
+
+More important: MIP screens are **transflective with no backlight**. A colour's
+brightness *is* how much ambient light it returns. Grey reflects about two-thirds
+of what white does. Choosing a photographically accurate grey for a large area
+makes the whole face read as dim on the wrist while looking fine in the
+simulator's backlit LCD.
+
+Corollary: a saturated colour on a glyph reflects only its own channel, making
+the thing you want to read the *dimmest* thing on screen.
+
+See `references/display.md`.
+
+### 5. The simulator lies about settings
+
+It persists app settings and **ignores changed defaults in `properties.xml`**
+until you do File → Reset All App Data. A property will keep reading its old
+value while the XML plainly says otherwise. This looks exactly like broken
+settings code.
+
+Reset also drops the loaded device, so relaunch and re-push afterwards.
+
+See `references/simulator.md`.
+
+## Workflow
+
+### Starting a face
+
+1. `<skill-dir>/scripts/ciq-doctor` — confirm SDK, JDK, developer key, target device installed.
+2. Copy `<skill-dir>/templates/Makefile`, `<skill-dir>/templates/monkey.jungle`, `<skill-dir>/templates/monkey.test.jungle`.
+3. Generate a fresh app id: `python3 -c "import uuid;print(uuid.uuid4().hex)"`.
+4. Split source by responsibility. This structure has held up well:
+
+| Module | Holds |
+| --- | --- |
+| `Palette.mc` | Colours only, all lattice-exact |
+| `Layout.mc` | Geometry, derivations, bezel maths — no drawing |
+| `<Widget>.mc` | Drawing primitives (rows, bars, segments) |
+| `Fields.mc` | Formatting and thresholds — pure, easy to test |
+| `Sensors.mc` | Sensor reads with null handling |
+| `<Name>View.mc` | Composition only |
+
+Keeping `Layout` free of `Dc` calls is what makes geometry unit-testable.
+
+### Every change
+
+```bash
+make build && make test && make lint
+```
+
+`make lint` is level 3 and catches real problems the level 2 build allows.
+
+### Before committing
+
+Capture and *look at it*. Layout bugs are invisible in a passing test run:
+
+```bash
+make build && make sim
+<skill-dir>/scripts/ciq-capture /tmp/face.png --face --size 260
+```
+
+Then Read the PNG. Every layout bug in this skill's history was found by looking,
+not by testing.
+
+## Monkey C gotchas
+
+- Module-level functions take **no** visibility modifier. `private` and `hidden`
+  are class-only; at module scope they are syntax errors.
+- `dc.fillPolygon` wants `Array<[Numeric, Numeric]>`. Cast the literal:
+  `[[x, y], ...] as Array<[Numeric, Numeric]>`.
+- `getInitialView()` returns
+  `[WatchUi.Views] or [WatchUi.Views, WatchUi.InputDelegates]`.
+- `Application.Properties.getValue()` **throws** when a key is absent, which
+  happens on a fresh install before settings have ever been written. Wrap every
+  read with a default.
+- Integer division everywhere. Centring an odd width leaves a 1px skew — write
+  tests that allow it rather than forcing constants to stay even.
+
+## Reference watches and homages
+
+If reproducing a real object, get these right before anything else, because they
+are what makes it recognisable:
+
+- **Display polarity.** A 1970s LCD is *positive*: dark segments on a pale panel,
+  the inverse of every modern face. Getting this backwards turns a crystal into a
+  screen.
+- **Proportion.** Bezels on vintage digitals are thick; the window is smaller
+  than memory suggests.
+- **Where the legends sit** — maker's name on the bezel, not the glass.
+
+No system font is a segment display. If you need one, draw it: see
+`references/layout.md` for a working seven-segment renderer, including the ghost
+(unlit) segments that are most of what sells the effect.
+
+**Do not print a real brand on the face.** See `references/store.md`.

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/references/devices.md

@@ -0,0 +1,98 @@
+# Device support
+
+## Products, devices, and what "5 out of 5 built" means
+
+A `<iq:product>` in the manifest often covers several marketing variants that
+share hardware. Declaring `fenix6pro` alone produces `5 OUT OF 5 DEVICES BUILT`
+— fenix 6 Pro, 6 Sapphire, 6 Pro Solar, 6 Pro Dual Power, quatix 6. That is one
+layout, not five. Do not read the count as breadth.
+
+## Widening cheaply
+
+A face written against one resolution ports for free to every device sharing it —
+a manifest edit, no code change.
+
+```bash
+bin/ciq-devices --same-as fenix6pro
+```
+
+That prints the `<iq:product>` lines to paste, flags devices below your
+`minApiLevel`, and warns when launcher icon sizes differ.
+
+Representative clusters (installed SDK, mid-2026):
+
+| Resolution | Devices |
+| --- | --- |
+| 240x240 | 38 |
+| 390x390 | 22 |
+| 260x260 | 13 |
+| 454x454 | 12 |
+| 218x218 | 11 |
+| 240x400 | 9 (rectangular) |
+
+## Then actually build each one
+
+Compiling is the cheapest verification and it catches real problems:
+
+```bash
+for d in fenix6 fenix7 fr955 vivoactive4; do
+  monkeyc -f monkey.jungle -d $d -o bin/t-$d.prg -y $KEY -w -l 3 \
+    | sed "s/^/$d: /"
+done
+```
+
+Two things that surface here and nowhere else:
+
+**API level.** `ERROR: Device 'approachs62' does not support API Level '3.1.0'.`
+A device can share your resolution and still be excluded. Drop it, or lower
+`minApiLevel` and give up the APIs you were using.
+
+**Launcher icon size.** `WARNING: The launcher icon (40x40) isn't compatible with
+the specified launcher icon size of the device 'vivoactive4' (35x35). The image
+will be scaled.` Scaling blurs detail at a size where it is already marginal.
+Give those devices their own resource path:
+
+```
+# monkey.jungle
+base.resourcePath = resources
+
+# resources-35 is listed second so its drawables win.
+vivoactive4.resourcePath = $(base.resourcePath);resources-35
+legacyherofirstavenger.resourcePath = $(base.resourcePath);resources-35
+```
+
+with `resources-35/drawables/` holding both `drawables.xml` and the 35x35 PNG.
+
+## What does not port
+
+Compiling clean does **not** mean it looks right. It will compile and look wrong,
+which is worse than failing.
+
+Before declaring a device of a different size or shape:
+
+1. **Absolute pixel constants.** Anything like `const PANEL_X = 30` needs to
+   become a fraction of `dc.getWidth()`.
+2. **Round-bezel assumptions.** `halfWidthAt()` computes a curve that does not
+   exist on a rectangular screen and needlessly squeezes content; on 240x400 it
+   is badly wrong. Branch on `System.getDeviceSettings().screenShape`.
+3. **Font heights.** They differ between devices at the *same* resolution. Derive
+   everything (see `reference/layout.md`); a fixed Y that fits a 19px glyph
+   overflows a 24px one.
+4. **Sensor availability.** Body Battery and stress are absent on older and
+   cheaper devices. Guard with `Toybox has :SensorHistory` and degrade to `--`.
+
+If the layout is not resolution-aware, say so in the manifest so the next person
+does not "helpfully" add products:
+
+```xml
+<!-- Every product here is 260x260, the only resolution this face supports:
+     Layout uses absolute pixel constants and halfWidthAt() assumes a round
+     bezel. Another size or shape will compile and look wrong, not fail. -->
+```
+
+## Recommended order
+
+1. Ship one resolution, verified on your own wrist.
+2. Add the same-resolution family — biggest reach per unit of risk.
+3. Make `Layout` resolution-aware only if it gets traction. It is real work and
+   it risks the pixel-exact look you tuned.

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/references/display.md

@@ -0,0 +1,120 @@
+# The display
+
+Two hardware facts drive every colour decision. Both are invisible in the
+simulator, which renders on a backlit LCD and flatters everything.
+
+## Transflective MIP: brightness is reflectance
+
+Most fenix/Forerunner/Instinct screens are memory-in-pixel, **transflective, with
+no backlight**. Pixels reflect ambient light rather than emitting it. So a
+colour's brightness *is* how much light it returns to the eye.
+
+| Colour | Reflects |
+| --- | --- |
+| `0xFFFFFF` | all three channels — brightest available |
+| `0xAAAAAA` | about two-thirds of white |
+| `0x555555` | about a third |
+| `0x00FF00` | green only — roughly a third of white |
+
+**Consequence 1: large areas must be bright.** Choosing a photographically
+accurate mid-grey for the biggest region on the face makes the whole watch read
+as dim on the wrist while looking correct in the simulator. If a design has a
+large panel, `0xFFFFFF` is usually the right answer even when a reference
+photograph says otherwise.
+
+**Consequence 2: never colour the thing you need to read.** A saturated colour on
+a glyph reflects only its own channel, making the number you are trying to read
+the *dimmest* thing on screen. Put status colour on a chip, bar, or rule beside
+the value and keep the value white.
+
+If a user insists on coloured values, say once that it costs outdoor legibility,
+then do it. It is their watch.
+
+**Consequence 3: big saturated fills shout.** A colour that reads as informative
+at glyph size is overwhelming across a progress bar. Keep a separate pale tint
+for large fills:
+
+```monkeyc
+const READY   = 0x55FF55;   // status, at glyph size
+const FILL_OK = 0xAAFFAA;   // the same meaning, across a large area
+```
+
+## The 64-colour lattice
+
+Many devices quantise to 4 levels per channel: `0x00 / 0x55 / 0xAA / 0xFF`. A
+colour not already on the lattice is snapped at draw time, so **what you picked
+is not what ships**. Greys and golds drift most visibly.
+
+Useful quantisations:
+
+| Intent | Nearest lattice point | Reads as |
+| --- | --- | --- |
+| Gold `(212,175,90)` | `0xAAAA55` | olive/khaki |
+| Brighter gold | `0xFFAA55` | orange |
+| Amber warning | `0xFFAA00` | strong orange |
+| Sky blue | `0x55AAFF` | good |
+| Mid grey | `0xAAAAAA` | good |
+
+There is no good gold. Say so rather than iterating.
+
+Pin every palette constant with a test:
+
+```monkeyc
+const LEVELS = [0x00, 0x55, 0xAA, 0xFF];
+
+function quantizeChannel(value as Number) as Number {
+    var nearest = LEVELS[0];
+    var best = 256;
+    for (var i = 0; i < LEVELS.size(); i += 1) {
+        var d = (value - LEVELS[i]).abs();
+        if (d < best) { best = d; nearest = LEVELS[i]; }
+    }
+    return nearest;
+}
+
+function quantize(color as Number) as Number {
+    return (quantizeChannel((color >> 16) & 0xFF) << 16)
+         | (quantizeChannel((color >> 8) & 0xFF) << 8)
+         |  quantizeChannel(color & 0xFF);
+}
+
+function isLatticeExact(color as Number) as Boolean {
+    return quantize(color) == color;
+}
+```
+
+```monkeyc
+(:test)
+function everyPaletteColourSurvivesQuantization(logger as Logger) as Boolean {
+    var colors = [Palette.BG, Palette.VALUE, Palette.LABEL /* ... */];
+    for (var i = 0; i < colors.size(); i += 1) {
+        if (!Palette.isLatticeExact(colors[i])) { return false; }
+    }
+    return true;
+}
+```
+
+Also pin the *relationships*, which is what actually breaks:
+
+```monkeyc
+(:test)
+function panelIsLighterThanItsSegments(logger as Logger) as Boolean {
+    return Palette.PANEL > Palette.SEGMENT;
+}
+```
+
+## Colour discipline that survives contact with a wrist
+
+- Reserve colour for states worth interrupting a glance for. A green "50%"
+  battery is decoration that costs luminance and teaches the eye to ignore
+  colour.
+- Set thresholds against the device, not phone habits. A 14-day watch at 50% has
+  a week left; that is not a warning.
+- Prefer luminance hierarchy — label grey, value white — over hue.
+- One accent colour on the whole face, used once.
+
+## AMOLED devices
+
+Venu and newer devices are emissive and do not share these constraints, but they
+do have burn-in protection requirements and an always-on mode with a pixel budget.
+Do not carry MIP palette reasoning onto them unexamined.

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/references/layout.md

@@ -0,0 +1,224 @@
+# Layout
+
+Monkey C will happily draw at y=400 on a 260px screen. Nothing warns you; the
+pixels just do not exist. Almost every layout bug in this skill's history is a
+constant that was written down instead of measured.
+
+## Measure, never assume, font heights
+
+Real heights on fenix 6 Pro. They are larger than they look:
+
+| Font | Height |
+| --- | --- |
+| `FONT_XTINY` | 19 |
+| `FONT_TINY` | 29 |
+| `FONT_SMALL` | 32 |
+| `FONT_NUMBER_MEDIUM` | 74 |
+
+`FONT_NUMBER_MEDIUM` at 74px means a two-line time block is **148px of a 260px
+face** — 57% of the screen for four digits.
+
+These differ per device, so treat the table as an order-of-magnitude guide and
+call `dc.getFontHeight()` at draw time.
+
+To measure on a device you have not used, drop a `System.println` into
+`onUpdate`, build, push, and read `monkeydo`'s stdout:
+
+```monkeyc
+System.println("H xtiny=" + dc.getFontHeight(Graphics.FONT_XTINY)
+    + " small=" + dc.getFontHeight(Graphics.FONT_SMALL)
+    + " num=" + dc.getFontHeight(Graphics.FONT_NUMBER_MEDIUM));
+```
+
+Do this instead of guessing. It costs one build.
+
+## Derive the vertical stack at draw time
+
+```monkeyc
+function onUpdate(dc as Dc) as Void {
+    var labelH = dc.getFontHeight(Graphics.FONT_XTINY);
+    var valueH = dc.getFontHeight(Graphics.FONT_TINY);
+
+    var rowTop     = HEADER_Y + labelH + GAP;
+    var columnBottom = rowTop + (rows * (valueH + GAP));
+    var ruleY      = clampRuleY(columnBottom + GAP_ABOVE_RULE, labelH);
+    var footer1Y   = ruleY + GAP_BELOW_RULE;
+    var footer2Y   = footer1Y + labelH + GAP_BETWEEN_ROWS;
+    ...
+}
+```
+
+`Layout` holds gaps and ratios; the view holds the arithmetic. Keep `Dc` out of
+`Layout` so the geometry stays unit-testable.
+
+## Clamp, so the bottom cannot fall off
+
+Deriving is not enough. If everything above grows, the footer walks off the
+screen and vanishes silently. Reserve its space first and let the stack above
+give way:
+
+```monkeyc
+function clampRuleY(derived as Number, footerH as Number) as Number {
+    var reserved = (footerH * 2) + GAP_BELOW_RULE + GAP_BETWEEN_ROWS;
+    var maxRuleY = SCREEN - BOTTOM_MARGIN - reserved;
+    return derived > maxRuleY ? maxRuleY : derived;
+}
+```
+
+Pin it with a sweep, not a single case:
+
+```monkeyc
+(:test)
+function footerStaysOnScreenForAnyPlausibleFont(logger as Logger) as Boolean {
+    for (var labelH = 14; labelH <= 40; labelH += 1) {
+        for (var timeH = 40; timeH <= 120; timeH += 4) {
+            if (footerBottom(labelH, timeH / 2, timeH) >= Layout.SCREEN) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+```
+
+A single-value test passes with the font height you happened to assume. The sweep
+is what catches the device you have not tried.
+
+## Round screens
+
+The screen is a circle; the bounding box is a lie.
+
+```monkeyc
+// Widest half-chord at a given y.
+function halfWidthAt(y as Number) as Number {
+    var dy = y - CENTER;
+    var inside = (CENTER * CENTER) - (dy * dy);
+    return inside <= 0 ? 0 : Math.sqrt(inside).toNumber();
+}
+
+// Usable X corridor for a row, measured at whichever edge the curve cuts first.
+function rowXBounds(topY as Number, height as Number) as Array<Number> {
+    var worstY = topY < CENTER ? topY : topY + height;
+    var half = halfWidthAt(worstY) - MARGIN;
+    if (half < 0) { half = 0; }
+    return [CENTER - half, CENTER + half] as Array<Number>;
+}
+```
+
+**A row is cut at its lowest edge if below centre, its highest if above.** Using
+the row's top for a bottom row is the classic error — it reports space that is
+not there.
+
+**Rectangles fail at their corners, not their edges.** Checking the sides of a
+panel against `halfWidthAt` passes while the corners hang outside the bezel:
+
+```monkeyc
+function cornerInsideBezel(x as Number, y as Number) as Boolean {
+    var dx = x - CENTER;
+    var dy = y - CENTER;
+    return ((dx * dx) + (dy * dy)) < (CENTER * CENTER);
+}
+```
+
+**The bottom of a round face is narrow.** At y=246 on a 260px screen only ~110px
+of width remains. Two label/value pairs do not fit there; one does. Test for real
+width, not merely a non-negative corridor:
+
+```monkeyc
+(:test)
+function footerKeepsEnoughWidthForItsPair(logger as Logger) as Boolean {
+    var bounds = Layout.rowXBounds(footerY, footerH);
+    return (bounds[1] - bounds[0]) >= 90;
+}
+```
+
+## Seven-segment digits
+
+No system font is a segment display, and a rounded sans-serif `4` is the single
+thing that gives away a digital-watch homage. Draw them.
+
+```monkeyc
+module Seg7 {
+    const SEG_A = 0x01; const SEG_B = 0x02; const SEG_C = 0x04; const SEG_D = 0x08;
+    const SEG_E = 0x10; const SEG_F = 0x20; const SEG_G = 0x40;
+    const ALL = 0x7F;
+
+    //   aaaa
+    //  f    b
+    //   gggg
+    //  e    c
+    //   dddd
+    const DIGITS = [
+        SEG_A|SEG_B|SEG_C|SEG_D|SEG_E|SEG_F,      // 0
+        SEG_B|SEG_C,                              // 1
+        SEG_A|SEG_B|SEG_G|SEG_E|SEG_D,            // 2
+        SEG_A|SEG_B|SEG_G|SEG_C|SEG_D,            // 3
+        SEG_F|SEG_G|SEG_B|SEG_C,                  // 4
+        SEG_A|SEG_F|SEG_G|SEG_C|SEG_D,            // 5
+        SEG_A|SEG_F|SEG_G|SEG_E|SEG_C|SEG_D,      // 6
+        SEG_A|SEG_B|SEG_C,                        // 7
+        ALL,                                      // 8
+        SEG_A|SEG_B|SEG_C|SEG_D|SEG_F|SEG_G       // 9
+    ];
+
+    // Mitred ends, so segments interlock at the corners instead of merging
+    // into a solid block.
+    function horizontal(dc as Dc, x as Number, y as Number, w as Number, t as Number) as Void {
+        var h = t / 2;
+        dc.fillPolygon([
+            [x + h, y], [x + w - h, y], [x + w, y + h],
+            [x + w - h, y + t], [x + h, y + t], [x, y + h]
+        ] as Array<[Numeric, Numeric]>);
+    }
+
+    function vertical(dc as Dc, x as Number, y as Number, len as Number, t as Number) as Void {
+        var h = t / 2;
+        dc.fillPolygon([
+            [x, y + h], [x + h, y], [x + t, y + h],
+            [x + t, y + len - h], [x + h, y + len], [x, y + len - h]
+        ] as Array<[Numeric, Numeric]>);
+    }
+
+    // Both vertical runs span from their end of the cell to the centred middle
+    // bar: half the cell plus half a bar thickness.
+    function drawMask(dc as Dc, mask as Number, x as Number, y as Number,
+                      w as Number, h as Number, t as Number) as Void {
+        var mid = y + (h / 2) - (t / 2);
+        var right = x + w - t;
+        var vlen = (h / 2) + (t / 2);
+
+        if (mask & SEG_A) { horizontal(dc, x, y, w, t); }
+        if (mask & SEG_G) { horizontal(dc, x, mid, w, t); }
+        if (mask & SEG_D) { horizontal(dc, x, y + h - t, w, t); }
+        if (mask & SEG_F) { vertical(dc, x, y, vlen, t); }
+        if (mask & SEG_B) { vertical(dc, right, y, vlen, t); }
+        if (mask & SEG_E) { vertical(dc, x, mid, vlen, t); }
+        if (mask & SEG_C) { vertical(dc, right, mid, vlen, t); }
+    }
+}
+```
+
+**Draw the unlit segments.** A real module shows them faintly, so a `1` sits
+inside a visible `8`. This single detail is most of what makes drawn digits read
+as a crystal rather than a font. Draw the ghost with `ALL` first, then the value
+on top.
+
+Two things this costs you:
+
+- Ghosts destroy legibility below about 60px. At icon size, the faint `8` behind
+  a `1` wins and every digit reads as `8`. Omit them there.
+- Ghost colour must sit between panel and segment. Against a white panel,
+  `0x555555` ghosts compete with lit digits — use `0xAAAAAA`.
+
+Blank a leading zero by drawing only the ghost, not by drawing `0`. Return
+`null` from the digit provider so the drawing code can tell "blank" from "the
+digit nought" — they are different pictures.
+
+## Miscellaneous
+
+- Centring an odd width leaves a 1px skew from integer division. Write the test
+  to allow `<= 1` rather than forcing every constant to stay even.
+- Draw filled shapes rather than stroked outlines when the geometry has been
+  checked against a boundary: a stroke straddles its path, putting half its width
+  outside what you verified.
+- Order matters when compositing. Pasting a square image over a ring erases it.