Prune and tighten comments; fix stale comments and docs

Audit every code comment and markdown doc against the project's comment
philosophy: keep only math, non-obvious algorithms, cited constants, and
genuine gotchas; make every comment standalone and current-solution-only.

- Fix out-of-sync comments: Crop's "unit circle" (the crop radius is
  viewport.scale - 1, not 1), Spectrum's stale "(replaces atan2)", and the
  pebble plan's single-band render() description (render now supersamples).
- Remove trivial comments that restate the code: test-assertion narration,
  doc-comments echoing the symbol name, the duplicated localStorage-catch
  notes, and textbook lerp citations.
- Shorten verbose doc/module comments while keeping their load-bearing
  gotchas (wasm32 overflow guard, arena alignment, dither error-buffer
  invariant, downsample in-place safety).
- Trim docs/pebble-port-plan.md: drop duplicated binary-model/risk prose and
  a boilerplate C listing.
- Add 14"/16" wallpaper export examples to the README.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

Author: clebert

README.md

@@ -49,3 +49,13 @@ zig-out/bin/png 1024 7 14 logo.png --grain --supersample
 zig build png -Doptimize=ReleaseFast && \
 zig-out/bin/png 260 7 14 pebble.png --dither --supersample
 ```
+
+```bash
+zig build png -Doptimize=ReleaseFast && \
+zig-out/bin/png 1964 7 14 wallpaper-14-inch.png --grain --supersample
+```
+
+```bash
+zig build png -Doptimize=ReleaseFast && \
+zig-out/bin/png 2234 7 14 wallpaper-16-inch.png --grain --supersample
+```

bin/png/main.zig

@@ -18,8 +18,7 @@ pub fn main(init: std.process.Init) !void {
 
     var config = try lib.Config.init(allocator);
 
-    // The config default may enable grain; the PNG tool ignores it and applies a
-    // texture only when explicitly requested via --grain or --dither.
+    // Ignore config default; apply texture only on --grain/--dither.
     config.texture = if (args.dither) .dither else if (args.grain) .grain else .none;
 
     config.supersample_enabled = args.supersample;
@@ -66,7 +65,7 @@ const Args = struct {
 fn parseArgs(process_args: std.process.Args) ?Args {
     var arguments = process_args.iterate();
 
-    _ = arguments.next(); // skip program name
+    _ = arguments.next();
 
     var positional: [4][]const u8 = undefined;
     var positional_count: usize = 0;

bin/png/png.zig

@@ -1,5 +1,4 @@
-// PNG encoder that compresses the image data with std.compress.flate.Compress,
-// the deflate compressor introduced in Zig 0.16.0, at its best level.
+// PNG encoder; compresses image data with deflate at its best level.
 
 const std = @import("std");
 
@@ -69,8 +68,7 @@ fn filterScanlines(
     return data;
 }
 
-/// Compresses data into a zlib stream (RFC 1950) using deflate at the best
-/// compression level. The returned slice is owned by the caller.
+/// Compresses data into a zlib stream RFC 1950. Returned slice owned by caller.
 fn zlibDeflate(allocator: std.mem.Allocator, data: []const u8) ![]u8 {
     const window = try allocator.alloc(u8, std.compress.flate.max_window_len);
 

bin/wasm/main.zig

@@ -3,12 +3,9 @@ const std = @import("std");
 const lib = @import("lib");
 
 comptime {
-    // render() returns a pointer that JS reinterprets as a flat RGBA byte buffer
-    // (a Uint8ClampedArray over WASM memory; see src/renderer.ts). That contract
-    // requires lib.Srgb to be exactly 4 bytes laid out as r, g, b, a with no
-    // padding. lib.Srgb has the default (auto) layout, which the language does
-    // not guarantee — pin the assumption here so a layout change fails the build
-    // instead of silently producing garbled pixels.
+    // JS reads render()'s result as a flat RGBA Uint8ClampedArray (src/renderer.ts),
+    // so Srgb must be exactly r, g, b, a with no padding. Auto layout does not
+    // guarantee this, so pin it:
     std.debug.assert(@sizeOf(lib.Srgb) == 4);
     std.debug.assert(@offsetOf(lib.Srgb, "r") == 0);
     std.debug.assert(@offsetOf(lib.Srgb, "g") == 1);
@@ -44,12 +41,9 @@ fn getConfig(config_json_byte_length: u32) ?lib.Config {
     return cached_config;
 }
 
-// A single grow-only arena for the render buffers, backed directly by
-// @wasmMemoryGrow. Growing by exact page counts (rather than through the general
-// allocator, which rounds large allocations up to a power of two) lets a native
-// full-resolution frame fit tightly — e.g. a 6K canvas needs ~407 MB, not ~642 MB.
-// One contiguous region reused across frames means peak memory equals the largest
-// frame ever rendered, with no fragmentation or resize accumulation.
+// A single grow-only contiguous arena backed by @wasmMemoryGrow, reused across
+// frames. Exact page-count growth avoids the allocator's power-of-two rounding so a
+// native full-res frame fits tightly (a 6K canvas takes ~407 MB, not ~642 MB).
 var arena_base: usize = 0;
 var arena_bytes: usize = 0;
 var arena_initialized: bool = false;
@@ -92,19 +86,15 @@ export fn render(
 
     const supersample_factor = lib.frame.supersampleFactor(config);
 
-    // usize is u32 on wasm32 and this module is built without runtime safety, so the
-    // buffer-size products below would wrap silently for an oversize frame, under-sizing
-    // the arena while the slices still span the true pixel count — a heap overflow. Reject
-    // any frame whose arena footprint does not fit usize; the JS caller treats a null return
-    // as "render failed, keep the previous frame".
+    // usize is u32 on wasm32 and this module runs without runtime safety, so an oversize
+    // frame would wrap these size products silently and under-size the arena (a heap
+    // overflow). Use checked arithmetic and return null on overflow.
     const pixel_count = std.math.mul(usize, image_width, image_height) catch return null;
     const supersampled_count = std.math.mul(usize, pixel_count, supersample_factor * supersample_factor) catch return null;
     const error_count = lib.dither.errorBufferSize(image_width);
 
-    // Lay the three buffers out consecutively in the arena: Linear (16 B, the strictest
-    // alignment) first, then Srgb (4 B), then the f32 error rows — each offset is a multiple
-    // of the next type's size, so every slice stays naturally aligned. The Linear scratch
-    // holds the full supersampled render; downsampling rewrites its front in place.
+    // Lay the buffers out by descending alignment so every offset stays naturally
+    // aligned: Linear (16 B) first, then Srgb (4 B), then the f32 error rows.
     const linear_bytes = std.math.mul(usize, supersampled_count, @sizeOf(lib.Linear)) catch return null;
     const srgb_bytes = std.math.mul(usize, pixel_count, @sizeOf(lib.Srgb)) catch return null;
     const error_bytes = std.math.mul(usize, error_count, @sizeOf(f32)) catch return null;

docs/pebble-port-plan.md

@@ -19,10 +19,11 @@ export** binary (`bin/png/`). Two properties of the library make a Pebble port r
   Floyd–Steinberg error diffusion — its only state is a small two-row error buffer carried forward
   between strips; see [the Pebble dither](#dither-palette).
 
-`lib/frame.zig`'s `render()` renders the **full image as a single band**
-(`image.band(Linear, buffer, image.height, 0)`), and both shells call it that way. Driving the
-pipeline strip-by-strip on-device is therefore _new shell code_, not new library code — the banded
-primitives already exist and are tested.
+`lib/frame.zig`'s `render()` renders the whole frame in one shot: it builds a supersampled band
+(`supersampled.band(Linear, linear_buffer, supersampled.height, 0)`), runs `Watchface.render` into
+it, box-averages it down, then constructs the target-resolution band over the front of the same
+buffer. Driving the pipeline strip-by-strip on-device is therefore _new shell code_, not new library
+code — the banded primitives already exist and are tested.
 
 ## Feasibility
 
@@ -59,7 +60,7 @@ approach has direct prior art.
 1. Whether Zig 0.16 / LLVM emits relocations for `thumbv7m`/`thumbv7em` that the Pebble app loader
    applies correctly for any mutable globals/statics. Build a minimal Zig-on-Pebble proof first and
    keep global state at zero.
-2. Soft-float f32 plus scalarized `@Vector` SIMD (≈59 uses across `lib/`; neither Cortex-M4F nor
+2. Soft-float f32 plus scalarized `@Vector` SIMD (used throughout `lib/`; neither Cortex-M4F nor
    base Cortex-M33 has packed SIMD) — code size and render time within the budget. Fine in principle
    for a once-per-minute redraw, but must be measured on the emulator.
 3. `compiler_rt` soft-float routines linking against newlib-nano without duplicate `__aeabi_*`
@@ -85,13 +86,10 @@ rectangular 64-colour model is a straightforward second target.
 
 Notes:
 
-- The SoC is the **SiFli SF32LB52J**, a big.LITTLE pair of Cortex-M33 STAR-MC1 cores (240 MHz HCPU +
-  24 MHz LCPU, 512 KB SRAM). The 16 MB PSRAM exists on-chip but is **not enabled in PebbleOS**, so
-  don't count on it.
-- Round 2 is **real and pre-orderable** (shown at CES, January 2026) but **has not shipped to
-  customers**. Plan to validate entirely on the **emulator**.
-- **FPU:** the Cortex-M33 FPU is optional and not confirmed for the SF32LB52J from primary sources —
-  but it's **moot**, because the Pebble app ABI is soft-float regardless (see below).
+- The 16 MB PSRAM exists on-chip but is **not enabled in PebbleOS**, so don't count on it. Round 2
+  has not shipped to customers (2026-05-30); plan to validate entirely on the **emulator**.
+- **FPU:** the Cortex-M33 FPU is optional and unconfirmed for the SF32LB52J, but **moot** — the
+  Pebble app ABI is soft-float regardless (see below).
 
 ### Platform names vs. board codenames
 
@@ -153,25 +151,21 @@ The Floyd–Steinberg dither's only extra scratch is a two-row error buffer
 (`dither.errorBufferSize(width)` = `width × 3 × 2` f32; ~6 KB at 260 px), carried forward between
 strips (see below).
 
-Supersampling (`config.supersample_enabled`; factor `N = 2` via `frame.supersampleFactor`) renders
-the continuous image at `N×` and box-averages it down in linear light before quantizing, which
-antialiases the prism, hand, and rainbow edges. The downsample is purely local — each output pixel
-reads only its own `N × N` source block — so it stays band-compatible: a `band_height = 1` strip
-needs `N` supersampled rows of `N × width` linear scratch (`N² × width × 16 B`; ~16 KB at `N = 2`,
-260 px wide), still far under budget. The cost is render time, which grows with `N²` — measure it on
-the emulator against the once-a-minute redraw before enabling it.
+Supersampling (`config.supersample_enabled`; factor `N = 2` via `frame.supersampleFactor`)
+antialiases the prism, hand, and rainbow edges. It stays band-compatible because each output pixel
+reads only its own `N × N` source block, so a `band_height = 1` strip needs only `N² × width × 16 B`
+of linear scratch (~16 KB at `N = 2`, 260 px); the cost is render time, which grows with `N²` —
+measure it on the emulator.
 
 The **framebuffer itself is owned by the firmware** — `graphics_capture_frame_buffer` hands you the
 real 8-bit `GColor8` buffer (~66 KB for 260×260), which the OS already allocated. The app only pays
 for the band scratch above, comfortably within budget.
 
-The Floyd–Steinberg dither carries error between rows, so it is **order-dependent**: strips must be
-applied top-to-bottom and the caller must persist the two-row error buffer across `dither.apply`
-calls (it is zeroed on the first band, where `y_offset == 0`). Done that way, strip rendering
-reproduces the single-pass output bit-for-bit (proven by the
-`multi-band apply matches single-band apply` test). This is the one cross-band dependency the
-renderer has; everything else is per-pixel. Drive a few `band_height` values and pick the smallest
-that renders fast enough.
+The dither is the renderer's one cross-band dependency (top-to-bottom order, persisted error buffer;
+see [the Pebble dither](#dither-palette)); everything else is per-pixel. Driven that way, strip
+rendering reproduces the single-pass output bit-for-bit (the
+`multi-band apply matches single-band apply` test). Drive a few `band_height` values and pick the
+smallest that renders fast enough.
 
 ## Pixel format: `GColor8`
 
@@ -347,16 +341,14 @@ each strip into the framebuffer via `gbitmap_get_data_row_info`.
 
 ## C app shell
 
-Standard Pebble watchface lifecycle:
+Standard Pebble watchface lifecycle (`window_create` → a `Layer` with an update proc →
+`tick_timer_service_subscribe(MINUTE_UNIT, …)` whose handler calls `layer_mark_dirty` →
+`app_event_loop`); scaffold it from `pebble new-project`. The only port-specific part is the band
+loop in the update proc:
 
 ```c
-#include <pebble.h>
-
 extern void pebbleRenderBand(uint8_t *out, uint16_t band_index, uint8_t hour, uint8_t minute);
 
-static Window *s_window;
-static Layer  *s_canvas;
-
 static void canvas_update_proc(Layer *layer, GContext *ctx) {
     GBitmap *fb = graphics_capture_frame_buffer(ctx);
     if (!fb) return;
@@ -376,30 +368,6 @@ static void canvas_update_proc(Layer *layer, GContext *ctx) {
 
     graphics_release_frame_buffer(ctx, fb);
 }
-
-static void tick_handler(struct tm *tick_time, TimeUnits units) {
-    layer_mark_dirty(s_canvas);
-}
-
-static void window_load(Window *window) {
-    Layer *root = window_get_root_layer(window);
-    s_canvas = layer_create(layer_get_bounds(root));
-    layer_set_update_proc(s_canvas, canvas_update_proc);
-    layer_add_child(root, s_canvas);
-}
-
-static void window_unload(Window *window) { layer_destroy(s_canvas); }
-
-int main(void) {
-    s_window = window_create();
-    window_set_window_handlers(s_window, (WindowHandlers){
-        .load = window_load, .unload = window_unload,
-    });
-    window_stack_push(s_window, true);
-    tick_timer_service_subscribe(MINUTE_UNIT, tick_handler);
-    app_event_loop();
-    window_destroy(s_window);
-}
 ```
 
 ## Build integration
@@ -478,30 +446,21 @@ band-by-band and `pebble screenshot` to compare against the PNG export.
 
 ## Open questions
 
+The relocation, soft-float perf/size, and `compiler_rt` linker risks are tracked in
+[Risks to retire early](#feasibility). The remaining open questions:
+
 - **Exact app build flags.** Read the installed SDK `waftools` for the precise `-mcpu`, `-mthumb`,
   `-fPIC`/`-fPIE`, `-mfloat-abi=soft`, `-msingle-pic-base`/`-mpic-register` — don't infer the PIC
   model from ARM convention.
-- **Relocations.** Empirically confirm Zig 0.16/LLVM emits data relocations the Pebble loader
-  applies correctly for `thumbv7m`/`thumbv7em` under `relocation-model=pic`. Build a minimal proof
-  first.
-- **Performance & size.** Measure soft-float render time and `.pbw` code/heap size on the
-  `gabbro`/`emery` emulator with `@Vector` ops scalarized, against the ~128 KB budget.
-- **Linker hygiene.** Confirm `compiler_rt` soft-float routines link against newlib-nano with no
-  duplicate `__aeabi_*` symbols.
 - **Manifest.** Confirm the exact `sdkVersion` string and `targetPlatforms` list the appstore
   accepts for a 4.9.x watchface; re-read per-app heap numbers from PebbleOS headers.
 - <a id="panel-gamma"></a>**Panel gamma — mostly resolved; not a blocker.** `GColor8` is a _nominal_
-  colour space: levels expand linearly to {0, 85, 170, 255} (no gamma), and the QEMU emulator
-  renders them linearly (`* 255 / 3`, no curve), so the dither — which quantizes in the sRGB domain
-  assuming the four levels are evenly spaced — is **exactly** emulator-accurate. PebbleOS adds
-  **no** gamma/colour-correction LUT for `getafix`/`obelix` — the SiFli driver
-  (`src/fw/drivers/display/sf32lb/display_jdi.c`) only does a mechanical 222→332 bit-repack (its
-  LCDC layer is `RGB332`); the `GColor8`/ARGB2222 model is identical to `basalt`/`chalk`. The
-  **only** residual unknown is the physical reflective JDI panel + the closed SiFli vendor HAL
-  (`bf0_hal_lcdc.c`), measurable only on real hardware. If its response diverges from sRGB it
-  degrades dither **quality** (the threshold lands at slightly wrong brightnesses — most visible on
-  the rainbow gradient), never output validity; the fix applies a correction curve before
-  quantization. So it cannot gate pre-hardware work.
+  colour space (levels expand linearly to {0, 85, 170, 255}, no gamma) and QEMU renders them
+  linearly, so the sRGB-domain dither is **exactly** emulator-accurate; PebbleOS adds no
+  gamma/colour LUT for `getafix`/`obelix`. The only residual unknown is the physical reflective JDI
+  panel's response, measurable only on hardware — and a divergence degrades dither **quality**, not
+  validity (fixable with a correction curve before quantization), so it can't gate pre-hardware
+  work.
 - **Shipping reality.** Confirm Round 2 hardware actually ships before relying on anything beyond
   the emulator.
 

index.html

@@ -137,8 +137,7 @@
         left: 0;
         width: 100%;
         height: 100%;
-        /* The backing store is antialiased at device resolution; "pixelated" would
-           nearest-neighbor fractional-DPI/zoom scaling and reintroduce aliasing. */
+        /* Backing store is antialiased at device resolution; "pixelated" would nearest-neighbor fractional-DPI/zoom scaling and reintroduce aliasing. */
         image-rendering: auto;
       }
 

lib/Clock.zig

@@ -8,8 +8,8 @@ const vector = @import("vector.zig");
 
 const Self = @This();
 
-const hour_arc: f32 = std.math.pi / 6.0; // 2π/12 = π/6 ≈ 30° (one hour moves 30°)
-const apex_angle: f32 = -std.math.pi / 2.0; // −π/2 (−90°, 12 o'clock)
+const hour_arc: f32 = std.math.pi / 6.0; // 30° per hour-step on the dial
+const apex_angle: f32 = -std.math.pi / 2.0; // 12 o'clock (apex, top of dial)
 const rainbow_max_spread_radians: f32 = std.math.pi / 6.0;
 
 prism: Prism,

lib/Crop.zig

@@ -85,8 +85,7 @@ fn antialiasAtBoundary(
 }
 
 fn antialiasNearEdge(self: Self, row: []Srgb, center_x: f32, dy: f32, radius: f32) void {
-    // For rows just outside the circle, find the horizontal range where
-    // pixels have partial coverage (top/bottom of the circle).
+    // Rows just outside the circle still have partially covered pixels near the top/bottom arc.
     const outer = radius + 0.5;
     const dx_max_squared = outer * outer - dy * dy;
     if (dx_max_squared < 0.0) return;
@@ -142,10 +141,10 @@ test "apply sets pixels outside circle to outside color" {
 
     crop.apply(band, viewport);
 
-    // Corner pixel (0,0) is outside the unit circle — should be white
+    // Corner pixel (0,0) is outside the crop circle — should be white
     try std.testing.expectEqual(Srgb.white, buffer[0]);
 
-    // Center pixel (5,5) is inside the unit circle — should stay black
+    // Center pixel (5,5) is inside the crop circle — should stay black
     try std.testing.expectEqual(Srgb.black, buffer[5 * 10 + 5]);
 }
 
@@ -160,10 +159,8 @@ test "apply sets transparent outside color" {
 
     crop.apply(band, viewport);
 
-    // Corner pixel should be transparent
     try std.testing.expectEqual(@as(u8, 0), buffer[0].a);
 
-    // Center pixel should remain opaque (default alpha=255)
     try std.testing.expectEqual(@as(u8, 255), buffer[5 * 10 + 5].a);
 }
 
@@ -178,13 +175,11 @@ test "apply handles wide image" {
 
     crop.apply(band, viewport);
 
-    // Far left pixel (0,5) is outside circle in a wide image (circle radius = 5)
+    // Far left pixel (0,5) is outside the crop circle in this wide image
     try std.testing.expectEqual(Srgb.white, buffer[5 * 20 + 0]);
 
-    // Far right pixel (19,5) is also outside
     try std.testing.expectEqual(Srgb.white, buffer[5 * 20 + 19]);
 
-    // Center pixel (10,5) is inside
     try std.testing.expectEqual(Srgb.black, buffer[5 * 20 + 10]);
 }
 
@@ -209,14 +204,13 @@ test "multi-band crop matches single-band crop" {
 
     const crop = Self{ .outside_color = .{ .r = 20, .g = 30, .b = 40 } };
 
-    // Reference: single-band (full height)
     var reference = input;
 
     const full_band = try image.band(Srgb, &reference, height, 0);
 
     crop.apply(full_band, viewport);
 
-    // Test with band heights: 1 (extreme), 2 (even), 3 (odd), 4 (even), 8, 16
+    // Cover extreme (1), odd, and even band heights
     const band_heights = [_]usize{ 1, 2, 3, 4, 8, 16 };
 
     for (band_heights) |band_height| {
@@ -265,14 +259,11 @@ test "antialias produces intermediate alpha at circle edge" {
 
     crop.apply(band, viewport);
 
-    // Center pixel should remain fully opaque
     try std.testing.expectEqual(@as(u8, 255), buffer[10 * 20 + 10].a);
 
-    // Corner pixel should be fully transparent
     try std.testing.expectEqual(@as(u8, 0), buffer[0].a);
 
-    // Find an edge pixel with intermediate alpha (proves AA is working).
-    // Scan the middle row for a pixel with 0 < alpha < 255.
+    // An edge pixel with 0 < alpha < 255 proves antialiasing ran.
     var found_intermediate = false;
 
     for (0..20) |x| {