How quoid/userscripts works
Project type and purpose
• This is a hybrid native/web application:
– A Safari WebExtension (popup, settings page, background, content scripts) built with Svelte/Vite.
– A native iOS & macOS host app (Swift/Xcode) to manage file-system access, directory selection, and extension configuration.
• Its purpose is to let users install, edit, and inject custom userscripts (.user.js/.css) into Safari.
File structure
• src/app & src/dev
– The Svelte “browser page” webview (the extension’s “full-page” UI).
– Entry point: entry-app-webview.html → App.svelte → main.js.
• src/ext
– Action popup (src/ext/action-popup), background script (src/ext/background), extension page (src/ext/extension-page), and content-scripts (src/ext/content-scripts).
– Entry points: entry-ext-action-popup.html, entry-ext-background.html, entry-ext-extension-page.html.
• src/shared
– Reusable Svelte components, CSS resets, variables, utilities.
• public/ext
– Prebuilt manifest.json files & assets for Safari 15/16 and dev channels.
• xcode
– Native hosts: App-Mac, App-iOS, Ext-Safari, shared Swift modules (Logger, Preferences, UrlPolyfill, Utilities), plus Xcode project/workspace, tests, and xcconfig files.
• scripts & fastlane
– Build scripts for Safari bundles (build-safari-15.js, build-safari-16.4.js), preview helpers, and Fastlane config for iOS/macOS app packaging.
• Configuration files
– vite.config.js, jsconfig.json, eslint.config.js, .prettierrc.json, .stylelintrc.json, etc.
Read README for usage flows
• UI overview: Browser page, settings modal, popup sections (install prompt, matched scripts, toggles).
• Metadata & API: content-script injection, file I/O via GM.* methods, update/download flows.
Main components
A. Native Host Applications
1. iOS App (Swift)
2. macOS App (Swift)
3. Shareable code modules (xcode/Shared/*.swift)
B. WebExtension
1. background script (persistent service worker)
2. action popup UI (Svelte)
3. extension page (“browser page”) UI (Svelte)
4. content scripts (injected into web pages)
C. Frontend UI Modules
– Svelte components (src/app, src/ext/*, src/shared)
– CSS assets & static HTML entry points
D. Persistence & Storage
– Local file system (user-selected “scripts directory”)
– iCloud sync (optional, via host app)
– Extension storage (chrome.storage or file‐read APIs via host bridge)
E. External Services
– Remote .user.js fetch for @require, @updateURL, @downloadURL
– Apple App Store (installation, updates)
Relationships & interactions
1. Native host ⇄ WebExtension
– The Swift host app wraps and installs the Safari WebExtension bundle.
– Exposes directory‐picker UI; stores path in UserDefaults/Shared Container.
2. WebExtension background ⇄ content scripts
– background injects content scripts on matched URLs, listens for messages, reads from “scripts directory” via native messaging or file API.
3. UI (popup & extension page) ⇄ background
– Popup and full-page UI communicate with background on script list, toggles, updates, settings changes via message passing.
4. Extension ⇄ File system
– On save/remove: UI triggers background to write/delete .js/.css files in the selected directory.
– On load: background reads directory contents, parses metadata blocks, populates UI.
5. Extension ⇄ Remote servers
– For scripts with @updateURL or @require: background fetches remote meta.js or resources, writes to disk.
Architectural patterns & principles
• MV* style:
– Model = metadata + filesystem scripts
– View = Svelte UI components (popup, page, settings)
– Controller = background script message handlers
• Shared modules
– src/shared for cross‐UI components
– xcode/Shared for cross‐host logic
• Build pipeline
– Vite compiles Svelte to extension assets
– Fastlane packages native apps and embeds built extension