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.mdindex 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 onapple-hig/ design review against Apple's Human Interface Guidelines, 122 pages underreferences/hig/, liquid-glass.md, materials.md, tab-bars.md and motion.md among themapple-design/ Designing Fluid Interfaces: springs by damping and response, velocity handoff,momentum projection, rubber-banding, interruptible transitions, materialsreview-animations/ a strict review of motion code, `/review-animations`; STANDARDS.md holds the valuesanimation-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 onlyThe motion skills write their examples in CSS and JavaScript. The rules carry over to UIKit as theyare: 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 withEmil Kowalski's `apple-design`. `node .agents/skills/apple-hig/scripts/pull-hig.mjs` pulls theguideline pages again from developer.apple.com.diff --git a/.agents/skills/clean-room-describer/SKILL.md b/.agents/skills/clean-room-describer/SKILL.mdnew file mode 100644index 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.mdindex 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 PitfallsFor 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.mdindex 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. Always9. [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 UIViewRepresentablestruct 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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-describernew file mode 120000index 00000000..d9f19b5f--- /dev/null+++ b/.claude/skills/clean-room-describer@@ -0,0 +1 @@+../../.agents/skills/clean-room-describer\ No newline at end of filediff --git a/.claude/skills/phone-check b/.claude/skills/phone-checknew file mode 120000index 00000000..cd8f0bce--- /dev/null+++ b/.claude/skills/phone-check@@ -0,0 +1 @@+../../.agents/skills/phone-check\ No newline at end of filediff --git a/.gitignore b/.gitignoreindex 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.examplenew file mode 100644index 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