Skip to content

Liquid Glass and Apple Music touches for the Spotify iOS app. A GPL-3.0 fork of spoti.pw 0.21.1.

C

chore: agent skills for Liquid Glass in UIKit, phone checks and clean-room reads of upstream

My-Name-Is-Jeffaf9a2bf99112
diff --git a/.agents/skills/README.md b/.agents/skills/README.md
index 82989088..215aadfd 100644
--- a/.agents/skills/README.md
+++ b/.agents/skills/README.md
@@ -4,14 +4,16 @@ Skills for agents working on the mod. Each directory is one skill, a `SKILL.md`
reads. `.claude/skills/` links each one back here, so Claude Code and the agents that read
`.agents/skills/` load the same copy.
- liquid-glass/ Liquid Glass APIs, migration and pitfalls; SwiftUI first, with the UIKit bridge
- (UIGlassEffect in a UIVisualEffectView), which is what the tweak builds on
+ liquid-glass/ Liquid Glass APIs, migration and pitfalls; SwiftUI first, with UIKit in
+ references/uikit.md, which is what the tweak builds on
apple-hig/ design review against Apple's Human Interface Guidelines, 122 pages under
references/hig/, liquid-glass.md, materials.md, tab-bars.md and motion.md among them
apple-design/ Designing Fluid Interfaces: springs by damping and response, velocity handoff,
momentum projection, rubber-banding, interruptible transitions, materials
review-animations/ a strict review of motion code, `/review-animations`; STANDARDS.md holds the values
animation-vocabulary/ the name of a motion effect you can describe but not name
+ phone-check/ install a build on the phone, drive it, take screenshots, read the tree and log
+ clean-room-describer/ learn what upstream changed or what its users report, as behavior only
The motion skills write their examples in CSS and JavaScript. The rules carry over to UIKit as they
are: a spring is `-[UISpringTimingParameters initWithDampingRatio:initialVelocity:]` on a
@@ -20,7 +22,8 @@ is `UIAccessibilityIsReduceMotionEnabled()`.
## Where they come from
-Copied unchanged unless noted. To update one, copy the upstream directory over it and redo the note.
+`phone-check` and `clean-room-describer` are Vitrine's own. The rest are
+copied unchanged unless noted. To update one, copy the upstream directory over it and redo the note.
| Skill | Upstream | Commit | License |
| --- | --- | --- | --- |
@@ -30,6 +33,10 @@ Copied unchanged unless noted. To update one, copy the upstream directory over i
| `review-animations` | [emilkowalski/skills](https://github.com/emilkowalski/skills) `skills/review-animations` | `85e8e23` | MIT, `LICENSE` beside it |
| `animation-vocabulary` | [emilkowalski/skills](https://github.com/emilkowalski/skills) `skills/animation-vocabulary` | `85e8e23` | MIT, `LICENSE` beside it |
+`liquid-glass` adds `references/uikit.md`, written here from the iOS SDK headers and `Core/SGGlass.m`.
+It also links that file from `SKILL.md` and `references/api-reference.md`, and changes the bridge's bare
+`UIGlassEffect()` to `UIGlassEffect(style: .regular)`, because a bare init draws a plain blur.
+
`apple-hig` is named `apple-design` upstream; its `name:` was changed so it does not collide with
Emil Kowalski's `apple-design`. `node .agents/skills/apple-hig/scripts/pull-hig.mjs` pulls the
guideline pages again from developer.apple.com.
diff --git a/.agents/skills/clean-room-describer/SKILL.md b/.agents/skills/clean-room-describer/SKILL.md
new file mode 100644
index 00000000..ed1e1045
--- /dev/null
+++ b/.agents/skills/clean-room-describer/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: clean-room-describer
+description: >
+ Learn what upstream spoti.pw (github.com/skopevoj/spoti.pw) changed or what its users report, without
+ anyone on Vitrine seeing upstream code. Use when the user asks about an upstream issue, pull request,
+ release or feature, or wants to know whether Vitrine needs something upstream did.
+---
+
+# Clean-room describer
+
+Upstream is under a license that does not allow reuse, so Vitrine is written clean room. Whoever implements
+must never see upstream code. One agent, the describer, reads upstream and hands back behavior only.
+
+## The rule
+
+- Implementers, including you, never read upstream code, diffs, the clone at
+ `/Users/r/GitRepositories/spoti.pw-beta` or anything in `/Users/r/temp`, and never decompile an upstream
+ build.
+- The describer reads issues, pull requests, release notes, screenshots and videos, and diffs only to
+ understand behavior. It writes what a user sees and under which conditions, never code, upstream's own
+ names for functions, variables, files or constants, or a paraphrase close enough to rebuild the code.
+- Spotify's classes and selectors and Apple's API names are facts about Spotify and iOS. The describer may
+ name them.
+
+## Dispatch
+
+Start a `general-purpose` agent with the Agent tool. It needs `gh` with the sandbox off; inside it, `gh`
+fails on TLS. Give it:
+
+1. The rule above, word for word.
+2. The exact items: issue or PR numbers, a release tag, or "open issues and those closed in the last N
+ weeks".
+3. What to report for each:
+ - The symptom, steps to reproduce, and conditions (device, iOS, Spotify version, redesign or native look).
+ - Expected against actual, and any timing measured from a video.
+ - Status, and any cause the maintainer stated, in behavior terms.
+ - For a PR: what changes for the user, which Spotify classes or system mechanisms are involved, and the
+ caveats.
+ - For a PR with several commits, how the behavior changed from commit to commit, above all a limit, a
+ guard or a cleanup added and later removed, and the reason given, if any. The connect relay was built
+ from what merged, and the merged version had dropped the earlier limit of one round per second. Nobody
+ noticed until the phone showed about fifty answers a second.
+ - The numbers in the behavior, with their units: rates, intervals, timeouts, caps, sizes, retry counts and
+ backoff.
+ - What the behavior costs while it runs: how often it does work (timers, polling, a round per event),
+ network traffic, CPU, background work, and the logging it does. State plainly when the source gives no
+ limit on any of these.
+ - Defaults and controls: whether it is on by default, whether a setting turns it off, and what a user
+ loses with it off.
+4. Where to write: a file in the session's scratchpad, also returned as its final answer, under a word
+ limit (about 900 for a survey, 1200 for detail).
+5. That it writes nothing into the repo, and keeps raw dumps out of the report. Issue bodies can carry
+ tokens or keys; raw dumps stay in the scratchpad and are never passed on or committed.
+
+To follow up on the same items, send the describer another message with SendMessage instead of starting a
+new agent, so it keeps what it already read.
+
+## After the report
+
+- Read only the report, never the raw dumps beside it.
+- Check each item against Vitrine yourself: grep `git log` for the fix by its behavior, then read our code.
+ Many upstream bugs are already fixed here under our own commit.
+- A spec built from the report keeps its numbers, its costs and the limits upstream removed, each as a point
+ for the implementer to decide, never dropped silently.
+- What Vitrine still needs becomes a behavior spec in `notes/` (gitignored, so it stays on this Mac, as
+ `notes/cleanroom-specs/` and `notes/beta-gaps/` do), which the implementer reads instead of the upstream
+ thread.
diff --git a/.agents/skills/liquid-glass/SKILL.md b/.agents/skills/liquid-glass/SKILL.md
index 87a052b3..1e8cce91 100644
--- a/.agents/skills/liquid-glass/SKILL.md
+++ b/.agents/skills/liquid-glass/SKILL.md
@@ -186,6 +186,12 @@ For platform-specific details, see [references/platform-specifics.md](references
- **iPadOS**: Larger grid sizes; sidebar adaptable tab views
- **Conditional compilation**: Use `#if os(macOS)` / `#if os(iOS)` for platform-specific code
+## UIKit
+
+The tweak is UIKit and Objective-C. For `UIGlassEffect`, `UIGlassContainerEffect`, `cornerConfiguration`,
+scroll edge effects, glass bar items and buttons, and the tweak's own glass rules, see
+[references/uikit.md](references/uikit.md).
+
## Common Pitfalls
For detailed pitfalls and solutions, see [references/pitfalls-and-solutions.md](references/pitfalls-and-solutions.md).
diff --git a/.agents/skills/liquid-glass/references/api-reference.md b/.agents/skills/liquid-glass/references/api-reference.md
index 51852be4..fd7c0783 100644
--- a/.agents/skills/liquid-glass/references/api-reference.md
+++ b/.agents/skills/liquid-glass/references/api-reference.md
@@ -15,7 +15,7 @@ Complete API reference for all SwiftUI Liquid Glass modifiers and types. Always
9. [TabView Glass APIs](#tabview-glass-apis)
10. [Sheet Glass APIs](#sheet-glass-apis)
11. [Accessibility APIs](#accessibility-apis)
-12. [UIKit Bridge](#uikit-bridge)
+12. [UIKit Bridge](#uikit-bridge) (full UIKit API: [uikit.md](uikit.md))
---
@@ -390,14 +390,14 @@ var body: some View {
For cases where SwiftUI glass has rendering issues (e.g., rotation animations):
```swift
-// UIKit glass effect
-let glassEffect = UIGlassEffect()
+// UIKit glass effect. init(style:) is the only initializer; a bare UIGlassEffect() draws a plain blur.
+let glassEffect = UIGlassEffect(style: .regular)
let effectView = UIVisualEffectView(effect: glassEffect)
// In UIViewRepresentable
struct GlassView: UIViewRepresentable {
func makeUIView(context: Context) -> UIVisualEffectView {
- let effect = UIGlassEffect()
+ let effect = UIGlassEffect(style: .regular)
return UIVisualEffectView(effect: effect)
}
func updateUIView(_ uiView: UIVisualEffectView, context: Context) { }
@@ -408,3 +408,5 @@ Use this bridge when:
- `rotationEffect` causes glass shape morphing artifacts
- You need precise control over glass rendering in complex layouts
- Integrating glass into existing UIKit view hierarchies
+
+The full UIKit API is in [uikit.md](uikit.md).
diff --git a/.agents/skills/liquid-glass/references/uikit.md b/.agents/skills/liquid-glass/references/uikit.md
new file mode 100644
index 00000000..4129af53
--- /dev/null
+++ b/.agents/skills/liquid-glass/references/uikit.md
@@ -0,0 +1,121 @@
+# Liquid Glass in UIKit
+
+UIKit's glass APIs, checked against the iOS 27 SDK headers, with the rules the tweak proved on the
+phone. The tweak is Objective-C, so the examples are too. Everything here is iOS 26 and later. Gate
+it with `@available(iOS 26.0, *)`, or with `NSClassFromString` and `respondsToSelector:` as
+`Core/SGGlass.m` does.
+
+## UIGlassEffect
+
+```objc
+UIGlassEffect *effect = [UIGlassEffect effectWithStyle:UIGlassEffectStyleRegular];
+effect.interactive = YES; // scales and shimmers under a touch
+effect.tintColor = UIColor.systemPinkColor; // nullable
+UIVisualEffectView *glass = [[UIVisualEffectView alloc] initWithEffect:effect];
+[glass.contentView addSubview:label];
+```
+
+- `+effectWithStyle:` is the only initializer. A bare `-init` (Swift `UIGlassEffect()`) leaves the
+ material unresolved, so the pane draws as a plain blur. Spotify's own glass uses `+effectWithStyle:`.
+- `UIGlassEffectStyleRegular` suits controls and bars. `UIGlassEffectStyleClear` suits glass over
+ bright media with bold content on it.
+- Put content in `contentView`, not directly in the effect view.
+- `SGGlassEffect()` returns the regular glass, or a dark chrome blur before iOS 26.
+
+## Shape
+
+Glass takes its shape from `UIView.cornerConfiguration`, not from `layer.cornerRadius`.
+
+```objc
+glass.cornerConfiguration = [UICornerConfiguration capsuleConfiguration];
+glass.cornerConfiguration = [UICornerConfiguration configurationWithUniformRadius:[UICornerRadius fixedRadius:20]];
+glass.cornerConfiguration = [UICornerConfiguration configurationWithUniformRadius:[UICornerRadius containerConcentricRadius]];
+glass.clipsToBounds = NO;
+```
+
+- `capsuleConfiguration` scales with the view's size. `capsuleConfigurationWithMaximumRadius:` caps it.
+- `containerConcentricRadius` computes the radius from the view and its container.
+ `containerConcentricRadiusWithMinimum:` sets a floor.
+- `-effectiveRadiusForCorner:` returns the radius a configuration resolved to.
+- Before iOS 26, use `layer.cornerRadius` with `kCACornerCurveContinuous` and `clipsToBounds = YES`.
+ `SGShapeGlass` (`Core/SGGlass.h`) does both.
+
+## Grouping: UIGlassContainerEffect
+
+Glass can't sample other glass, so glass views that sit close together go in one container. Its
+`spacing` is the distance at which the elements begin to merge.
+
+```objc
+UIGlassContainerEffect *group = [UIGlassContainerEffect new];
+group.spacing = 12;
+UIVisualEffectView *container = [[UIVisualEffectView alloc] initWithEffect:group];
+[container.contentView addSubview:glassA]; // each a UIVisualEffectView with a UIGlassEffect
+[container.contentView addSubview:glassB];
+```
+
+The tweak doesn't use it yet, so check merging and morphing on the phone before you rely on them.
+
+## Scroll edge effects
+
+Every `UIScrollView` has `topEdgeEffect`, `bottomEdgeEffect`, `leftEdgeEffect` and `rightEdgeEffect`.
+Each is a read-only `UIScrollEdgeEffect` with a `style` and a `hidden` flag. The styles are class
+properties of `UIScrollEdgeEffectStyle`, not an enum:
+
+| Style | Look |
+| --- | --- |
+| `automaticStyle` | the system picks |
+| `softStyle` | a thin fading blur |
+| `hardStyle` | a hard cutoff with a dividing line |
+
+```objc
+scrollView.topEdgeEffect.style = UIScrollEdgeEffectStyle.softStyle;
+scrollView.bottomEdgeEffect.hidden = YES;
+```
+
+iOS 27 resolves an automatic top edge to the hard style, and UIKit can resolve it again after the
+page appears. `Redesigned/Kit/SGREdgeEffect.x` and `Native/Appearance/EdgeEffect.x` set the soft
+style on `didMoveToWindow` and on every `layoutSubviews`.
+
+## UIScrollEdgeElementContainerInteraction
+
+Add it to a container of views that overlay a scroll view's edge, such as a floating button bar.
+Labels, images, glass views and controls inside the container then shape the edge effect.
+
+```objc
+UIScrollEdgeElementContainerInteraction *interaction = [UIScrollEdgeElementContainerInteraction new];
+interaction.scrollView = scrollView; // weak
+interaction.edge = UIRectEdgeBottom;
+[buttonContainer addInteraction:interaction];
+```
+
+## Bar button items
+
+- `hidesSharedBackground` (default `NO`): `YES` draws the item alone, without the shared glass background.
+- `sharesBackground` (default `YES`): `NO` stops the item from being grouped with other items.
+- Both are ignored for an item in a `UIBarButtonItemGroup` with more than one item.
+
+## Buttons
+
+`UIButtonConfiguration` has four glass constructors: `glassButtonConfiguration`,
+`prominentGlassButtonConfiguration`, `clearGlassButtonConfiguration` and
+`prominentClearGlassButtonConfiguration`.
+
+## Background extension
+
+`UIBackgroundExtensionView` is UIKit's `backgroundExtensionEffect`. Set its `contentView`. With
+`automaticallyPlacesContentView` (default `YES`), it places the content in the safe area and extends
+it to fill the view around it.
+
+## Tab bar
+
+- `UITabBarController.tabBarMinimizeBehavior`: `UITabBarMinimizeBehaviorAutomatic` (default),
+ `…Never`, `…OnScrollDown` or `…OnScrollUp`.
+- `bottomAccessory` takes a `UITabAccessory` made with `-initWithContentView:`. Use
+ `-setBottomAccessory:animated:` to animate the change.
+
+## Appearance in the tweak
+
+Glass takes the appearance it inherits. Outside Spotify's navigation stacks (the tab bar, the now
+playing bar, the player) that is the system's, so set `overrideUserInterfaceStyle =
+UIUserInterfaceStyleDark` on every pane of the mod's. Present a controller of the mod's through
+`SGPresentDark`, because a sheet's glass belongs to its presentation.
diff --git a/.agents/skills/phone-check/SKILL.md b/.agents/skills/phone-check/SKILL.md
new file mode 100644
index 00000000..d7c260d6
--- /dev/null
+++ b/.agents/skills/phone-check/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: phone-check
+description: >
+ Install a Vitrine build on the paired iPhone and check it there: relaunch, drive it with the phone driver,
+ take screenshots, read the view tree and stream the log. Use whenever a change has to be seen or measured
+ on the phone, or the user reports something on the phone that needs evidence.
+---
+
+# Checking a build on the phone
+
+Values that belong to one person's phone live in `.phone.env` at the repo root (gitignored; copy
+`.phone.env.example`). Load them first:
+
+ set -a; . ./.phone.env; set +a # PHONE_UDID, PHONE_HOST, APP_BUNDLE
+
+## Install
+
+- `make quick` rebuilds only the tweak and installs it in seconds. It needs a full build with FLEX first:
+ `scripts/pipeline.sh ipa/Spotify-9.1.78.ipa`, then `make quick`.
+- The full build fails inside the sandbox at the App Intents step ("Exception during writing compiled
+ data"); run it outside the sandbox.
+- `make quick` refuses when the extension, a plist or an icon changed since the full build. Run the full
+ build again.
+- An install quits the app. Relaunch it and wait for the driver:
+
+ xcrun devicectl device process launch --terminate-existing --device "$PHONE_UDID" "$APP_BUNDLE"
+ for i in $(seq 1 15); do sleep 2; scripts/phone.py state >/dev/null 2>&1 && break; done
+
+- After a version change, What's New covers the screen. Close it with `scripts/phone.py tap --text Continue`.
+
+## Drive
+
+`scripts/phone.py` (its header lists every command) talks to the driver in FLEX builds. Over Wi-Fi it
+needs `PHONE_HOST` and the token the app logs at launch, which it reads from the log file below.
+
+- Check `scripts/phone.py state` before anything else. Its `top` and `presented` say what is on screen.
+- `settings.page` finds only rows on screen. Scroll first. After two failed lookups, stop and ask the
+ user to open the page instead of probing further.
+- A swipe that only sets `contentOffset` (`scroll`) does not trigger scroll-driven behavior like the tab
+ bar's minimize. Use `swipe` with a duration for that.
+
+## Screenshots
+
+The driver's `screenshot` can come back blank. Take them through the tunnel instead, which needs
+`sudo pymobiledevice3 remote tunneld` running (the user starts it):
+
+ uvx pymobiledevice3 developer dvt screenshot --tunnel "$PHONE_UDID" "$TMPDIR/shot.png"
+ uv run -q --no-project --with pillow python -c "from PIL import Image; im=Image.open('$TMPDIR/shot.png'); w,h=im.size; im.crop((0,int(h*.8),w,h)).save('$TMPDIR/crop.png')"
+
+Read the cropped file with the Read tool. A full-height image is hard to judge; crop to the part in question.
+
+Privacy: a tunnel screenshot captures whatever is on screen. Check `scripts/phone.py state` first, and do
+not take one while the user is in another app.
+
+## Log
+
+- `scripts/phone.py log` holds only the latest lines of the current launch. A background screen dump
+ floods it, and every relaunch starts it over. For anything across a relaunch or a lock, stream the log
+ instead, in the background:
+
+ uvx pymobiledevice3 syslog live --tunnel "$PHONE_UDID" -m '[spotifyglass]' >> /tmp/claude-501/device.log 2>&1
+
+ `scripts/phone.py` reads the Wi-Fi token from that file. `idevicesyslog -n` often cannot find the phone
+ over Wi-Fi.
+- Grep the file for the feature's log prefix (`lock lyrics:`, `sing:`, `redesign home:`). When a feature
+ says nothing about why it did nothing, add one log line per track or per change and rebuild, rather than
+ guessing.
+
+## View tree
+
+`scripts/phone.py tree` prints the visible screen's tree as indented text with frames, `hidden`, `a=` (alpha)
+and `clips`. To see a view's ancestors, walk up by indentation:
+
+ n=$(grep -n 'SGRBarText' tree.txt | head -1 | cut -d: -f1)
+ awk -v n=$n 'NR<=n {match($0,/^ */); d[NR]=RLENGTH; l[NR]=$0} END{w=d[n]; for(i=n;i>0;i--) if(i==n||d[i]<w){print l[i]; w=d[i]}}' tree.txt
+
+Capture the tree in the exact state being judged. A tree taken after another gesture describes a different
+layout.
+
+## Before blaming the code
+
+- Spotify playing on another device through Connect (a laptop or speaker glyph on the bar) leaves the phone
+ a remote. The lock screen's full-screen artwork and anything that needs local audio do nothing then.
+- `sing: the iPhone is hot` means Karaoke holds back on purpose.
+- FLEX's toolbar can cover the top of the screen. The user closes it with its ✕.
+- A log line on a path that runs per event, per packet or per tick floods the in-app log (it pushed every
+ other line out at about fifty a second) and costs battery for every user. Log the first few of a launch
+ and a count once a minute, and take debug lines out or cap them before committing.
+- Say what the phone showed and what it did not. A build that compiled is not a check on the phone.
diff --git a/.claude/skills/clean-room-describer b/.claude/skills/clean-room-describer
new file mode 120000
index 00000000..d9f19b5f
--- /dev/null
+++ b/.claude/skills/clean-room-describer
@@ -0,0 +1 @@
+../../.agents/skills/clean-room-describer
\ No newline at end of file
diff --git a/.claude/skills/phone-check b/.claude/skills/phone-check
new file mode 120000
index 00000000..cd8f0bce
--- /dev/null
+++ b/.claude/skills/phone-check
@@ -0,0 +1 @@
+../../.agents/skills/phone-check
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 35a91f71..54b5e5fa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,3 +25,5 @@ notes/
# zsign's signature cache, from signing out/quick/ in place
.zsign_cache/
+.phone.env
+.claude/worktrees/
diff --git a/.phone.env.example b/.phone.env.example
new file mode 100644
index 00000000..09aa0bdc
--- /dev/null
+++ b/.phone.env.example
@@ -0,0 +1,4 @@
+# Your phone, for the phone-check skill (.agents/skills/phone-check). Copy to .phone.env, which git ignores.
+PHONE_UDID=00000000-0000000000000000 # xcrun devicectl list devices
+PHONE_HOST= # the phone's Tailscale address, empty over USB
+APP_BUNDLE=com.example.spotify # the bundle id your signing gives the app