Detect new a-Shell downloads automatically instead of manual per-file imports

[EnesYilmazcode]

Problem

Every track downloaded by the a-Shell pipeline has to be manually imported through the file picker (src/components/ImportButton.jsx). The app can't watch the a-Shell library folder because iOS Safari has no File System Access API — a PWA cannot save a folder path and re-read it later. The sandbox constraint is real, but the experience of "I downloaded 3 songs, why aren't they in the app?" is fixable.

Constraint (so nobody fights it)

• No persistent folder handles on iOS Safari. Zero-setup true folder-watching is impossible from the PWA alone.
• What we do control: the picker allows multi-select, dedup already exists (addLocalTrack() in src/lib/db.js skips existing tracks by YouTube id or title+artist+duration), and the a-Shell engine writes index.json (context.md §2).

Phased plan

Phase 1 — "Sync" flow (MVP, no new infra)

Turn the existing dedup into a one-gesture sync:

• Rename/augment Import → Sync: instruct "Select All in your library folder"; the picker returns everything, dedup skips known tracks, only new ones are stored
• After the pick, report a diff summary: "3 new tracks added · 41 already in library" (counts already computed in ImportButton.onPick; today skipped is only shown when nonzero — invert the emphasis)
• If the pick includes index.json, parse it and list catalog entries that were not among the picked/imported audio files ("2 tracks in your download folder weren't selected") so missed files are visible

Phase 2 — localhost bridge (auto-detect for real, one Shortcut tap)

a-Shell can run Python: serve the library folder on http://127.0.0.1:<port> (e.g. via a small script wrapping http.server). The PWA polls http://127.0.0.1:<port>/index.json; when reachable, it diffs against the local catalog and offers "3 new downloads found — add all?" (or auto-adds behind a setting), fetching the .m4a bytes straight into audioBlobs.

• Validate on-device that fetch from an HTTPS PWA to http://127.0.0.1 is permitted by current iOS/WebKit (localhost is spec'd as potentially trustworthy; must be confirmed in Safari standalone mode — this is the go/no-go)
• Add http://127.0.0.1:* to connect-src in the CSP (vite.config.js)
• a-Shell script + "Open Melody sync server" Shortcut; PWA detects the server with a short-timeout probe on foreground, stays silent when absent
• Setting: "ask before adding" vs "add automatically"

Phase 3 (fallback if Phase 2 is blocked) — Shortcut hand-off

iOS Shortcut base64-encodes a downloaded file + metadata to the clipboard; a "Paste import" affordance in the PWA reads it via navigator.clipboard.readText() and stores the track. Clunkier, but zero picker interaction.

Acceptance criteria

After downloading N tracks in a-Shell, getting them into Melody takes at most one gesture, never per-file selection, and duplicates are never created.

[EnesYilmazcode]

Research findings — revising the plan

Researched what others have done for exactly this constraint (PWA + on-device downloads folder). The library folder is On My iPhone → a-Shell (a-Shell's ~/Documents, which the Files app and Shortcuts can both read directly). Results:

Confirmed dead ends (stop considering these)

1. Remembering the folder path is impossible, permanently. showDirectoryPicker() / File System Access API local pickers are unsupported on iOS Safari and Apple has a formal oppose position on the spec — this is not "waiting for a future iOS version" (caniuse, web-platform-dx). Only OPFS (the app's own private storage) exists.
2. Phase 2 (localhost bridge) is blocked as designed. Safari is the only major browser that still treats http://127.0.0.1 from an HTTPS page as blocked mixed content — WebKit bug 171934, open since 2017, still unresolved (Apple dev forums). So the deployed HTTPS PWA cannot fetch from an a-Shell http.server. The self-signed-cert workaround requires installing a trust profile — too much setup to be worth it.
3. Web Share Target (share a file from Files → straight into Melody) — not supported on iOS Safari, no timeline (status overview). Sharing out works; receiving doesn't.
4. Shortcuts has no "file added to folder" automation trigger on iOS (Apple Support trigger list) — no passive folder watching from Shortcuts either.

What prior art actually does

• minht11/local-music-pwa — same architecture as Melody: no FS Access API → copy picked files into IndexedDB. Our design is the established pattern, not a workaround.
• tucomel/yt-dlp-ios, SW-DLT — the a-Shell/Shortcuts download side; both end at "file lands in Files", none bridge into a web app automatically. Nobody has beaten the sandbox; the winning moves are about reducing gestures, not eliminating them.

Revised plan

Phase 1 (unchanged, now clearly the backbone): "Sync" = Select All + dedup + diff summary. With the folder being flat (On My iPhone → a-Shell), Select All is one gesture. This is the reliable batch path.

Phase 2 (replaced): piggyback on the download Shortcut — clipboard hand-off. The event we want to detect ("new song downloaded") always originates from a Shortcut run. So the Shortcut itself becomes the notifier:

• After yt-dlp finishes, the Shortcut reads the new .m4a from On My iPhone → a-Shell (Files actions can access it directly — no picker), base64-encodes it with a small JSON header ({melody: 1, title, youtubeId, ...}), and puts it on the clipboard, then opens Melody.
• On foreground, Melody shows a discreet "Import from download?" affordance; tapping it reads the clipboard (navigator.clipboard.readText() — requires a tap, which the affordance provides), decodes, and stores via the existing addLocalTrack() dedup path.
• Zero new infrastructure, no server, no cert, works offline. Cost: one tap per download, and clipboard payloads of ~1.3× file size (a 4 MB m4a ≈ 5.5 MB text — fine for Shortcuts/clipboard).

Phase 3 (unchanged): Select-All fallback covers anything the Shortcut path missed.

• Phase 1 as originally specced
• Define the clipboard payload format (magic key + metadata + base64 audio) and the foreground "Import from download?" affordance
• Extend the Phase-6 download Shortcut with the encode-to-clipboard + open-Melody steps
• Spike (30 min, low priority): whether a-Shell's own WKWebView can run the app from local files with direct folder reads — would trade home-screen/MediaSession polish for real file access; likely not worth it, but cheap to rule out

---

Generated by Claude Code