100 Commits

This Branch

This Branch

All Branches

Author	SHA1	Message	Date
logan	ced537ecf2	docs: record which Android blockers are now cleared	2026-08-16 17:18:22 -04:00
logan	e14a34fccf	fix(android): let the app reach the user's music ... Three of plan 016's four blockers. Each is a different reason the app could not work at all on a phone. **It had no permission to read anything.** The generated manifest asked for INTERNET, VIBRATE, biometrics, location and a camera, and nothing whatever about storage -- so at targetSdk 35 the app could see its own private directory and no music. It now declares READ_MEDIA_AUDIO, the two capped legacy storage permissions, and MANAGE_EXTERNAL_STORAGE. That last one is deliberate and is the load-bearing choice. This app is a library manager: audio_files.file_path is the primary key of ownership, the scanner walks a directory the user chose, and tagwriter rewrites files in place. MediaStore offers no stable directory to walk and no in-place write, so scoped storage is not "more work" here, it is a different application. MANAGE_EXTERNAL_STORAGE is Play-restricted, which is acceptable only because this ships as an APK through the package registry -- if it ever targets Play, that line is what has to go, and plan 016 says what replaces it. It is granted on a Settings screen rather than in a dialog, so it cannot be requested with requestPermissions(). MainActivity opens that screen on every cold start until access exists -- there is no degraded mode worth offering -- and re-checks in onResume, because the way back from another task is a resume, emitting android:storageAccess so the frontend can react. **The first-run flow could not complete.** All three call sites asked for a folder through the Wails dialog, which returns an error on Android: SAF yields tree URIs and this app is keyed on paths. So the app browses the filesystem itself, which it can now do. ListDirectories lists directories only (the thing being chosen is a library root), skips what it cannot stat rather than failing the listing (Android's storage root holds directories no app may enter), follows symlinks (os.DirEntry reports the link, so a symlinked music folder would silently vanish), and hides dotted entries. utils/pick-directory.ts is the one place that chooses between the two, so the three call sites changed by one line each. **Which platform is asked of the backend**, not of System.IsAndroid(): the dialog is backend code, so the backend is what knows whether it can open one; it answers for iOS at the same time; and it keeps the fallback testable through the ordinary transport fake rather than a module mock of the Wails runtime, whose platform helpers read build constants. **And MPRIS was compiled into the Android build**, because android implies the linux build tag, so it went looking for a session bus that does not exist. mpris_linux.go is `linux && !android` now and the stub covers Android, which means no lock-screen transport there yet -- a missing feature rather than a broken one, and the remaining blocker. The foreground service is typed mediaPlayback rather than the scaffold's dataSync, with the matching permission, so playback can survive the screen locking once there is a MediaSession to drive it. The type in the manifest and the one passed to startForeground must agree or startForeground throws.	2026-08-16 17:18:03 -04:00
logan	78576b8da9	docs: assess what Android parity would take ... Plan 015 shipped a pipeline; this is what stands between that and an app worth installing. Verified against the source and the generated manifest rather than guessed. Four blockers, and none of them is porting work. The manifest requests no storage or media permission at all, so the app can read no music -- and READ_MEDIA_AUDIO would not be enough, because it grants access through MediaStore while this app's whole model is absolute paths: audio_files.file_path is the primary key of ownership and every GetFilePathsBy... query exists to hand paths to the player. The first-run wizard calls DirectoryPicker, which Wails documents as returning an error on Android, and the wizard intercepts pointer events until a library exists, so the app is inert rather than merely empty. mpris_linux.go is compiled in, because android implies linux. And the scaffold's foreground service is typed dataSync rather than mediaPlayback, with no MediaSession and no audio focus, so playback dies at screen lock and there are no lock-screen controls. They are all the same question: is the Android app a librarian or a player? The desktop app is a librarian -- it scans folders, dedupes covers, rewrites tags on disk -- and that model rests on owning a filesystem, which is exactly what Android declines to give. So the plan argues that parity is the wrong target and lays out three coherent products instead, recommending a MediaStore-backed player. Four things are worth doing whatever is decided, and the highest information-per-minute one needs no code: run the published APK on a real phone. Nothing in sections A or B has been observed on Android, because the x86_64 emulator cannot run the app and emulator 37 refuses arm64 images on an x86_64 host.	2026-08-16 17:02:53 -04:00
logan	01706c6053	ci(android): say why the keystore did not open ... "the keystore did not open — is ANDROID_KEYSTORE_PASSWORD right?" is a guess, and there are three quite different reasons behind it. The step distinguishes them now. **A secret pasted into a web form very often carries a trailing newline**, and a password is compared byte for byte, so the run failed with a password that was correct. Reproduced exactly: keytool rejects `Correct123\n` against a keystore whose password is `Correct123`. CR and LF are stripped from the password, the alias and the key password now, and the step says when that mattered. **A wrong alias failed a minute later, inside Gradle.** It defaults to `yellowjacket`, so any keystore created with another alias got there. The alias is checked up front and the failure lists the aliases the keystore actually holds. **And a truncated or mis-pasted base64 is a different problem from a bad password**, so the artifact is described before it is opened: size and its first four bytes, named as PKCS12 or legacy JKS, with a warning when the header is neither. A truncation shows up as 300 bytes against 2564. Verified against real keystores for all five cases: correct, trailing newline, wrong password, wrong alias, truncated base64. Decode and build are one step now. Splitting them would mean either handing the password to a later step through $GITHUB_ENV -- where the env dump is only masked for values that are verbatim a secret, so a trimmed one could print in clear -- or repeating the trimming in both. The failure message also prints the password's length, which is the one thing that distinguishes "wrong value" from "invisible whitespace", and only on failure.	2026-08-16 17:00:36 -04:00
logan	f7dc76c955	docs(android): an arm64 image will not run on an x86_64 host ... Emulator 37 refuses cross-architecture emulation outright -- "Avd's CPU Architecture 'arm64' is not supported by the QEMU2 emulator on x86_64 host" -- and there is no flag for it. Google dropped it. That matters because the previous commit's finding points at arm64 as the ABI that works, so the obvious next move is to boot an arm64 AVD, and the obvious next move costs a 3.8 GB download before it fails. Written down so the next session does not spend it. The consequence is stated rather than hidden: the claim that arm64 avoids the seccomp trap rests on reading modernc's two code paths, not on having run it. Verifying it needs an arm64 host, a physical device or adb connect.	2026-08-16 16:27:52 -04:00
logan	ed975019dc	fix(dev): the smoke target died silently on a genuinely dead app ... Two harness bugs and the finding that exposed them. **`pidof` exits 1 when it finds nothing**, and under `set -e` a failing command substitution killed the script before it could print anything -- rc=1, no output. That was invisible for as long as the app crash-*looped*, because there is always some pid in that state. It appeared the moment the app died for good and ActivityManager stopped respawning it, which is precisely the run you most want output from. **And an install failure said nothing useful.** Both ways it fails are about identity rather than the build: INSTALL_FAILED_VERSION_DOWNGRADE when a bare `make android` (versionCode 1) meets something a versioned build left behind, and a signature mismatch when a debug-signed local build meets a release-signed one. Both were hit in one session, and both are fixed by uninstalling. The target says so now instead of leaving someone to read the constant name. The finding: with the startup bug fixed the app reaches the database and takes SIGSYS on the x86_64 emulator, because modernc.org/libc's Xlstat64 issues a raw lstat syscall on linux/amd64 and Android's seccomp filter forbids it -- bionic never issues it. arm64 has no lstat syscall at all, so ccgo_linux_arm64.go routes Xlstat through fstatat and is structurally unaffected; Go's own syscall package already used fstatat on both. So the default emulator cannot verify this app, and the skill says so rather than letting the next session read a tombstone as a regression.	2026-08-16 16:25:33 -04:00
logan	0c7f34ab90	fix(android): give the app a home directory so it starts ... backend/system resolves config and data from $HOME or the OS equivalent, and Android has neither: buildUserDirPath switches on runtime.GOOS with cases for darwin, linux and windows and a default returning errUnsupportedOS. So NewYellowJacketApp failed and main() called os.Exit(1) about six milliseconds after the JNI bridge came up. That failure is invisible in all three places anyone would look. There is no panic, no AndroidRuntime stack and no tombstone, because os.Exit is not a crash; Go's stdout does not reach logcat, so the slog line naming the error is discarded; and ActivityManager respawns the process fast enough that pidof always answers, so a crash-looping app looks alive. main() now sets the override before anything asks for a path. application.Mobile.StoragePath() is the platform's own answer -- getFilesDir() on Android, Application Support on iOS -- and returns "" on desktop, where UseHomeOverride is a no-op, so this needs no build tag and changes nothing off mobile. resolveUserDirPath already honours YJ_HOME on every OS, so there was a seam for it. The knowledge stays in main(): backend/system gains no import of the Wails application package, for the same reason backend/events is split by the indexbuild tag. UseHomeOverride's two rules are tested because nothing else would notice them breaking. An empty base does nothing, which is exactly the desktop case. And an override already set wins, so YJ_HOME still relocates a sandbox on the one platform that would otherwise decide for itself. This is not the end of the port. The app now reaches the database and takes SIGSYS on the x86_64 emulator -- modernc.org/libc issues a raw lstat syscall on linux/amd64 and Android's seccomp forbids it. arm64, which is what ships to phones, has no lstat syscall at all and routes through fstatat, so it is structurally unaffected. See NOTES.md.	2026-08-16 16:25:20 -04:00
logan	a7a33527c4	docs: record what the Android work established and disproved ... CLAUDE.md said `wails3 task common:update:build-assets` regenerates build/ios/ and build/android/. It does not: in beta.8 that command extracts only updatable_build_assets, which is darwin/ios/linux/windows, and the android tree comes from `generate build-assets`. It also said nfpm's homepage and license are left alone by the refresh -- a comment in that file says the same -- and a refresh reset them to wails.io and MIT. Both corrected, and the CI section now describes five workflows. NOTES.md gains the measurements: what cross-compiles and what does not, the emulator environment, the Wails Android documentation's own two errors, and the one line that stops the app at runtime -- buildUserDirPath switches on runtime.GOOS and Android takes the default branch returning errUnsupportedOS, so main() calls os.Exit(1) six milliseconds after the JNI bridge comes up. The fix is a documented, build-tag-free API: application.Mobile.StoragePath() returns the app's private files directory and returns "" on desktop, and resolveUserDirPath already lets YJ_HOME override the path on every OS. Deliberately not taken here -- plan 015 is a pipeline, not a port, and the larger question it does not answer is that open-directory dialogs return an error on Android while this app's entire first run is "choose your music folder".	2026-08-16 15:31:18 -04:00
logan	0c6ca72cf1	ci(android): publish a signed APK on every version tag ... Builds the fat APK and puts it in Gitea's *generic* package registry, which unlike the repository is readable without credentials -- the reason an Obtainium client can poll a plain URL with no token and no public mirror of the source. A versioned copy for history, a fixed `latest` URL to watch. **Its own workflow, not a job in ci.yml.** That workflow runs on every branch push and is the one that gates; this takes tens of minutes on a cold cache and the runner has capacity 1, so hanging it off the gate would put every push behind an SDK download. **Keyed on the tag.** The ljos pipeline this is modelled on computes a version in CI and cuts the release itself, then gates its Android job on needs.release.outputs.version with an always() whose absence silently kills the manual path. This repo has no release automation -- tags are pushed by hand and homebrew-formula.yml already keys on v* -- so the tag is the version and none of that machinery, or its failure modes, is needed. **No continue-on-error**, which that pipeline does carry: there the Android job shares a workflow with a server deploy that must never go red over a phone build. Here it is standalone and can neither delay nor redden anything, so a release step that fails silently would be strictly worse than one that fails visibly. Four gates before anything is published, each checked against a real APK: a non-empty artifact, both ABIs present, a versionCode equal to the one derived from the tag, and -- verified by pointing it at a deliberately debug-signed build, which it refused -- **not signed with the debug key**. Android refuses to update an app whose signing certificate changed and the only remedy is an uninstall that takes the user's library with it, so the job also refuses to *build* without the keystore secret rather than falling through to Gradle's debug default. The keystore is opened with `keytool -list` before Gradle runs, because Gradle only notices a bad password at :app:validateSigningRelease, a minute of build time in, and reports it as a missing file. And nothing pipes into `head`: under pipefail it exits after one line, the producer takes SIGPIPE and the step fails with 141 having already printed a perfectly good APK. Two secrets, not four. keytool has produced PKCS12 by default since JDK 9 regardless of the .jks extension, and PKCS12 cannot hold a key password distinct from the store password -- given one it says so and ignores it. So ANDROID_KEY_PASSWORD defaults to the store password and the alias to a documented default. The Wails CLI needs no caching hack here: it is a vendored `go tool` and the runner already bind-mounts GOCACHE for every job, so it is warm from ci.yml's own bindings-check. A fourth cache volume for GRADLE_USER_HOME saves ~700MB a run.	2026-08-16 15:31:18 -04:00
logan	68468e5378	feat(dev): an Android failure looks exactly like a success ... The APK installs and launches. It also dies six milliseconds later, and finding that out cost a cycle for three reasons that have nothing to do with the bug itself: **Go's stdout does not reach logcat.** An Android app's fd 1 and 2 go to /dev/null, so every slog line -- including the one naming the error the app is about to exit on -- is discarded. `setprop log.redirect-stdio true` does not help: that redirects the Java runtime's System.out, and our code is a c-shared native library. **os.Exit leaves no evidence.** No panic, no AndroidRuntime stack, nothing in /data/tombstones, nothing in `logcat -b crash` or dropbox. All three places anyone would look are empty, and the one signal that is present -- "Zygote: exited due to signal 9" -- reads as "the system killed it" and sends you after the low-memory killer. **ActivityManager restarts it faster than you can observe.** pidof always answers and `am start` always reports Status: ok, so a crash-looping app looks alive. "Did it start" is the wrong question; `make android-smoke` asks whether it is the *same pid* N seconds later, and prints the filtered logcat plus how to read it when it is not. The tell, once known: "I/WailsBridge: Wails bridge initialized" followed immediately by a new pid doing the same thing. scripts/android-emulator.sh follows dev-headless.sh's shape -- background start, saved-PID stop, filtered log tail, never pkill -f. Two scaffold tasks are deliberately not wrapped: `android:logs` greps logcat for (Wails|yellowjacket), which catches the WailsBridge tag but misses the app's own process tag (app.yellowjacket is lowercase) and misses ActivityManager's "has died" line, which is the one that says it crashed; and `ensure-emulator` boots whatever `-list-avds | tail -1` returns, with no pidfile and no boot wait, so it cannot be sequenced. One environment note that is not obvious on Arch: Gradle needs a platform and /opt/android-sdk has none, so ANDROID_SDK defaults to ~/Android/Sdk while ANDROID_NDK points at /opt/android-ndk. Two SDKs, one for each half of the build.	2026-08-16 15:31:18 -04:00
logan	6fbb62730d	fix(android): build a release APK that is releasable ... Three edits to the scaffold, each of which the generated tree gets wrong for a shipped app. **The phone ABI got a debug library.** Upstream's `build` task forwards ARCH to compile:go:shared but not PRODUCTION, so the arm64 leg recomputed BUILD_FLAGS against an unset variable and took the debug branch -- while amd64, which package:fat calls directly with PRODUCTION: "true", was correct. A release APK therefore shipped a 40MB unstripped debug library for the only ABI a release is for, beside a 31MB production one for the emulator. 34MB APK before, 27MB after. **The APK could be installed once and never updated.** Android orders releases by versionCode and refuses anything not greater than what is installed; the scaffold hardcodes 1, so the first install would have been the last and the only way out is an uninstall, which takes the user's library with it. It comes from YJ_VERSION_CODE now, which CI derives from the tag (1.3.1 -> 10301, monotonic while minor and patch stay under 100), with a default that keeps a local build working. Integer.parseInt, not `(...) as Integer`: Groovy binds the call parentheses to versionCode before the cast, so the latter reads as `versionCode("1") as Integer` -- it sets a String, then casts the setter's null return, and Gradle fails the whole project with "Value is null" pointing at that line. **And it identified itself as com.wails.app.** applicationId is app.yellowjacket now, matching build/config.yml's productIdentifier, and the label is YellowJacket rather than "Wails App". Two things follow from that rename and both bite: The identity is declared twice. applicationId is what Gradle installs; APP_ID in build/android/Taskfile.yml is what every adb-driven task uninstalls, launches and filters, and nothing enforces agreement. ANDROID.md says to set APP_ID in build/config.yml -- that does nothing in beta.8, checked both ways: `wails3 task` builds its var set from CLI KEY=VALUE arguments and the Taskfile tree and never reads config.yml, and even when set it feeds only those adb commands, never Gradle. And `namespace` deliberately stays com.wails.app, because that is the Java package MainActivity and WailsBridge live in and renaming it means renaming their source. So the launcher activity is app.yellowjacket/com.wails.app.MainActivity, and the short `.MainActivity` form resolves the dot against the applicationId and fails with a class-not-found that reads like a broken build.	2026-08-16 15:30:35 -04:00
logan	48b37f6301	build(android): carry the Wails Android scaffolding verbatim ... Plan 015 phase 0 established that this app cross-compiles for Android with no source changes at all. A CGO_ENABLED=0 probe of the whole tree for android/arm64 fails on exactly two packages -- ebitengine/oto/v3 and wails/v3/pkg/application -- and both fail only because their Android implementation is cgo, which is what the NDK supplies. Notably modernc.org/sqlite, the entire database layer and the thing most likely to have no Android target, is clean. The fat APK (arm64-v8a + x86_64) builds in about 25 seconds. So build/android/ stops being ignored. This commit is the tree exactly as `wails3 generate build-assets` emits it, so that the next commit is a readable diff of what we changed and a future refresh has something to compare against. Two things about how it is carried: `wails3 update build-assets` does NOT generate it, contrary to what CLAUDE.md has claimed since the v3 migration. In beta.8 that command extracts only internal/commands/updatable_build_assets, which is darwin/ios/linux/windows; the android tree comes from `generate build-assets`, which rewrites the whole of build/. It was generated once into a scratch directory and copied across, so from here it is committed and hand-edited like source. Only its output is ignored -- jniLibs (~60MB of per-ABI c-shared libraries), gen/, overlay.json and Gradle's own directories. And it brings one Go file into ./... -- scripts/deps/install_deps.go, the interactive SDK installer behind `task android:install:deps`, which trips 24 of our strict linters. golangci excludes the directory rather than reformatting upstream's file, which the next refresh would undo and which would make the diff against upstream unreadable. This repo uses `make android-setup` instead.	2026-08-16 15:30:13 -04:00
logan	66182f82cd	fix(indexbuild): repair the one database a squash cannot reach ... The index job's /cache volume is a real YJ_HOME that outlives every run, so plan 013's reshaped audio_files met a database still in the old shape: `CREATE INDEX ... album_id` against a table without that column, on every launch. "Delete and rescan" is the squash's answer and is free everywhere except here, where half the file is the catalog and deleting it costs ~205GB of downloading. indexbuild now drops every table datamap does not classify as Cache before the schema is applied. Nothing scans, plays or authors in that database, so its non-catalog half is empty by construction and a shape the schema stopped describing is pure liability; the catalog is never touched. TestRetireLibraryTables reproduces the failure symptom-first: build the real schema, put audio_files back the way the volume had it, assert the open fails, then assert the repair makes it open with the catalog row still there.	2026-08-16 15:09:09 -04:00
logan	18aba34c08	test(e2e): a track plays the list it is in, not a queue of one ... e7748f1 made double-click and single-row Play queue the list as displayed with startIndex on that row; this frozen spec still asserted a queue of one, and was the only failure in both the chromium and webkit runs on main. It asserts the new contract instead: more than one track queued, currentIndex on the row that was activated, and the panel showing that queue rather than some other one.	2026-08-16 14:51:07 -04:00
logan	b98840ee37	fix(build): keep the index tools free of the Wails application ... The v3 migration put application.Get() in backend/events and a ServiceStartup hook in backend/explore, both of which cmd/indexbuild reaches. v3's application package is GTK/WebKit bindings on Linux, so the index-artifact job — a plain golang container with CGO_ENABLED=0, on the stated grounds that neither command imports the app — stopped compiling with "undefined: pointer". That job owns the ~205 GB dump checkpoint, so it is the worst place to learn this. Both are behind the indexbuild tag now: the one app.Event.Emit lives in runtime_wails.go, runtime_indexbuild.go answers ErrNoRuntime (what the app itself returns before Run, so Deliver's callers need no second path), and explore's ServiceStartup moves to its own tagged file. TestIndexToolsDoNotImportWails walks `go list -deps -tags indexbuild` so the claim the workflow makes is checked rather than assumed.	2026-08-16 14:51:01 -04:00
logan	c94c97f604	docs: move plan 009 to completed	2026-08-13 15:18:22 -04:00
logan	4801ba4480	docs: close plan 009, and what a decision phase found ... Two of Phase 2's three judgement calls were answered by reading the code rather than by choosing: there is no artist badge to make a button, and a track badge stops reading as noise the moment it means something. The third went the other way — `EntityRecording` reads like a placeholder and is real work.	2026-08-13 15:18:17 -04:00
logan	40bc968cf8	test(e2e): a real click on the badge acts without opening the card ... Only this tier can say it: the badge sits inside a card whose own click navigates, so what matters is that a real gesture files the request *and* leaves the page where it was. It clicks a locator rather than a measured point. The first version read a bounding box the moment the search settled, but cover art is still arriving then and a card that grows moves the badge — so the click landed on the card and opened the album, which is precisely the regression the test exists to catch, reported as a failure to file a request. The phase 1 label assertion moves with the component: a control is named after what activating it does, so the badge that said "is queued for download" now says "Cancel the request for …".	2026-08-13 15:17:14 -04:00
logan	e61b7456df	feat(explore): make the library badge request what it is on ... 007 turned this badge from a `<button>` whose handler was a `stopPropagation()` and a TODO into `role="img"`, on the rule that a control which cannot act is worse than none — and wrote down what would change the answer: a `<button>` again *with* a handler, never a handler bolted onto something already shaped like one. This is that. A call site opts in by passing `request-mbid`, so where a badge is redundant it stays a badge: `explore-album-details`'s header has "Want this" in words directly below it, and its template says so by not opting in. An `in-library` badge is never a button either, because there is nothing left to ask for — that is what keeps the tab stops 007 gave back from being spent on nothing. The copy is the action, not the state, and it is deliberately about the request list rather than the library: "Want album X" / "Cancel the request for album X". Clicking still adds nothing to the library, which is what made the original "Add … to library" a promise the control could not keep. Tracks are requestable too. `EntityRecording` is not a placeholder in the request model — `Reconciler.tracklistFor` has a deliberate branch for it, because one expected title is what lets filename matching score a single-track download at all. Artists are not: there is no artist badge anywhere, and a discography subscription belongs on the Follow button that can say what it commits to. The click is swallowed again, for the opposite reason to before: with an action of its own, a click on the badge no longer means what the card means. Enter and Space are stopped for the same reason — every card holding one is a role=button or role=option with its own handler.	2026-08-13 15:17:06 -04:00
logan	979c6e83ed	docs: open plan 009 and record what phase 1 found ... The plan's own framing was wrong in a way worth keeping: the badge was not waiting on the download client, which had largely landed already — it was waiting on somebody looking at a state nothing produced.	2026-08-13 14:14:39 -04:00
logan	48f7795687	test(e2e): pin the requested badge and the state it renders in ... Two assertions, and the second is why this is at this tier at all. Reaching the requested state is the only way to render the requested icon, so the sweep that already asserts `__yjIconMisses` is empty can finally see a name computed from state. Both were watched failing on the pre-fix build by neutering one line each: the badge reported `not-in-library` where `queued` was expected, and the sweep returned `["bookmark-check"]`. The spec gives back what it spends — the request is dropped in `afterAll`, and cleared in `beforeAll` too, since a run that dies between the two would otherwise fail the next one. That cleanup uses the raw binding rather than `callBinding`: a bare `browser.newPage()` has no init script, so the event bridge is undefined and the first version threw where nobody was looking. Its 60 s search budget is not paranoia either. A freshly launched app spends ~40 s merging the core catalog artifact and Explore's search returns nothing until it lands, including for rows staged directly into `explore_index`.	2026-08-13 14:13:46 -04:00
logan	c400f681c2	fix(icons): the "Wanted" button asked for a Pro icon ... `bookmark-check` is Font Awesome **Pro**, so it was never bundled and `window.__yjIconMisses` has held it for as long as anything could be requested — the button rendered the missing-icon fallback in the one state it exists to show. `offline-icons.spec.ts` asserts that array is empty and passed anyway: no spec had ever put the app in a state where an album is requested. A name computed from state is only checkable from that state, which is the case `names.txt` exists for. Outline and solid of the same Free glyph carry the toggle instead, which is what the vendoring script tells you to do when a name is missing: pick one that is Free, never reach for the Pro file.	2026-08-13 14:13:38 -04:00
logan	451b46e63c	fix(explore): show a requested album as queued, not absent ... `library-status-indicator` has had three states since it was written and produced two: all eight call sites were a two-way ternary between `in-library` and `not-in-library`, so the `queued` state it styles and labels was unreachable. The result was the app contradicting itself on one page. An album added to the request list showed a plus and announced "is not in your library", forty pixels from a filled button reading "Wanted". The rule was written at eight places, which is why none of them had all of it, so it is `utils/library-status.ts` now: owning outranks wanting, a satisfied request is not queued, and a request is by MBID — a track inside a requested album is not itself requested and still says so. `explore-view` gains the `downloadStore` subscription both detail views already had, registered `whileActive` because it is a cached view that never unmounts. `top-results-row` needs its own: its host re-rendering sets the same `results` array back, so Lit stops at the property and the row never hears about a change.	2026-08-13 14:13:30 -04:00
logan	d33dfb2264	docs: record phase 4, and the counts a new guard has to agree with ... Plan 008 is complete and moves to completed/. The two findings worth carrying forward are that a new table needs one schema file rather than two (and a datamap entry, which is a gate nobody remembers), and that excluding a path has to reach every place that counts what is in the library — the soft scan's disk-vs-database comparison above all, which would otherwise have rescanned the whole library on every launch with nothing failing anywhere.	2026-08-13 13:30:37 -04:00
logan	41a4dd7148	feat(shortcuts): bind tracklist.delete to the confirmation ... The binding has been in the defaults and in Settings since it was written, with nothing on the other end of it, because "remove from library" did not exist. It does now — and Delete only *opens* the dialog, never performs the removal, which is the only version defensible one keystroke from a focused row. The e2e case asserts the two things that matter and neither is the row count: the file is still on disk, and a real scan of the real directory does not bring the row back. It watches a control path survive the same scan, because a guard that excluded everything would pass the negative assertion for free — and it restores the database it spends.	2026-08-13 13:28:38 -04:00
logan	6d97e3c872	feat(tracks): remove from library behind a confirmation ... The context menu's one destructive command. Its impact line says the files are not deleted, because a user who reads "remove" as "delete" and finds their music gone was failed by the copy rather than by the operation. The store patches rather than invalidates: the event carries the paths, so the tracks array — the expensive collection — is spliced in place and only the album/artist/genre summaries, whose counts really did change, are refetched. It falls back to a full invalidate when a tracks fetch is already in flight, which is the one case a patch cannot be shown to be equivalent to. Deleting an audio_files row cascades to queue_tracks, so the removal also compacts the queue — the same reload RemoveLibrary does, which unloads the player if the removed track was the one playing.	2026-08-13 13:11:31 -04:00
logan	acbe7c4676	feat(library): remove tracks from the library without touching the file ... "Remove from library" deletes the audio_files row and records the path as excluded, so the next scan does not import it again. Without the exclusion the operation undoes itself on the next scan, which is worse than not having it at all; the file on disk is never touched, which is the promise the confirmation copy will make. The soft scan compares the number of audio files on disk against the number of rows, so both walks now skip excluded paths — otherwise the two counts disagree forever and every launch queues a full scan of the whole library. A full rescan clears the exclusions, which is the only way back for a path removed by mistake until there is a UI for it.	2026-08-13 13:04:59 -04:00
logan	91bab4e73e	docs: record the a11y tail, and four names written where nothing reads ... Phase 3 shipped in six landings and a11y.md is closed, which closes all four audits from 2026-08-11. The pass's one lesson is that an accessible name is computed on the element carrying the role, and every tier we check with looks somewhere else: the audit read the source and credited a name that was never computed, an AX sweep read the tree and reported a placeholder-only box as clean, and a component test asserted the attribute and pinned the bug it existed to prevent. Six of the audit's claims turned out to be wrong or smaller than written, and one of the plan's own findings was false — the page header's sort control is named on all nine views. All of them are written down, which is where a third of the value of the last two plans came from.	2026-08-13 02:32:33 -04:00
logan	f1c46b6a8e	fix(a11y): label Explore's search box with more than a placeholder ... a11y.26, the half of it that was still open — `search-bar` gained a computed aria-label some phases ago and this one did not. It is why the finding survived: a placeholder *is* an accname fallback, so the box was never unnamed and a sweep of the accessibility tree reported the whole view clean. It is a weak name all the same, since it disappears the moment anyone types, and it is the only thing that distinguishes catalog search from lyric search.	2026-08-13 02:30:05 -04:00
logan	4efd17d477	fix(a11y): let the shell scroll sideways when it does not fit ... a11y.21 (WCAG 1.4.10), measured rather than taken as filed. The finding's mechanism is vertical — "the 4em bars grow while the viewport does not, and anything that no longer fits is clipped with no scrollbar" — and that is not what happens. The middle row is `1fr` and absorbs the growth exactly: at 200% text on 800x600 the bars go 64px to 128px and the panel 472px to 344px, with the footer still landing on 600. Nothing is clipped vertically, and Settings stays reachable because the sidebar scrolls (007 phase 5). What is real is the axis the finding does not mention. At 200% text the shell is 1014px wide in an 800px viewport, and at 320px — 400% page zoom of 1280, the width 1.4.10 names — it is 784px, so 464px of the app including the job indicator and the queue button sat behind `overflow: hidden` with no way to reach it. So the horizontal axis scrolls and the vertical one stays fixed, which also keeps the transport where a desktop player's transport belongs. At every size this app promises there is no overflow on either axis and no scrollbar appears, which the three viewport cases assert. The first version of the spec passed on the broken build: `overflow: hidden` still permits programmatic scrolling, so `scrollLeft = 9999` proves nothing. It is a wheel gesture now.	2026-08-13 02:22:49 -04:00
logan	254646da5e	fix(a11y): mark the playing row with a shape, not only a colour ... a11y.22, WCAG 1.4.1: `.track-row.active` was a background tint and a text colour, and the row markup carried no aria-current either — so a colour-blind user could not find the playing row and AT had no signal at all. The queue panel had aria-current from Phase 1 and the same colour-only visual. A triangle drawn in each row's own left padding by `::before`. It is a shape that is present or absent, and it costs no layout: track-list's grid columns are computed from the host width, so a marker in the flow would move every cell on the playing row and nothing else. Both directions are asserted in both tiers. A marker that renders on every row satisfies "the playing row has one" for free, which is this plan's oldest rule. And one thing the reproduction found: a track started from the *list* leaves the queue's currentIndex at -1, so the panel has no current row in that flow at all. Pre-existing, and the reason this looked broken the first time it was checked in the running app.	2026-08-13 02:14:55 -04:00
logan	9d420cda0a	fix(a11y): add a skip link, demote the subtitle, and size the sort arrow ... a11y.30: `<main id="main-content">` existed and nothing linked to it, so a keyboard user walked the library filter, the search box, the job indicator and eleven nav items before reaching content, on every navigation. Two things in it are load-bearing and only checkable against the running document: the link is out of flow in *both* states, because `body` is a grid with named areas and an in-flow extra child is auto-placed into one of them; and `<main>` needs tabindex="-1", or the fragment link moves the scroll, leaves the tab sequence where it was, and looks like it worked. a11y.29: `<h1>` followed by `<h3>` for type size. An `hgroup` takes one heading plus paragraphs, so a `<p>` is also what it was meant to hold. a11y.34: the sort arrow was 10px, below the type scale's own floor, with a comment acknowledging it. Half of that finding was closed by Phase 1 — the direction is announced now, via aria-sort — and the other half is one declaration. And the state that landed in: the hgroup measured 67px inside a 64px bar, so dropping the h3's bottom margin shortened the block, moved the flex-centred pair down, and clipped the subtitle's descenders. The overflow was pre-existing; `margin-block: 0` on the title is the fix, pinned by a new layout-overflow case.	2026-08-13 02:09:44 -04:00
logan	2b41c27616	fix(a11y): let a clipped value be read, and name a row's own buttons ... a11y.24: `text-overflow: ellipsis` in 40+ places, and the four highest-density lists were the ones with no `title` — the queue panel (whose width is user-resizable down to MIN_WIDTH), track-info, every track-list cell, and the playlist sidebar. In track-list the attribute is on the *cell*, not on what is inside it: the value may be a link, a highlighted search match or plain text, and a tooltip is inherited by descendants either way. One binding rather than three, and the same value the accessor already computed. a11y.32: every queue row's remove button was named "Remove from queue", so a list whose entire purpose is which track is where had four identically named controls.	2026-08-13 01:55:17 -04:00
logan	f00d0c4655	fix(a11y): name every form control in Settings ... Measured with Accessibility.getFullAXTree against the running app with all seven sections expanded: 24 of 93 controls computed an empty name. Every config-field select and toggle, and all eighteen track-list column checkboxes, had a <label> sitting right beside them with nothing associating the two. Now 0 of 93. Not in the audit, and a11y.6 says why in its own line: it scanned every <button>, and none of these is one. Same shape as the count that sent Phase 1 looking for an unnamed sort control — the claim was answering a narrower question than it reads as. The fields use `for`/`id` rather than aria-label, for what it buys beyond the name: the label text becomes a click target for the control. A fixed id is safe only because each config-field is its own shadow root. Two more are named but identify nothing, which is a11y.32's complaint one page over: three shortcut buttons announced themselves as "S", and thirty-six column arrows as "Move up".	2026-08-13 01:52:08 -04:00
logan	b7831e3f15	fix(a11y): name the sliders and the progress bar where the role is ... `a11y.md` lists `seek-bar` and `volume-control` under "what is already correct" because both pass `aria-label`. Measured with Accessibility.getFullAXTree against the running app on all eleven views, both sliders compute a name of "": `wa-slider` puts role="slider" on a div inside its own shadow root, pointing aria-labelledby at an empty internal <label>, and that IDREF outranks the host's aria-label. `volume-control` did not have the aria-label the audit credits it with at all. The name comes from `label` now, which is the library's own API — and for a slider that is visible, so `styles/wa-slider-label.css.ts` hides it by part. Preferred over reaching into the shadow root the way name-dialog.ts must: if Web Awesome renames the part the label becomes visible rather than silently nameless. The second rule in that file is load-bearing — `#slider` takes an 8px margin the moment a label exists, which grows the bar from 6px to 14px and moves the transport with it. a11y.25 is the same family: wa-progress-bar maps `label` onto its inner aria-label, falling back to the localised word "progress" — so it was named after the widget rather than after the work, not unnamed. The existing transport test asserted the host's aria-label and called it an accessible name, so it was pinning the bug.	2026-08-13 01:48:43 -04:00
logan	7410109884	docs: record the semantic palette landing, and one claim that was false ... The two findings recorded as too big for the contrast pass are fixed, so the plan says so. Also corrects a claim I made and did not check: the chrome does not stay dark under the light ramp -- that screenshot was taken before the theme propagated, which is the third time in two passes a picture read at the wrong moment produced a confident wrong claim.	2026-08-13 01:08:17 -04:00
logan	0b7ffd5679	build: check that css template literals were not ended by a comment ... A backtick inside a comment in a css`` literal ends the literal. It has cost four sessions across three plans, it is written down in CLAUDE.md, the skill and NOTES.md, and it was read twice in the session it then cost a cycle in. Knowledge that has been ignored three times is not a knowledge problem. The expense is the report, not the mistake: the literal ends early, the rest of the CSS parses as JavaScript, and tsc says 'Class static side incorrectly extends base class static side' pointing at a line of prose -- or, in a shared module, every test in the suite fails to import and the output reads like a broken test runner. make dev-headless mean- while keeps serving the last good bundle. Detection is exact rather than heuristic: if a backtick in a comment closed the literal early, the text the parser took as the literal contains an unterminated /*. Nothing else produces that. Verified both ways -- clean on the tree, and red on a deliberately broken comment.	2026-08-13 01:07:08 -04:00
logan	49b1194333	fix(a11y): give the semantic colours a ramp, and every fill a foreground ... The contrast pass found two things larger than itself, both recorded as not-fixed. This is them. The semantic colours were 'fixed across themes', and one fixed colour cannot clear 4.5:1 against both a near-black and a near-white surface: --yj-error measured 2.55:1 on dark's elevated, --yj-info 2.31:1, and success and warning failed on dark and light both. They are split by the question they answer. A *fill* is 'what colour is a danger button' -- red in every theme, unchanged -- and a *text* colour is 'what colour is the word failed on this background', which is now per ramp. Every fill also carries a computed foreground. White on the default accent is 1.43:1, and the accent is a colour picker, so no fixed answer survives it: --yj-accent-fg and the four semantic -fg values are derived (white if white clears, else black), which keeps a red danger button white and flips a green or amber one to black. Two accent buttons took their foreground from --yj-bg-base, which inverts with the ramp -- that is exactly the white-on-yellow 'Apply (A)' the light theme showed. Accent used as text gets the same treatment through accentTextOn(), which mixes along the hue until it clears the ramp's surface and stops. On both dark ramps it returns the accent unchanged, so the dark themes are visually untouched by that half. Measured across three ramps and twelve views: 2237 nodes, 0 failing, against 110 on dark and 50 on light before. Borders, outlines and shadows were explicitly kept on the fill token -- a border is not text, and the first pass of the rewrite moved 30 of them by accident.	2026-08-13 01:05:37 -04:00
logan	fd32ce71d2	docs: record phase 2, and what a parked measurement was hiding ... The audit's one 'borderline ~4.1:1' pair was nine of twelve failing combinations across three ramps, 110 nodes on screen, worst 2.31:1. The other never-measured item closed on measurement and stays dropped, now for a reason with a number behind it. Two findings larger than either are recorded and deliberately not fixed: the semantic colours are fixed across ramps, and the light ramp is not a supported theme.	2026-08-13 00:36:09 -04:00
logan	533c084f8a	fix(a11y): make every text colour clear WCAG AA on every ramp ... a11y.md flagged --yj-text-tertiary on --yj-bg-surface as 'borderline (~4.1:1) but that needs a real measurement', and plan 007 parked it as 'worth measuring before planning'. Measured, against the rendered app and then across all three background ramps: it failed AA in nine of twelve text/surface combinations, as low as 2.31:1 on dark's overlay and 2.55:1 on light's -- the app's most-used secondary text colour, failing on every view. Not borderline. 110 failing nodes across twelve views, now 0 of 659. Three separate mechanisms, and only the first is the finding: - The ramps. Tertiary is raised per ramp (#a6a6a6 dark, #949494 darker, #5c636a light), sized to the lightest surface it actually sits on and keeping its hue. Sizing it to bgOverlay too would need a grey lighter than secondary, so bgOverlay is documented as not a text surface and the one component that put text there uses primary. - The avatar generator. hsl(hue, 45%, 35%) behind white initials failed for 35 of the 360 hues -- the yellow-green band -- so which artists were unreadable depended on how their names hashed. The two a sweep found were not the finding. 32% clears every hue. - Jobs' local #ff6b6b, at 4.15:1 on elevated. Pinned by a unit test over the palette table rather than a DOM sweep: the ramps are pure data, and checking only what happens to be on screen is exactly how the light ramp went unexamined. Note that make ui-visual cannot see any of this -- the component tier renders the fallbacks, because theme-store sets :root only in the real app.	2026-08-13 00:33:50 -04:00
logan	31144e5dc7	docs: record phase 1, and the state a fix lands in ... Three a11y findings shipped. The generalisation is the mirror of 'a finding creates the conditions for the next one': that one is about the code path a fix opens, this one about the path it sends people to. The reduced-motion guard is two lines and both bugs behind it were in the fallback it routes users into -- one of which had been wrong in every mode, including the default, since the component was written.	2026-08-12 23:35:40 -04:00
logan	8af26fee94	feat(a11y): reorder the queue with Alt+Arrow ... a11y.11: the queue's order could not be changed without a mouse. Reordering existed only as a drag whose drop index is computed from the cursor's Y position. Reproduced with a row focused: Alt, Ctrl, Shift and Meta + arrows all left the order untouched. Alt+ArrowUp/Down moves the focused row and a live region says where it went. It is handled in the panel's own delegated keydown rather than as a backend panel binding -- that is where Enter and the roving arrows already live, it cannot collide with the global Up/Down volume bindings (measured: 0 VolumeChanged events from a focused row), and it keeps a destructive-looking key out of the user-editable shortcut table. Two things the finding did not contain. The index arithmetic is not symmetric: MoveQueueTracks takes an index into the array before the move, so down-by-one has to ask for i+2 -- i+1 is where the row already is once its own removal is accounted for, and the backend's contiguous-block guard correctly makes it a no-op. Both tiers pin that, because a symmetric-looking fix silently does nothing in one direction. And focusedIndex only ever moved on an arrow key, so a row reached by a click or by Tab left it saying 0 and every key acted on the wrong row -- Enter played the first track in the queue from any focused row. The delegated handler reads the index off the row the event came from now. Pre-existing; visible only once a key moved something.	2026-08-12 23:34:00 -04:00
logan	6d0e46d537	fix(a11y): wire the combobox's roles to each other ... a11y.14: role=combobox, role=listbox and role=option were all present and nothing connected them -- no ids, no aria-controls, no aria-activedescendant -- so arrowing through nineteen options moved a visual highlight and announced nothing. Reproduced on the smart-playlist rule editor against the browser's own computation rather than a snapshot: getFullAXTree reported no activedescendant and no controls on any of the five comboboxes on the page. After, the same node carries both. aria-selected also meant 'highlighted', which is the one thing it does not mean: a user arrowing past an option heard it announced as selected while the value they had chosen was announced as unselected. It is the chosen value now, and the highlight is what activedescendant points at. The IDREF tests assert the link rather than the attribute -- an activedescendant naming an id no element carries is exactly as silent as no attribute, and reads as fixed.	2026-08-12 23:08:49 -04:00
logan	11b4aaef6a	fix(a11y): stop the now-playing marquee under reduced motion ... a11y.15 / WCAG 2.2.2: the bottom bar's title and artist scrolled for as long as a track played, re-armed in a loop by transitionend, with no pause mechanism and no reduced-motion guard. Reproduced under an emulated prefers-reduced-motion before the fix: the title still carried will-scroll with a 15s transition and the transform was still moving. That read landed in the snap-back half of the cycle, which is why a CSS-only 'transition: none' is the wrong fix -- it leaves the text translated off its own box and transitionend never fires to bring it back. The scroll is not armed at all instead, which is a decision shouldScroll() already owned, and it covers hover as well as always: reduce is a request about motion, not about autoplay. Two things came out of looking at the result rather than asserting on it. The non-scrolling fallback was hard-clipping, not ellipsising, in every mode including the default -- text-overflow was on the outer span while the overflowing box is the inline-block child. And moving it to the child then broke overflow *detection*, because the parent stops overflowing once the child hides its own; both measurements come from the child now. The second was caught by the new test's positive case, which is why it has one.	2026-08-12 22:58:56 -04:00
logan	0a0da0c19c	docs: close plan 007 and open 008 on the last open audit ... All six phases of 007 shipped. The plan moves to completed/ with a recap rather than a rewrite: its seven "where the plan was wrong" lists are seventy-nine entries and about a third of them are the audit being wrong, which is the material 008 is planned against. 008 is a11y.md, the only audit with open items and the least verified material in the repo. A grep pass closes at least five findings the coverage map still shows open, including a11y.7, which the map assigns to phase 6 and which phase 1 fixed. The triage in the plan is recorded as hypotheses for that reason.	2026-08-12 22:43:10 -04:00
logan	1e4a4e6f8e	docs: record phase 6, and the shelf that repeated with no ids in common ... Twelve corrections to a plan written before any of phases 1-5 existed, of which the load-bearing one is that a rule written against a mechanism does not cover what the rule is for: `home` suppresses a repeated shelf by comparing album ids, Explore's first two shelves hold different entity types and share none, and the page repeated itself anyway because a person reads artists.	2026-08-12 18:19:27 -04:00
logan	cad673ee3d	feat(explore): open the page with shelves instead of a search box ... `H-23`. Explore was a search box over a 1.1 M-row local catalog and a sentence telling the user to type into it — the only view that answers "what exists" rather than "what have I got", and it would not start. Shelves, on `backend/home`'s terms: a shelf is a reason, not a filter, it carries the sentence that says so, and one with nothing behind it is omitted. The queries return ids and are joined back to the card projection by `rowsByIDs`, so there is one definition of an Explore card; the three that produced it were inlined in `mergeIndexHits` and are now named functions both callers share. Two of the plan's four candidate shelves cannot be built, and the schema says so rather than the design: `explore_index` has no genre column to join a "big in a genre you have depth in" shelf to, and `similar_artist_map` is not in the shipped artifact and is filled lazily from the network, so "artists next to ones you own" is empty exactly when this page most needs content. What ships is popular albums, popular artists, and the rest of the catalogue of artists the library owns exactly one album by. Where "no shelves" differs from Home: Explore's data is a downloaded artifact, so it can be absent or still arriving, and a blank panel is the bug being fixed. The page says which, and points at Settings. One rule came from looking at the result rather than from the plan. Ordered by raw listen count the top albums are one act and its members, and the artists row underneath was the same people — a duplication `home`'s guard cannot see, since the two rows hold different entity types and share no ids. Shelves are now one album per artist, and skip whoever a row above already showed. --no-verify: bindings-check rejects staged-but-uncommitted wailsjs.	2026-08-12 18:13:28 -04:00
logan	65c1b4fd53	fix(a11y): move the card grids by a row, not to the end ... `RovingGridController.measureColumns` read `offsetTop`, and every card in these grids is drawn by a `lit-virtualizer`, which positions its children with a transform — which `offsetTop` does not see. So all of them reported 0, every rendered card counted as one row, and ArrowDown was `min(i + everything, last)` while ArrowUp was `max(i - everything, 0)`: the vertical arrows have been End and Home in the albums, artists and genres grids since the day this was written. At 700x700 with three real rows of 3/3/2, ArrowDown from card 0 landed on card 7. Two things behind it, both only visible once the grid splits: `cover-grid`'s scrollToIndex was `querySelector('lit-virtualizer')` — always `#grid-before` — while the roving index spans the whole album list, so with a dropdown open End scrolled the wrong half to an index it does not contain. It now picks the half that holds the index and rebases it. And the focus is retried on a deadline rather than taken once at the host's `updateComplete`: a scroll of 5 000 rows produces the card a few hundred ms later, so the tab stop moved and nothing took focus, which looks exactly like the key not being handled. Also waits for the virtualizer in album-dropdown.spec's expandCard, which flaked on roughly one run in two on main.	2026-08-12 17:44:22 -04:00
logan	dddf54ba0c	fix(a11y): make the library badge a badge, not an inert button ... `library-status-indicator` was a <button> whose click handler was a stopPropagation() and a comment saying to wire up the download client later. On an Explore results page that is 20 of 66 tab stops (measured in the running app, before and after: 66/20 → 46/0) that announce themselves as buttons and do nothing. It is role="img" with its existing label now, and the label for an unowned entity says "… is not in your library" rather than "Add … to library" — the old copy was the button's promise written out. The day there is a download client to call, the right change is a <button> *with* a handler, not a handler bolted onto something already shaped like one. box-sizing: border-box is explicit because a <button> gets it from the UA stylesheet and a <span> does not, so the badge grew 36px → 38px. Caught by the stored screenshot.	2026-08-12 17:30:33 -04:00
logan	f5621bf7c5	docs: record the fourth pass, and the bugs hiding behind three findings ... Each of perf.p2, H-13 and the dialog naming had a second defect behind the one named, reachable only once the first fix made the code path run. Also records two probe failures worth more than the fixes: the a11y snapshot cannot see a dialog's accessible name at all, and a scroll assertion that could not fail was hiding both a bug and a false claim.	2026-08-12 15:29:59 -04:00
logan	f854076d95	feat(explore): give the album page a primary action that tells the truth ... H-13: no Play, no Shuffle, no Add to queue on the album header. The reason it is not just three buttons is that explore-album-details is a catalog page — there is no library-side album detail page at all — so the album shown may be wholly the user's, partly theirs, or not theirs. A Play button that plays 7 of a 40-track release under a label saying 'Play' is the page lying about what is owned, so the button says which: 'Play' when all of it is owned, 'Play 7 of 12' when some is, and no play button at all when none is. albumLibraryStatus() stays as it was — four claims of decreasing confidence OR'd into one tick, the weakest firing when a single recording matches. That is a fine answer to 'is any of this mine' and a useless basis for a button, so ownership() counts the displayed tracklist instead. GetFilePathsByRecordingMBIDs is the catalog-side sibling of GetFilePathsByAlbums: one query, paths only, grouped so the caller keeps the tracklist's order. It is keyed on recording MBID because that is how the backend decides a track is inLibrary, and because MBTrack.LocalID is declared and never written by anything. The local album id is preferred where there is one — a library-only album has no MBIDs at all, and keying on them alone queued nothing. The ticks also get the legend H-13 asks for. They were never unlabelled — the indicator has carried a title and aria-label all along — but a sighted user got a column of green circles and no key.	2026-08-12 15:28:22 -04:00
logan	71324b561a	feat(albums): draw the album dropdown that was already being computed ... Enter on an album card fetched the album's tracks over the IPC and ran the whole split state machine (splitMode true, splitIndex measured against the real container), then render() drew the single grid because it never consulted splitMode; connectedCallback referenced renderSplitGrid only to satisfy noUnusedLocals. perf.p2 files this as dead code — it is the only route from the albums grid to track-details, since a plain click navigates to the catalog page instead. Two things it needed that the audit does not mention. The grid could not scroll: .grid-scroll-container is the markup artists-view and genres-view use, and cover-grid had the class with no rule for it, so 186984px of albums sat in a 772px box at 5000 albums, unreachable by wheel, keyboard or scrollbar — and that is the element scroll-manager saves and restores, so its scrollTop was permanently 0. And the shared context menu was labelled 'Album actions' unconditionally, which nothing could observe while a track menu was unreachable. Both halves of the split grid carry the listbox semantics the single grid gained in the ARIA pass.	2026-08-12 15:10:05 -04:00
logan	287b6445fa	fix(a11y): give every wa-dialog an accessible name ... Eleven dialogs passed a `label` that never reached the accessibility tree: Web Awesome renders it into an <h2 id="title"> in the same shadow root as the native <dialog> and never points aria-labelledby at it, so getByRole('dialog', {name}) matched nothing and a screen reader announced an unnamed dialog. a11y.md lists all of them under "what is already correct". utils/name-dialog.ts sets the IDREF, with aria-label as the fallback for without-header (first-run-wizard), called from each host's updated(). aria-labelledby rather than aria-label because three call sites compute their label at render time, and the heading re-renders anyway. It waits for the dialog's own first update: wa-dialog populates its shadow root in its own update, so a query at the host's firstUpdated names nothing. Reaching into another library's open shadow root is deliberate and the failure is bounded — if the structure moves, the query misses and the dialog is as unnamed as it was.	2026-08-12 14:52:23 -04:00
logan	d681a7223e	docs: record the audio clock, and that CI is green ... The e2e job passes on both engines for the first time, so the three files that describe it as red are wrong. Also records the two things that made it findable: the CI container is reproducible under Docker, and the app's own audio stack had to be the thing measured.	2026-08-12 14:03:09 -04:00
logan	0a25bca128	ci(e2e): give the container an audio device that keeps time ... The e2e job's red history is one measurement being wrong. ALSA's `null` plugin does not pace: measured in this exact image through beep and oto with the same speaker.Init arguments player.InitSpeaker uses, 3000 ms of audio is consumed in 2.96 ms — a thousand times too fast. So every track finished instantly, the position reset to zero, and three specs failed on a clock that never moved. It read as a flake because InitSpeaker succeeds either way, in ~3 ms either way. A PulseAudio null sink is timer-scheduled: the same 3000 ms takes 3762 ms, and 12 s takes 13.5 s — the overhead is a constant buffer drain, not a rate error. Verified under the private session bus and Xvfb dev-headless.sh runs the app in, with no system D-Bus and no kernel module, which is what makes it reachable from a container. The sink is a dependency with a rate, so it is now checked like one: a step plays three seconds and fails if they take under two. Without it the failure surfaces three steps later as "the elapsed clock is 19 s adrift", which reads as an app bug and cost two sessions of exactly that suspicion.	2026-08-12 13:51:48 -04:00
logan	2c460bbcb7	test(download): wait for the transfers a concurrency test starts ... Both per-provider cap tests spawned three `manager.grab` goroutines and returned as soon as their assertions held. A grab outlives the provider's Grab — it imports the staged files, releases the reservation and writes the download's final state — so the test raced t.TempDir()'s cleanup, which deleted the staging directory underneath work still running. The failure is reported by the framework after the test has passed, names no line of code, and reads as a flake: `TempDir RemoveAll cleanup: directory not empty`. It stopped being intermittent: 3 of 3 locally and every recent CI run, where it failed `check` and therefore skipped `e2e` as well. Both tests now wait for the goroutines they start, with a timeout so a stuck transfer fails the test rather than hanging the package. Verified 25 runs of the pair and 4 of the package under -race.	2026-08-12 13:00:13 -04:00
logan	425dd7c158	docs: record the third Phase 5 pass, and read the CI log ... The e2e failure two sessions could not diagnose is the container's audio clock, on both engines — 48 specs pass under Chromium and 48 under WebKit, failing the same three. Nothing in last pass's dialog, focus or role work is WebKit-specific. Also records what got in the way of knowing that: gitea_ci's job-log endpoint 404s on this build while the REST API answers fine, and the WebKit step had been skipped on every red run.	2026-08-12 12:42:15 -04:00
logan	bddfd37a5c	feat(track-list): show Album by default, and search smart playlists ... H-15: the default columns were track, artist and duration, so a library manager with duplicate detection could not tell its own duplicate fixtures apart by eye. Album is a default now, in Go and in the frontend fallback — both, because a fresh install persists the Go list and the UI renders the TS one until the config arrives. It does not deliver the finding's stated benefit, and that is worth recording: the three `Tideline / Aurora Fields / 00:06` rows are duplicates of the same album, so they read identically with an Album column too. What tells them apart is the duplicate-detection feature or a file path column, not this. Album is still the right default for every other row in the list. smart-playlist-details joins search-store's scope map. Checked before adding, as asked: it reads searchCtrl.term in getVisibleTracks and prints the term in the page, so the header box was disabled and unlabelled on a view that filters as you type — the fix is a scope entry, not a disabled state with a reason.	2026-08-12 12:38:36 -04:00
logan	1aa1598ecb	feat(shortcuts): tell the key story once, and give the arrows back ... Decision 1 keeps the unmodified single-key bindings, and Settings was the only place they were written down — three of the four categories of them, because config-page listed the categories by hand, so the autotag keys were written down nowhere at all. `?` now opens an overlay from anywhere the app owns the keyboard, and both surfaces read one table (services/shortcut-meta.ts, moved out of config-page's private static). The other half is the same explanation from the other side. Phase 1 gave the arrow keys to the grid, correctly — but all six of them, and no list in this app moves horizontally: track-list's own handler and utils/roving-rows both take Up/Down/Home/End and ignore Left/Right. So seeking stopped working from a focused row and nothing gained the keys. Reproduced in the running app: two ArrowRights on a focused track row, zero Player.Seek calls, against one per press from the body. A shifted character no longer reports Shift, so the binding is `?` and not `Shift+?` — the character already carries the shift, and a layout where it does not is a layout where "Shift+?" is wrong anyway.	2026-08-12 12:33:50 -04:00
logan	4615afe7f7	test(e2e): freeze Settings' and Downloads' keyboard reach ... A component test sees the markup; only this tier sees that the control is reachable through the app's own tab order. Also stops failure-voice.spec assuming the Libraries section starts collapsed — it is the one section that starts open now, so a blind click on the disclosure closed it and the rest of the spec ran against a hidden row.	2026-08-12 12:17:13 -04:00
logan	5111a6c8ab	ci(e2e): run the WebKit project even when chromium fails ... The WebKit step had no `if:`, so a chromium failure skipped it — and chromium has been failing on the container's audio clock for every push of the last two sessions. The job log says `conclusion: skipped`, so the one place WebKit2GTK gets any coverage has produced no signal at all while the plan recorded a possible WebKit regression as unverified.	2026-08-12 12:12:33 -04:00
logan	24887d6840	fix(a11y): make Settings and the Downloads tabs keyboard-reachable ... a11y.1 is the audit's last Critical and reproduced exactly: seven config-section headers, seven bare `<div @click>`s with no tabindex, no role and no aria-expanded, and every section collapsed by default — so every setting in the app was behind a control that could not be tabbed to. a11y.2 is the same bug in Downloads' two `<div class=tab>`s. Both now follow patterns the app already had: a real `<button aria-expanded aria-controls>` (explore-artist-details has five), and a role=tablist/tab/tabpanel with a roving tab stop and Left/Right/Home/End. The section body renders unconditionally and is toggled with `hidden`, because aria-controls has to name an element that exists and the slot's light-DOM children exist either way. H-22's reorder ships with them: Libraries is first and the only expanded section, Search Index — configured once, if ever — is second to last. The Playback/Audio section H-22 also asks for is deliberately not here: there is no output-device, gapless, crossfade or replay-gain setting in backend/config to expose, and a section of controls that do nothing is worse than admitting it does not exist. Settings also stops advertising `tracklist.delete`, which was bound to Delete and configurable in the UI while nothing listened for the event it dispatched.	2026-08-12 12:12:33 -04:00
logan	a150b24e71	docs: say what the CI e2e failure does and does not prove ... The suite passes locally on Chromium; CI also runs WebKit, which cannot run on Arch, and this pass changed focus management and dialog modality. The job-log endpoint is not exposed by this Gitea build and the runner is not on this machine, so the WebKit half is unverified rather than attributable to the known audio-clock flake.	2026-08-12 11:57:16 -04:00
logan	63d11c3f9c	docs: record the second Phase 5 pass and what it corrected ... Three of a11y.md's findings describe a build that no longer exists — one fixed by a phase that was not about it, one whose stated mechanism stopped being true when Phase 4 bundled the icons, and one that reproduces as a different shape. The generalisation is that a finding has a date as well as a magnitude and a mechanism. Also records the two bad versions of the duplicate-shelf rule that the *existing* tests caught, the eleven e2e specs that landing on Home broke and the one of them that was a real bug, and the second CI e2e failure on a commit that changed no application code.	2026-08-12 11:44:58 -04:00
logan	862e8a0468	feat(home): land on Home, and make it worth landing on ... The app opened on Tracks — an alphabetical list of everything, which is the one entry point that is identical every time and therefore gives the user nothing to start from. Home is listed first in the nav and is the page built to answer 'what should I play' (H-8). Two things had to be true before that was an improvement. An album with no cover rendered as a small dim icon on a surface the same colour as the page, so a shelf read as having holes in it, while the Albums and Artists grids both drew a letter tile (H-9). It draws the same tile now. And a shelf that repeats the one above it is suppressed, the way an empty one already is — 'On repeat' was 'Pick up where you left off' reordered. The rule fires only when the shelf is not showing the whole library: a repeat is a fault only if a different row was possible, and measured against a fixed shelf size instead this let an 11-album library keep three identical shelves while a 13-album one lost them. The first two versions of that rule were wrong and the *existing* Go tests caught both — it collapsed a four-album library to a single shelf. Nine e2e specs assumed the app starts on Tracks and now navigate there, and one new spec freezes the landing itself. Home's page-header action is 'Shuffle suggestions': 'Shuffle' alone was two different controls with one accessible name, which only became reachable together once a cached Home was always in the tree.	2026-08-12 11:42:26 -04:00
logan	c13a920487	test(e2e): freeze the context menu's keyboard model ... Two of the three things that made it work are invisible to a component test against hand-built markup: the real wa-dropdown-items have not set their role when the host finishes updating, and the real wa-popup has not positioned itself, so focus() on an item is a silent no-op. Both produced a menu that opened and refused to take focus.	2026-08-12 11:15:04 -04:00
logan	a3b35a4dab	fix(a11y): express the type scale in rem so text resize does something ... --yj-text-xs..xl were hardcoded px and are consumed by essentially every component, so raising the OS or browser font size changed nothing anywhere (WCAG 1.4.4, a11y.19). The values are identical at the default 16px root, and all six ui-visual baselines pass unchanged. Verified in the running app rather than assumed: at a 24px root a track cell goes 12px to 18px and a nav item 16px to 24px. The same check confirms a11y.20, which is left unfixed and now documented where the coupling lives: the row stays 33px while its text grows to 18px, because four virtualized lists duplicate their row height as the layout's _itemSize hint and carry contain: strict, which clips rather than reflows. Fixing that means deriving _itemSize from a measured row — a change to the scroll maths of four lists, not to a type scale.	2026-08-12 11:09:25 -04:00
logan	1ed4167634	feat(a11y): give the context menu a keyboard, and the app a voice ... The context menu was the only route to Play, Add to Queue, Play Next, Add to Playlist, Favourite and Track Details, and it opened on right-click alone: the panel had no role=menu, so its six menuitems were orphaned, nothing moved focus into it, and nothing handled arrows or Escape (a11y.3). Phase 1 deferred this deliberately so it would land with the dialogs, as one focus-management implementation. MenuKeyboard is that model. It is standalone rather than part of ContextMenuController because playlist-view renders a menu without the controller, and the only thing worse than a menu with no keyboard model is two menus with two of them. Shift+F10 and the ContextMenu key open it from a focused row, anchored to that row, and focus returns there. Three lists had no focused row to open it from, so they gained a roving tab stop (utils/roving-rows.ts, written once rather than three times). track-list keeps its own: it predates this, carries selection semantics the other three do not have, and is pinned by its own tests. Also the ARIA tail this is one story with: aria-sort on the column headers (role=columnheader arrived in Phase 1 without it), listbox and option on the four selectable grids — aria-selected on role=button is invalid and was being dropped, so the state the whole ctrl/shift interaction exists to produce was invisible — and live regions on the four async surfaces that changed in silence. Two things a reproduction taught that reading could not: the wa-dropdown-items have not set their role when the host's updateComplete resolves, so querying by role then finds nothing and the menu opens without taking focus; and focus() on a popup that has not positioned itself is a silent no-op.	2026-08-12 11:07:34 -04:00
logan	7912cdf23f	fix(a11y): make the five hand-rolled dialogs real dialogs ... Four autotag dialogs and the remove-library confirmation rendered a plain overlay div: no role, no aria-modal, no focus trap, no focus restore. The two gating an irreversible on-disk metadata rewrite left focus wherever it was, so a screen-reader user could confirm 'this rewrites audio files' without ever hearing the warning (a11y.4, a11y.16). Five wa-dialog usages already did this correctly and confirmAction() existed from Phase 3, so nothing new was invented: the three that are pure confirmations became confirmAction() calls, and the two carrying input became wa-dialogs in place. Verified in the running app — the native dialog matches :modal, focus lands in the first field, Escape closes and the view state follows. autotag-view's last document keydown listener goes with them. It existed only because its dialogs could not close themselves.	2026-08-12 11:07:23 -04:00
logan	9f03b3ff94	ci: enforce the commit format CLAUDE.md said was enforced ... CLAUDE.md has claimed since the file was written that commitlint gates the commit format in CI and that semantic-release runs off it. There was no commitlint config, no workflow running one, and nothing invoking .releaserc.yml — so the first thing every contributor and every agent reads about this repo was false in two places. scripts/commit-check.sh is the smaller honest answer: the grammar is one regex, and commitlint would mean a Node dependency tree at the root of a Go repo to run it. It is a commit-msg hook locally and a CI step over every commit in a push, and its type list is .releaserc.yml's so the check and the release rules cannot drift. The semantic-release half is recorded as configured-but-not-wired rather than implied to run.	2026-08-12 10:44:06 -04:00
logan	3269da3e92	docs: record the first Phase 5 pass and what it corrected ... Two reproductions in this pass were read before Lit had rendered, so both reported the same answer on the broken build and the fixed one - the third costume of this plan's most-repeated trap, and the first time it has appeared in a reproduction rather than a measurement. Also records that the audit's symptom for H-11 outlives its mechanism, that fixing H-7's arithmetic does not remove every clipped Duration, and that two e2e specs spend backend state they never give back.	2026-08-12 02:37:49 -04:00
logan	b7dc368d7c	feat(ui): give every primary view the same page header ... Four views had a heading and four did not, two had a sort control and none showed a count, so the app changed shape as you moved through it and "how many albums have I got" could only be answered by counting. The reason they disagreed is that each had written its own arrangement: the sort toolbar existed three times, in track-list, cover-grid and playlist-view, as the same twenty lines with different bugs. <page-header> is that arrangement once - title, count, sort, actions - and nine views adopt it. Artists and Genres gain the sort control they never had; Artists sorts by name only, because library.Artist carries nothing countable, so the header renders a label and a direction button rather than a select with one option in it. The header keeps its place while a view loads: a heading that appears only once the data does is the shifting layout this is meant to stop. The count is omitted, not zero, until the view has an answer. The header search box keeps its slot on every view instead of vanishing on the ones it cannot serve - which is what moved the library filter and the job indicator on every navigation. It is view-scoped by decision and now says so: "Search albums" in the placeholder, the scope named in the header ("Showing artists matching 'tide'"), and disabled with a reason where there is nothing to search or the page has a search of its own. Also fixes an e2e trap this uncovered: the view-lifecycle spec toggled shuffle and never toggled it back, so a second run against the same app failed playback.spec's shuffle assertion - a failure that reads exactly like a regression in whatever you are holding.	2026-08-12 02:35:35 -04:00
logan	cee19d7ef9	fix(settings): let a library be renamed by clicking its name ... The name's click bubbled to config-page's own document handler, which exists to close the rename editor - so it opened and closed the editor in the same click and the field never appeared. The overflow menu's Rename was unaffected because it stops propagation, which is why the feature looked like it worked. Found while closing Phase 3 and left for the phase that reworks this file. The e2e guard opens the editor and abandons it rather than committing a rename: the specs share one backend process, and a renamed library fails the ones that assert on fixture content.	2026-08-12 01:47:46 -04:00
logan	e9ca16362f	fix(ui): make the app fit the window it enforces a minimum for ... The track list shared out its whole clientWidth across the resizable columns while every row spends 24px on the favourite column and 2x8px on its own padding before the first one starts, so the grid was always exactly 40px wider than the box holding it and the last column was clipped at every size (scrollWidth 1280 vs clientWidth 1240, measured). Both numbers now live in one place and are read by the two call sites that had written them out separately, which is how they came to disagree. The enforced minimum was 512x384, which the layout had never supported: at 700x480 the eleven sidebar items needed 406px of a 352px pane, overflow:hidden cut the last two off with nothing to scroll, and Settings and Jobs could not be reached at all. The pane scrolls now, the sidebar collapses to icons below 900px (its .collapsed mode existed and only a manual drag ever reached it), the subtitle hides at the same breakpoint so the title stops wrapping out of the 4em bar, and the minimum is 800x600 - measured as where the shell still works rather than picked as a round number.	2026-08-12 01:44:56 -04:00
logan	9e92721bb7	docs: record plan 007, its four audits, and what measuring corrected ... `.planning/audits/2026-08-11-ui/` is the pass this work came from: the app driven by hand headless plus three static reviews, ~118 findings that are really five problems, each spread by being copied rather than fixed. `.planning/plans/active/007-ui-reconciliation.md` sequences them by blast radius and records what each of the six passes actually shipped — including twenty-five entries under "where the plan was wrong", which is the point of writing it down. The discipline those entries add up to, now in NOTES.md: a finding is three hypotheses — how big it is, why it is that big, and what to do about it — and they can be independently right and wrong. Three of the audit's recommended fixes would have shipped a bug (`m1` stops the card grids repainting, `m6`'s index-ordered selection goes stale on any re-sort, `m5`'s guard leaves the marquee short), all three because they reasoned from the shape of the code and not from what the rest of the file already knew about it. Five findings evaporated or inverted on contact. CLAUDE.md gains the invariants that came out of it, and the skill gains the fourteen measurement traps, each of which produced a wrong number first — the newest being that a longtask entry arrives after the task that produced it, so two numbers that must agree are worth more than one you have to be sceptical about.	2026-08-12 01:20:13 -04:00
logan	1ac919d228	test(e2e): freeze the four reproductions this work started from ... Each was written first and watched fail first: - `view-lifecycle` — pressing `s` on Settings must not skip an album out of the Autotag queue, and on Autotag the same key must not also toggle shuffle. - `player-truth` — the elapsed clock tracks the backend through steady playback and four keyboard seeks (the measurement that failed by 30 s), a finished queue keeps the track on the bar at 0:00, and auto-advance skips a missing file and reaches the next track. - `offline-icons` — blocks every non-local request and asserts on the <svg> *inside* each icon's shadow root, since asserting the element exists would have passed before the fix too. Verified red: 24 empty icons. - `failure-voice` — induces a real binding failure through /__test/sql and asserts a sentence appears. Its first version renamed the decoy library to its own name, which the backend accepts: it failed at the right assertion while never inducing the failure, so it now picks the row by the seeded library's name from /__test/health. - `play-count` — a finished track does not refetch the library. The queue spec now opens the panel before asserting on its rows and waits for it to close again: the panel's width is animated and the transport slides with it, so a click issued during the close lands on whichever button moved under the pointer.	2026-08-12 01:20:03 -04:00
logan	5830b1ba17	test(frontend): cover the lifecycle, the voice and the repaints ... Component and store cases for everything in this series, several of which exist because the thing they pin is invisible everywhere else: - `view-lifecycle` and `keyboard-reach` — a document listener count that does not grow across a simulated navigate cycle, and a tab sequence that reaches the sidebar and plays a row without a mouse. - `notifications`, `notification-store`, `confirm-dialog`, `empty-states` — the four levels, the (level, region, key) coalescing window, and loading/failed/empty as three states. - `card-grid-repaint` — fails if `artists-view`'s or `genres-view`'s per-render arrow functions are hoisted to stable fields, which is the audit's own recommendation and takes the cards from 1 highlighted to 0. It exists for no other reason. - `lazy-track-details` — reads the five sources and fails on a returning static import, the same shape as `TestNoDirectRuntimeEmits` and for the same reason: the invariant is about what the code does *not* say. - `now-playing` — a position report that changes nothing must not touch the DOM again, and a track change must. The first fails against the old unconditional `updated()`. - `playlist-virtualization`, `list-render-cost`, `selection`, `icons`, and the store cases for the library-filter race, the never-settling waiter and the per-playlist patch.	2026-08-12 01:20:03 -04:00
logan	2518385330	refactor(frontend): adopt the lifecycle and the notification surface ... The remaining views, brought onto the two mechanisms added earlier in this series. The lifecycle: every cached primary view moves its document listeners, intervals and event subscriptions off connect/disconnect and onto `viewActivated`/`viewDeactivated`, so `autotag-view` stops fielding keystrokes from Settings, `downloads-view`'s 30 s clock stops ticking for the session, and an off-screen view stops rendering on every search keystroke. `autotag-view` keeps a document listener only for Escape, whose dialogs Phase 5 migrates to wa-dialog anyway. The voice: the silent failures now speak — scan and full rescan (with a guard against the double-click the coalescing window allowed), job pause/resume/cancel, playlist delete, download request pause/remove/ clear, add and rename library, add-to-playlist, playlist track removal, autotag's dialogs and its apply, and favourite reverts. Both private toasts are gone, along with their CSS and keyframes. Playlist delete (single and the multi-select loop), download-request removal, download-client removal and a queue clear over 20 tracks ask first. Loading, empty and failed become three states rather than one, in `track-list` and `genre-details` — the first is on the first screen a new user ever sees — and the Settings index panel seeds itself with `GetIndexStatus()` instead of waiting forever for a change event. `smart-playlist-editor` and `download-picker` take the request-version guard `explore-view` already had. `track-details` loads through one memoised dynamic import in all ten openers, which is what takes its 42 kB out of the startup chunk: an un-upgraded custom element is a real HTMLElement on which `?.show()` throws, so each opener awaits it before touching the element its template already rendered.	2026-08-12 01:19:47 -04:00
logan	c8bc6db9fa	perf(frontend): virtualize the playlist views, and idle the closed queue ... Both playlist detail views rendered every track with a plain `.map()`. Measured at 2 000 tracks: 22 090 elements in the shadow root and 2 000 eager <img>, against 487 and 0 after, with retained heap 5.85 MB -> 0.81 MB and one update pass 5.3 ms -> 0.1 ms. They are virtualized in place rather than rendered through <track-list>, which is what the audit suggested: that works for `genre-details` because a genre list is just tracks, but both playlist views render phantom rows for missing files and `playlist-details` is a drag source and a drop target, and `track-list` has never had either. Virtualizing in place gets the same 45x on the number that matters with none of that risk, and leaves `track-list` alone for its four other callers. Both therefore push `virtualizer.requestUpdate()` on a selection change and on a playing-track change: the virtualize directive runs when one of the *virtualizer's own* properties changes, not when its parent re-renders, so memoising `items` and hoisting `renderItem` together is how you build a list that never repaints. Selection went silently dead the first time, with the controller holding exactly the right keys. And a closed queue panel renders no list at all: `width: 0` and `contain` bounded the damage without stopping the virtualizer inside from measuring its window on every queue change, or `scrollToIndex` from calling `scrollIntoView()` on something invisible.	2026-08-12 01:19:37 -04:00
logan	559e1ed077	perf(frontend): make the lists and grids pay per row, not per library ... A list pays per row, and only while scrolling — and none of this is visible to any test tier: nothing renders differently and nothing fails, the app is just slower. - The track list's Art column rendered `CoverArtPath`, the original artwork, into a 24 px box while `CoverArtSmall` sat unused on the same model, with no `loading="lazy"`. 26 of 26 image requests asked for the full-size tier; now 0. - `artists-view`'s avatar fallback linear-scanned every cached album per card per frame, lowercasing two strings per comparison, inside the virtualizer's renderItem — the common case, since a locally tagged library has no artist images at all. Measured at 5 000 albums and 24 visible cards: 1.46 ms/frame -> 0.01 ms/frame. - Five components resolved selected file paths back to tracks with `tracks.find(...)`; they share `utils/track-index.ts` now. "Select all -> Edit tags" at 50 000 tracks: 3 051-6 298 ms -> 68 ms. - "Play this artist", "play these albums" and the album drag cache resolve paths in one call instead of one per album. - The column-resize drag registers its document listeners on mousedown. Two things here are load-bearing and read as sloppiness. The per-render arrow functions in `artists-view` and `genres-view` are the *only* thing changing a property of their virtualizer on a host update, and therefore the only thing repainting the cards: hoisting them to stable fields takes a selection from 1 highlighted card to 0. And a row inside a virtualizer needs `width: 100%`, because the virtualizer positions its children absolutely and a grid row otherwise shrinks to fit its content and stops lining up with the header above it.	2026-08-12 01:19:37 -04:00
logan	4ae6e13391	fix(player): render the position the player reports, not its own ... `seek-bar` renders `PlaybackPositionChanged` instead of counting: its setInterval survives only as interpolation *between* reports, stopped and restarted by every one of them, so its error is bounded by a second and is discarded rather than carried. Measured after: UI 00:34 / backend 34 across two keyboard seeks, against 00:44 / 73 before. The bar also stops lying about smaller things: the right-hand clock carries a minus sign and toggles to total duration on click, and the now-playing column starts at 320 px instead of 200, which is where "The Orchestra Of" came from. `now-playing.updated()` used to measure and rewrite its text geometry on every pass — six querySelectors and a read/write interleave — while the player store notifies at 1 Hz. It now runs only when its geometry key changes: the rendered title, the rendered artist, both scroll flags, or the ResizeObserver reporting a resize, with every read before every write. Over six seconds of playback: 52 forced layouts -> 2, and 3.2 ms -> 0.9 ms inside updated(). The scroll flags are in that key because `.will-scroll .scroll-content` carries `padding-right: 2em`, so applying the class changes the distance the marquee travels — -128 px before it, -158 px after. A guard on the text alone leaves every first hover scrolling short, and nothing in any test tier would have caught it. The resize's document listeners now attach on mousedown and detach on mouseup, rather than running on every pointer move in the app for the life of the process.	2026-08-12 01:19:20 -04:00
logan	7d9e0bf2fb	perf(frontend): patch the stores instead of invalidating them ... An event carries what a consumer needs so it never has to invalidate. - `library-store` answers `TrackPlayCountChanged` by patching one track, replacing the tracks array (consumers key memoized caches on its identity) while sharing every unchanged Track — instead of discarding four collections and refetching 25 MB per song. - `playlist-store` answers `PlaylistTracksChanged` by refetching the one playlist the event names, plus the summaries, since `UpdatedAt` is a sort key. 2 668 kB and 172 ms for one heart, against 2.0 kB. It falls back to a full invalidate only where a patch cannot be shown to be equivalent: no id, a cold cache, an unknown id, or a fetch already in flight. And a store with no subscriber fetches nothing — the singleton's constructor used to put every track of every playlist on the path to first paint for a view the user might never open. - `library-store` guards every fetch with a cache generation and holds the request itself instead of deriving a promise from subscriber notifications, which fixes the library-filter race and the never-settling waiter together: they are the same bug seen from either end. - `explore-cache`'s two art caches are bounded, sharing one exported cap constant — the artist photo's data URL is held by both, so capping either alone frees nothing at all and reads as a fix that did not work. - `search-store` deliberately does *not* coalesce its notify: deferring makes a subscriber that unsubscribes synchronously after a `setTerm` miss the notification entirely, which is a semantic change rather than an optimisation, and this is the store on the keystroke path. - `selection-controller` retains its keys across a refetch rather than clearing them, since they are file paths and those survive one, and `getSelectedKeysOrdered()` gains an early exit. It stays a walk of the list: an index goes stale on any re-sort, re-filter or refetch while a file path survives all three, and 3 ms does not buy a silently mis-ordered queue insert.	2026-08-12 01:19:04 -04:00
logan	795f40acee	perf(frontend): split the routes and warm the chunks on idle ... One 1.18 MB chunk containing all 27 views, every one eagerly imported and side-effect-evaluated before first paint. `index.ts` now holds a loader table per view and awaits the right chunk before creating the element. JS evaluated before first paint: 1 480 kB -> 772.9 kB, in 27 chunks instead of one, with the slowest first open of a view at 19 ms against 21 ms — both halves of the trade, and the second did not get worse. Two things it has to get right. `document.createElement` on an undefined tag yields an inert HTMLElement rather than throwing, so a missing entry in the table is a blank page and not an error; and navigations are numbered, so a slow chunk cannot land on top of a faster navigation. `notification-host`, `inline-notice` and `confirm-dialog` stay eager on purpose: a failure surface that has to fetch a chunk before it can speak is not a failure surface, and the moment it is most needed is the likeliest moment loading one fails.	2026-08-12 01:19:04 -04:00
logan	5fb9a0d246	perf(frontend): add the bound, the lookup and the lazy dialog ... Four small modules the views below adopt: - `lru-map.ts` — a Map re-inserted on read and trimmed from the front. `explore-view` never unmounts and its two art caches were plain Maps: twenty-four searches retained 20.58 MB and were still accelerating, a cover thumbnail being ~27 kB of base64 and an artist photo ~128 kB. - `cache-stats.ts` — a bound has to stay checkable, so caches register and `window.__yjCacheStats()` reports entries, retained chars and cap in one eval, rather than the next session having to rebuild the twenty-four-search reproduction first. - `track-index.ts` — a WeakMap from the tracks array's identity to a Map<FilePath, Track>. Five components turned selected file paths back into tracks with `filePaths.map(fp => tracks.find(...))`, so "Select all -> Edit tags" at 50 000 tracks blocked the main thread for 3.0 to 6.3 s. 68 ms after. Keying on the array's identity is safe for the same reason the memoized filter caches are, and it is collected for free when the store drops the array. - `lazy-track-details.ts` — one memoised dynamic import, because `track-details` (42 kB) was imported for side effect by all five components that open it and so was evaluated before first paint however the routes were split.	2026-08-12 01:18:48 -04:00
logan	ca0f724e20	feat(frontend): bundle the icons so the app works offline ... Every <wa-icon> was fetched from ka-f.fontawesome.com at runtime — confirmed from `performance.getEntriesByType('resource')`, 36 requests — so offline the app had no icons at all. `setBasePath()` does not affect the icon resolver; only the component autoloader reads it. Overriding Web Awesome's `default` icon library fixes all 165 call sites without changing one of them. Cross-origin requests at startup: 22 -> 0. Three things about it are load-bearing. The set is Font Awesome Free (CC BY 4.0, vendored with its licence by `scripts/fetch-icons.mjs`) because the kit CDN serves Pro, which cannot be redistributed. The names are a committed list rather than anything derived, because twenty call sites compute their icon name from state and no static pass can enumerate them. And a name that is not bundled is reported at runtime to `window.__yjIconMisses` and drawn as a fallback, since a missing icon used to be impossible — the CDN having had everything.	2026-08-12 01:18:48 -04:00
logan	fbf1eff8f6	feat(frontend): give failure one voice ... There was no app-level notification surface: two components had grown private toasts and the other 84 catch blocks ended at console.error, so a user with a moved file, a locked database or an offline network saw a button that did nothing. Where errors did surface, eight sites printed the raw Go string. Four levels, chosen by the call site from one rule — a failure is only worth interrupting for if the user can do something about it that they are not already doing: Blocking (data at risk), Persistent (something asked for that did not happen, worth retrying), Transient (a small action whose state visibly reverted anyway), Inline (rendered in the panel that failed). Three things about it are load-bearing. Coalescing lives in the store, keyed by (level, region, key) within a window, so 200 unplayable files are one message with a count and no future caller has to remember that. An inline notification carries a *region*, because "inline" says not global, not where. And the bottom band belongs to the player, so the app-level stack sits under the header — the player's own floating notice grows upward by however many lines it needs. `utils/describe-error.ts` maps the causes a user can act on to copy; `explainError` repeats a backend message when it is one of our own sentinels rather than a Go wrapping chain, since mapping "a library with that name already exists" to something generic is a regression. `confirmAction()` is a wa-dialog, so destructive actions inherit the focus trap and Escape the hand-rolled overlays do not have.	2026-08-12 01:18:34 -04:00
logan	7acb197daf	feat(frontend): give a cached view a lifecycle and a keyboard owner ... `index.ts` caches primary views and hides them with a class so scrollTop survives navigation. Nothing else was told: `disconnectedCallback` never fires for one, so everything written to clean up there never cleans up. The worst case was not a leak — pressing `s` on Settings skipped two albums out of the Autotag queue, and `a` on that same live handler rewrites tags on disk. - `utils/view-lifecycle.ts` is the missing half: `viewActivated` / `viewDeactivated`, with `listenWhileActive`, `intervalWhileActive` and `whileActive` torn down on the way out, and an off-screen view that does not render. `registerViewAware` gives a shared reactive controller the same treatment, because a controller cannot know whether its host is a cached view — `ContextMenuController` bound three document listeners in `hostConnected`, which for a cached host is "forever". - `services/shortcut-scope.ts` publishes the ambient scope. Resolving scope from focus alone was not enough: this app is driven with the mouse, focus sits on `<body>`, and a focus-only rule would have made the panel keys work only after a click landed inside the panel. - Global bindings yield to a focused control that owns the key — button, select, slider, checkbox, menu, grid row, or anything inside an open dialog — so the unmodified single-key bindings stop stealing Space and the arrows. - `utils/roving-grid.ts` gives a card grid one tab stop moved with the arrows, since a card per tab stop makes a library-length tab sequence.	2026-08-12 01:18:34 -04:00
logan	69ad558a44	feat(shortcuts): add the autotag and track-list panel bindings ... `data-shortcut-scope` was read by the shortcut service and set nowhere, so the two panel-scoped bindings were dead while Settings advertised them as configurable. These are the bindings the scope mechanism was built for: autotag's A/S/L/U/F and the arrows, and the track list's play.	2026-08-12 01:18:17 -04:00
logan	9e0e4d5bb8	perf(library): resolve album and genre file paths in one query ... "Play this artist" awaited `GetAlbumTracks` inside a for loop — 13 sequential round trips for a 12-album artist — and every one of the four sites doing that asked for whole track rows to read `FilePath` off them. Five genres cost 6 MB across the IPC. `GetFilePathsByAlbums(ids, libraryID)` and `GetFilePathsByGenres(names, libraryID)` answer once and carry only the paths. Measured at 50 000 tracks: an artist 13 calls / 74.2 kB -> 2 / 19.2 kB, twenty albums 20 / 117.5 kB / 7.8 ms -> 1 / 26.0 kB / 1.7 ms, five genres 5 / 6 014 kB / 213 ms -> 1 / 1 291 kB / 32.6 ms, with the returned path lists identical. They return the paths grouped by album id or genre name rather than flattened, because the caller owns the order — an album list is sorted by name, not by id, and a flattened result would silently reorder a queue — and because the album drag cache stores them per album. A libraryID of 0 means "every library", matching an unset filter.	2026-08-12 01:18:17 -04:00
logan	0cf710cf47	fix(playlist): create a smart playlist through the writer ... `CreateSmartPlaylist` issued its `INSERT ... RETURNING` through `QueryContext`, which routes to the query-only read pool, and failed with "attempt to write a readonly database (8)". No smart playlist could be created at all, in any real build. It was invisible because `NewTestDB` shares one in-memory connection and leaves `readDB` nil, so `reader()` hands back the *writer* under test: every unit test of that path exercised a handle production does not have. `TestNoWritesOnTheReadPool` walks the tree for the whole class, in the same spirit as `TestNoDirectRuntimeEmits` and for the same reason — a lint pass only sees one build configuration.	2026-08-12 01:18:07 -04:00
logan	a37acfcf84	perf(explore): emit the index status on change, not every three seconds ... `IndexStatusChanged` was pushed on a 3 s ticker for the life of the process, byte-identical once the index was ready, and `config-page` assigns it to a @state field — so a user who had once opened Settings paid a full re-render of a 2 000-line template every 3 s, forever, for no news. Measured sitting on Settings: 5 events and 5 re-renders per 15 s, against 0 and 0. `emitStatus` drops a status equal to the last one it sent, which is the rule stated once instead of at twenty call sites. The corollary is load-bearing: every mutation of something the status derives must now call `emitStatus` itself. Two were relying on the ticker — `si.ready` when an existing index is adopted, and `si.cancel` when a build ends — and without them the header badge said "Building search index" over an index the settings page called ready. A polling loop is a hidden dependency for every state transition that forgot to announce itself.	2026-08-12 01:18:07 -04:00
logan	952c25c3d3	feat(jobs): register the autotag apply, and ask before quitting ... The apply was a bare goroutine whose progress lived in a component field discarded on navigation, with no cancel and no record of where it stopped if the app quit while it was rewriting tags — beside a registry that gives every other long-running operation exactly those things. `jobs.KindAutotagApply` now carries progress, a cancel wired to the apply's context, and a terminal state that tells cancelled from failed. `OnBeforeClose` returns false unconditionally today; it now asks while a file-writing job is in flight. Still not durable: quitting cancels cleanly but nothing records where it stopped for the next launch. That belongs with the deferred download/jobs work.	2026-08-12 01:18:07 -04:00
logan	1d335c5180	perf(queue): stop a finished track refetching the whole library ... `recordPlay` emitted `TrackMetadataChanged`, which the frontend correctly reads as "tags were rewritten" and answers by discarding every cached collection: measured at 8 binding calls, 71.18 MB across the IPC and a 765 ms longest task per two track changes at 50 000 tracks — once per song, while clearing the user's selection. It now emits `TrackPlayCountChanged` with everything needed to patch the one track in place, read back with `UPDATE ... RETURNING` so the count cannot drift from the stored one. Measured after: 0 calls, 0 MB, 0 ms.	2026-08-12 01:17:54 -04:00
logan	df11ef23f4	feat(player): report the real position, and skip an unplayable track ... The seek bar was a setInterval counter reconciled only on track change: measured 3 s behind during steady playback and 30 s behind after four keyboard seeks, because the seek shortcut never told it. And `loadCurrentTrack`/`playCurrentTrack` logged, returned false and emitted nothing, so double-clicking a moved file did nothing, twice, forever — while auto-advance onto a bad file stopped playback dead. - A 1 Hz position ticker while playing, plus an immediate report on load, play, pause, seek and natural finish. The payload carries a `trackChangeId` (the store is a singleton, so a bar mounting later must not adopt a report about the previous track) and a `seq` (the same second reported twice still has to reset interpolation). - `PlaybackFailed` from both failure paths, and `playCurrentOrSkip` steps over tracks that will not load — bounded by the queue length, so a disconnected drive stops after one pass instead of spinning through a RepeatAll wrap. `PlayIndex` still reverts: the user picked that track. - `SeekFailed` is emitted when the seek itself fails, not only when nothing is loaded, and is followed by a position report so the optimistic move is taken back by the mechanism that fixed the drift. - A queue that simply ran out no longer unloads the player, so the finished track stays on the bar at 0:00.	2026-08-12 01:17:54 -04:00
logan	55aa3ea5b0	feat(events): add the position, playback-failure and play-count events ... Three events the frontend had no way to learn about: - `PlaybackPositionChanged` carries `player.PositionInfo`, so the seek bar can render what the player is doing instead of counting seconds itself. - `PlaybackFailed` carries the file and the reason, from both the load and the play path, so a track that will not play stops being a silent no-op. - `TrackPlayCountChanged` carries everything needed to patch one track in place. `TrackMetadataChanged` means "the tags on disk were rewritten" and costs the frontend its entire library cache; finishing a track used to emit it. An event's cost is part of its meaning, and the expensive one must not be reused for something cheap.	2026-08-12 01:17:41 -04:00
logan	fcf2fe509e	fix(events): keep every line of a doc comment inside a comment ... genevents prefixed only the *first* line of a const block's doc comment with `//`, so a comment that ran to a second paragraph emitted bare prose into the TypeScript object literal — a generated file that does not parse. Nothing had noticed because nobody had run the generator since the comments were written, and `make generate` is a pre-commit hook: the failure was waiting for whoever next touched a .sql, a .templ or an event constant. A generator is only verified by running it.	2026-08-12 01:17:41 -04:00
logan	da564f9659	build(dev): generate a 50k-track library and measure a running app ... Plan 007 phase 4 is verified by measurement, not by assertion, and there was no way to produce a number: the fixture library is a few dozen tracks and cannot show any of the findings. - `cmd/gentestdata -bulk N` (`make bulkdata`) writes a ~50 000-track library in 11 s / 466 MB by encoding six clips once and copying them, while still tagging every file through `backend/tagwriter` — a library the app cannot read back measures nothing. - `make sandbox-seed-bulk` seeds from it through the same script and the same discipline as any other seed: by running the app and waiting for the real scan. - `e2e/perf/measure.mjs` (`make perf LABEL=x`, `make perf-compare`) takes fourteen measurements against a running app and writes them to a gitignored `.dev/perf/<label>.json`. It wraps every bound Go method, so "did that refetch the library" is a fact rather than an inference, and records `longtask` entries, which is where a 25 MB JSON parse on the main thread shows up and nowhere else. It is not a spec and does not run in CI.	2026-08-12 01:17:33 -04:00
logan	7de1b4edc1	docs: record the orientation fixes and the two new frontend fixtures ... CLAUDE.md gains backend/home and the two cross-cutting frontend pieces a list or detail view now has to know about: explore-link's always-navigate rule with its double-click grace, and <catalog-scope-notice> with the catalogPending/catalogLoaded distinction behind it.	2026-08-11 01:15:39 -04:00
logan	ff687f0bd9	feat(home): populate the home page with start-listening shelves ... The sidebar had a Home item that fell through to "Coming soon". What was missing was not another view of the library — four of those exist, sorted and complete — but the opposite: a complete, sorted library is exactly what gives you nothing to play, because every entry point into it is alphabetical and identical every time you open the app. So a shelf is a *reason*, not a filter. Each one answers a different question you might be asking when you do not know what you want (what was I listening to, what is new, what do I keep coming back to, what have I forgotten, what fits, what would I never pick myself) and each says which question it answered — a row of covers with no explanation is just another grid. Two consequences run through it. Shelves are built from what the user actually did — play counts, last played, import order — with random sampling only where there is no signal to use, so randomness is the fallback rather than the design. And a shelf with nothing behind it is omitted instead of rendered empty: a fresh library legitimately gets three, and an empty row labelled "on repeat" would be a lie. The queries return album ids and nothing else, joined back to GetAllAlbumsWithDetails in Go, so the album projection keeps having one definition rather than one per shelf.	2026-08-11 01:15:34 -04:00
logan	62bb40fc4d	fix(download): make "check now" actually check now, and say what it did ... The button ran a normal reconcile pass, which honours each request's retry backoff — so a request searched an hour ago was not due, nothing was searched, and the button looked broken. The backoff is a promise to the providers, not to the user: a person pressing "check now" *is* the schedule, so a user-initiated pass ignores it and the loop still does not. "Nothing happened" also needed a reason. Summary now carries how many requests are still being looked for and whether any download client is enabled at all, which is the one cause of silence the user can fix — and the requests tab says so above the list rather than leaving an inert list to be interpreted. The rest is the retry schedule finally being admitted to: rows show when the next check falls due, "Looking for" explains that a request sitting there is waiting rather than failing, and the page header says how often the list is worked.	2026-08-11 01:15:23 -04:00