fix(ui-macos): #185 CALayer shadow + visual_test infrastructure (v0.5.324)

CALayer shadows on macOS were invisible because set_shadow() never set
masksToBounds:false. iOS/tvOS/visionOS mirror impls all set it; macOS was
the lone outlier. One-line fix in widgets/mod.rs::set_shadow.

Also adds:
- docs/examples/ui/styling/visual_test.ts: comprehensive 13-section
  visual styling test (colors, borders, padding, shadow, gradient,
  opacity, typography, buttons, inputs, controls, image symbols,
  states, runtime colors)
- docs/examples/ui/styling/visual_test.spec.md: LLM-debuggable per-cell
  expected-values manifest with "Visible signature" strings for
  screenshot verification
- scripts/run_visual_test_check.sh: drift check that asserts the .ts's
  labeled() rows and the spec's '### N.' headers stay 1:1
- .github/workflows/test.yml: wire drift check into CI after the
  existing UI styling matrix step

Verified via 3-round shadow_repro.ts (high-contrast yellow shadow):
round 1 inconclusive low-contrast, round 2 confirmed missing, round 3
post-fix confirmed working. Web/wasm + iOS-sim cross-compile clean.

Author: proggeramlug

.github/workflows/test.yml

@@ -368,6 +368,18 @@ jobs:
           git diff --exit-code -- docs/src/ui/styling-matrix.md \
             || (echo "docs/src/ui/styling-matrix.md regenerated; commit the diff" && exit 1)
 
+      # Visual styling test ↔ spec consistency (#185 follow-up).
+      # `docs/examples/ui/styling/visual_test.ts` is the canonical
+      # comprehensive visual test app; `visual_test.spec.md` documents
+      # each cell's expected visible signature for human/LLM-aided
+      # screenshot verification. The two files must stay in lockstep
+      # — adding a row to the .ts without updating the spec silently
+      # breaks the verification flow. The actual cross-platform
+      # compile-test of visual_test.ts is handled by the existing
+      # run_doc_tests.sh loop downstream.
+      - name: Visual styling test ↔ spec consistency
+        run: ./scripts/run_visual_test_check.sh
+
       # Fastify end-to-end integration (#174): launches a Perry-compiled
       # Fastify server as a background process, curls four routes covering
       # simple GET, path params, POST with JSON body + reply.code(), and

CLAUDE.md

@@ -109,7 +109,7 @@ opt-level = "s"       # Optimize for size in stdlib
 opt-level = 3
 
 [workspace.package]
-version = "0.5.323"
+version = "0.5.324"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/PerryTS/perry"

Cargo.toml

@@ -754,6 +754,13 @@ pub fn set_shadow(
                 // already provides this layout-compatible struct.
                 let offset = objc2_core_foundation::CGSize::new(offset_x, offset_y);
                 let _: () = objc2::msg_send![layer, setShadowOffset: offset];
+                // CALayer shadows are clipped by `masksToBounds`. iOS
+                // sets this in its mirror impl; the macOS version was
+                // missing it — the bug visible in
+                // `docs/examples/ui/styling/visual_test.ts` section 4
+                // before this fix landed (FFI args correct per the IR
+                // dump but no visible shadow).
+                let _: () = objc2::msg_send![layer, setMasksToBounds: false];
             }
         }
     }

crates/perry-ui-macos/src/widgets/mod.rs

@@ -0,0 +1,249 @@
+# Visual styling test — verification spec
+
+Companion to `visual_test.ts`. This document describes every cell in
+the test app along with its **expected visual signature** so a tester
+(human or LLM) can mechanically compare a screenshot against
+expectations and flag regressions cell-by-cell.
+
+## How to use
+
+1. Compile + run the test on the platform you want to verify:
+   ```bash
+   ./target/release/perry compile docs/examples/ui/styling/visual_test.ts -o /tmp/styling_test
+   ./tmp/styling_test
+   ```
+2. Capture the window (any screenshot tool, or via geisterhand's
+   `/screenshot` endpoint where wired).
+3. Walk this spec top-to-bottom. For each cell, confirm the screenshot
+   matches the visible signature. Anything that doesn't match → file
+   an issue against the underlying styling matrix row.
+
+For LLM-assisted verification, send the screenshot + this file to
+the model and ask "for each row, list any cells that don't match
+their expected visible signature."
+
+## Window meta
+
+- **Title bar:** "Perry Styling Visual Test"
+- **Dimensions:** 880 × 940 (resizable on platforms that support it)
+- **Header:** large bold black "Perry Styling Visual Test" (20pt),
+  followed by a small gray subtitle, then a horizontal divider line.
+- **Body:** vertical stack of 13 numbered sections, each with a small
+  gray label above and a horizontal row of widgets below.
+
+## Section-by-section expectations
+
+### 1. Colors
+
+Five horizontally-arranged labels, all with white text, padding 8,
+border-radius 4. Every cell should be a clearly-distinct solid color:
+
+| # | Text | Expected background | Visible signature |
+|---|------|---|---|
+| 1 | `hex` | pure red `#FF0000` | white "hex" on FULL red box |
+| 2 | `named` | pure blue `#0000FF` | white "named" on FULL blue box |
+| 3 | `object` | medium green `(0, 0.6, 0, 1)` | white "object" on green box, slightly darker than pure green |
+| 4 | `alpha` | red @ 50% alpha — composited over window background | white "alpha" on PINK / muted-red box (alpha shows through) |
+| 5 | `runtime` | `#3B82F6` from a `themeBlue` variable | white "runtime" on bright cobalt-blue box (Phase C step 7 path) |
+
+If cell 5 renders as anything other than the same blue as cell 2 of
+gradient row, the runtime parseColor path is broken — cells 1-4 use
+compile-time, cell 5 uses runtime, both should produce identical
+visual results for the same color value.
+
+### 2. Borders + corners
+
+Four labels with transparent background + visible border, varying
+width and corner-radius:
+
+| # | Text | Border | Radius | Visible signature |
+|---|------|---|---|---|
+| 1 | `1px-4r` | thin black | slightly rounded | thin black outline, gentle corners |
+| 2 | `3px-12r` | medium blue | well-rounded | thicker blue outline, pronounced rounding |
+| 3 | `heavy` | thick red | square | bold red outline, sharp 90° corners |
+| 4 | `pill` | thin gray | very rounded | nearly pill-shaped, hairline outline |
+
+**Windows note:** issue [#210](https://github.com/PerryTS/perry/issues/210) — borders are stub-with-state on Windows
+(FFI accepts the params, no paint pass). Cells 1-4 may render as
+plain text labels with no visible border on Windows until #210
+lands. **GTK4:** all 4 should render correctly.
+
+### 3. Padding
+
+Two labels with `#EEE` light-gray background:
+
+| # | Text | Padding | Visible signature |
+|---|------|---|---|
+| 1 | `p:12` | uniform 12px | text centered with even gap on all sides |
+| 2 | `p:4-24` | top:4 right:24 bottom:4 left:24 | text vertically tight, wide horizontal margins |
+
+Cell 2's box should be visibly WIDER than cell 1 (more horizontal
+padding) but SHORTER (less vertical padding).
+
+### 4. Shadow
+
+Three light-gray labels with rounded corners + black/colored shadows.
+The shadow visibility test — if no shadow is visible, the platform's
+shadow path isn't wired.
+
+> **Note on bg color choice:** these cells use light gray `#F3F4F6` rather than
+> pure white intentionally. CALayer's drop shadow is visually invisible when
+> the card is the same color as the window background, even when the FFI is
+> correctly applied — the bug originally observed before the macOS
+> `setMasksToBounds: false` fix landed.
+
+| # | Text | Shadow color | Blur | Offset | Visible signature |
+|---|------|---|---|---|---|
+| 1 | `soft` | black @ 100% (full alpha) | 12 | (0, 4) | soft dark blur below light-gray box |
+| 2 | `hard` | black | 0 | (4, 4) | sharp dark offset to bottom-right of light-gray box |
+| 3 | `blue` | blue | 16 | (0, 6) | soft blue glow below light-gray box |
+
+**Windows note:** issue [#210](https://github.com/PerryTS/perry/issues/210) — shadow is stub-with-state on
+Windows. Cells 1-3 will look like plain white boxes with no shadow
+until #210 lands. **Android:** shadow direction may differ from
+iOS/macOS (Android's elevation derives direction from device-level
+light source, not the offset; the offset is intentionally ignored —
+same shadow color/blur should appear under all 3 cells).
+
+### 5. Gradient
+
+Three labels with linear gradients at different angles. White text:
+
+| # | Text | Gradient | Angle | Visible signature |
+|---|------|---|---|---|
+| 1 | `→` | blue→purple | 90° (left to right) | left edge blue, right edge purple, smooth horizontal blend |
+| 2 | `↓` | red→orange | 180° (top to bottom) | top edge red, bottom edge orange, smooth vertical blend |
+| 3 | `↘` | green→cyan | 135° (diagonal) | top-left green, bottom-right cyan, diagonal blend |
+
+### 6. Opacity
+
+Four `#3B82F6` blue labels at decreasing opacity:
+
+| # | Text | Opacity | Visible signature |
+|---|------|---|---|
+| 1 | `100` | 1.0 | full bright cobalt blue |
+| 2 | `75` | 0.75 | slightly faded, still clearly blue |
+| 3 | `50` | 0.5 | half-transparent, washed-out blue |
+| 4 | `25` | 0.25 | very faint, almost ghosted |
+
+**GTK4 / Windows:** opacity is wired on GTK4 (real `Widget::set_opacity`)
+but stub-with-state on Windows ([#210](https://github.com/PerryTS/perry/issues/210)) — Windows cells 2-4
+will all render at full opacity until #210 lands.
+
+### 7. Typography
+
+Seven text labels in a row, all black text, demonstrating font axes:
+
+| # | Text | Style | Visible signature |
+|---|------|---|---|
+| 1 | `normal` | regular 14pt | baseline reference |
+| 2 | `bold` | weight 700 | visibly heavier strokes than cell 1 |
+| 3 | `under` | underline | "under" with horizontal line below |
+| 4 | `strike` | strikethrough | "strike" with horizontal line through middle |
+| 5 | `12pt` | smaller | visibly smaller than cell 1 |
+| 6 | `18pt` | larger | visibly larger than cell 1 |
+| 7 | `mono` | monospaced | distinctive monospace glyph shapes |
+
+**Windows:** text decoration is stub-with-state ([#210](https://github.com/PerryTS/perry/issues/210)) — cells 3
+and 4 will render as plain "under" / "strike" without the line
+decoration until #210 lands.
+
+### 8. Buttons
+
+Four buttons in a row:
+
+| # | Label | Style | Visible signature |
+|---|------|---|---|
+| 1 | `Default` | none | platform-native button (rounded rect on macOS, square on Windows, etc.) |
+| 2 | `Styled` | blue bg, white text, 6r radius, 8 padding | flat blue rectangle, white "Styled" |
+| 3 | `Outlined` | 2px blue border, 6r, 8 padding | transparent rectangle with blue outline |
+| 4 | `Disabled` | enabled: false | grayed out, won't respond to clicks |
+
+### 9. Inputs
+
+Two text input controls. Verify both render at all + accept focus:
+
+| # | Type | Placeholder | Visible signature |
+|---|------|---|---|
+| 1 | `TextField` | "Type here…" | single-line input box with gray placeholder |
+| 2 | `SecureField` | "Password" | single-line input that masks typed chars |
+
+### 10. Controls
+
+Three control widgets:
+
+| # | Type | Setup | Visible signature |
+|---|------|---|---|
+| 1 | `Toggle` | label "Enable" | iOS-style switch (on macOS: checkbox-style; iOS: pill switch) |
+| 2 | `Slider` | min 0, max 100 | horizontal slider track with movable thumb |
+| 3 | `ProgressView` | indeterminate | spinning indicator OR horizontal bar showing progress |
+
+### 11. Image (SF Symbols)
+
+Three symbol icons. SF Symbols only render on Apple platforms; on
+GTK4 / Android / Web you'll get a fallback or empty space.
+
+| # | Symbol | Visible signature |
+|---|------|---|
+| 1 | `star.fill` | filled 5-pointed star |
+| 2 | `heart.fill` | filled heart shape |
+| 3 | `circle.fill` | filled circle |
+
+**Non-Apple platforms:** these may render as empty placeholders or
+default fallback icons. That's expected; Perry's image-by-symbol is
+SF-Symbols-specific.
+
+### 12. States
+
+Three labels demonstrating visibility flags:
+
+| # | Text | State | Visible signature |
+|---|------|---|---|
+| 1 | `visible` | normal | green box with white "visible" |
+| 2 | `hidden!` | hidden: true | **NOTHING — should NOT appear** |
+| 3 | `opacity-0` | opacity: 0 | **NOTHING — should NOT appear** (or invisible blue box that takes layout space) |
+
+If cells 2 or 3 are visible, the state-based hiding is broken on
+that platform. Note: cell 3 (`opacity: 0`) may still occupy layout
+space on some backends (the box is invisible but pushes siblings).
+That's correct behavior — opacity-0 ≠ hidden.
+
+### 13. Runtime colors
+
+Two runtime-resolved color cells (Phase C step 7 path):
+
+| # | Text | Color source | Visible signature |
+|---|------|---|---|
+| 1 | `var-hex` | `themeBlue` = `"#3B82F6"` | white text on cobalt-blue box (matches color row cell 5) |
+| 2 | `var-bad` | `themePurple` = `"rebeccapurple"` (NOT a Perry-supported named color) | white text on box with **fallback color** — black with alpha 1.0 because `parse_css_color` returns None for unknown named colors and the runtime returns 0.0 for r/g/b channels and 1.0 for alpha (see `crates/perry-runtime/src/color_parse.rs::js_color_parse_channel`) |
+
+If cell 2 renders as the actual purple color of `rebeccapurple`,
+that means the runtime path supports MORE named colors than the spec
+documents (good — file a docs update). If cell 2 renders as
+something else entirely, the runtime path is broken.
+
+## Per-platform expected status
+
+Platform → Expected sections rendering correctly, given the matrix
+state at v0.5.310+:
+
+| Platform | Sections expected fully ✓ | Sections expected ✗ (with reason) |
+|----------|--------------------------|-----------------------------------|
+| **macOS / iOS / tvOS / visionOS / watchOS** | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 | none |
+| **Android** | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13 | 11 (no SF Symbols), 4 (shadow direction may differ — offset ignored on Android by design) |
+| **GTK4** | 1, 2, 3, 5, 6, 7, 9, 10, 12, 13 | 4 (some cells may be flat — depends on GTK theme), 8 (cell 3 outlined button may not show border due to [#202](https://github.com/PerryTS/perry/issues/202) `widget.on_click` etc gaps), 11 (no SF Symbols) |
+| **Windows** | 1, 3, 5, 7 (cells 1, 2, 5, 6, 7), 9, 10, 12 (cell 1), 13 cell 1 | 2 (border stubs), 4 (shadow stubs), 6 (opacity stubs), 7 cells 3-4 (text decoration stubs), 8 cell 3 (border stub) — all blocked by [#210](https://github.com/PerryTS/perry/issues/210) |
+| **Web** | 1, 2, 3, 4, 5, 6, 7, 9, 10, 12, 13 | 11 (no SF Symbols, fallback may show empty boxes) |
+
+## When something fails
+
+If a cell doesn't match its visible signature on a platform where
+the matrix says it should:
+
+1. Confirm the matrix entry: `./target/debug/styling-matrix --gen` then
+   inspect `docs/src/ui/styling-matrix.md` for the relevant prop row.
+2. If matrix says `Wired` but visual fails → file a new issue
+   referencing this spec section + the platform.
+3. If matrix says `Stub` (Windows deferred-paint family) → expected,
+   tracked in [#210](https://github.com/PerryTS/perry/issues/210).
+4. If matrix says `Missing` (GTK4 4 rows) → expected, tracked in [#202](https://github.com/PerryTS/perry/issues/202).