# quoid/userscripts architecture

> Architecture diagram of the GitHub repository quoid/userscripts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quoid/userscripts
- Repository: https://github.com/quoid/userscripts

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Native Hosts"
        iOS["iOS App\n(xcode/App-iOS)"]:::native
        Mac["macOS App\n(xcode/App-Mac)"]:::native
        SwiftShared["Shared Swift Modules\n(xcode/Shared)"]:::shared
        Bridge["Safari WebExtension Handler\n(xcode/Ext-Safari/SafariWebExtensionHandler.swift)"]:::native
    end

    subgraph "Safari WebExtension"
        Background["Background Script\n(entry-ext-background.html + src/ext/background/main.js)"]:::ext
        Popup["Action Popup UI\n(entry-ext-action-popup.html + src/ext/action-popup/main.js & App.svelte)"]:::ext
        PageUI["Extension Page UI\n(entry-ext-extension-page.html + src/ext/extension-page/main.js & App.svelte)"]:::ext
        Contents["Content Scripts\n(src/ext/content-scripts/*.js)"]:::ext
        ExtShared["Extension Shared Utilities\n(src/ext/shared)"]:::shared
        Manifests["Manifests & Assets\n(public/ext)"]:::storage
    end

    subgraph "Browser Page Webview UI"
        AppUI["Webview UI\n(entry-app-webview.html + src/app/main.js & App.svelte)"]:::webview
        DevUI["Dev Webview UI\n(src/dev/main.js & src/dev/App.svelte)"]:::webview
        SharedUI["Shared Svelte Components\n(src/shared/Components/*.svelte & CSS)"]:::shared
    end

    subgraph "Storage & Remote"
        FS["File System\n(User Scripts Dir)"]:::storage
        Remote["Remote Servers\n(.user.js fetch)"]:::storage
    end

    subgraph "Build & Deploy"
        BuildScripts["Build Scripts\n(scripts/build-safari-15.js & build-safari-16.4.js)"]:::pipeline
        Vite["Vite Build\n(vite.config.js)"]:::pipeline
        Fastlane["Fastlane\n(Fastfile, Appfile, Matchfile)"]:::pipeline
    end

    %% Relationships
    SwiftShared --> iOS
    SwiftShared --> Mac
    Bridge --> Background
    iOS -->|hosts/installs| Background
    Mac -->|hosts/installs| Background

    BuildScripts -->|compile assets| Vite
    Vite -->|extension bundle| Background
    Fastlane -->|package| iOS
    Fastlane -->|package| Mac
    Background -->|embedded in| iOS
    Background -->|embedded in| Mac

    Popup <-->|"message passing"| Background
    PageUI <-->|"message passing"| Background
    AppUI <-->|"message passing"| Background
    DevUI <-->|"message passing"| Background

    Background -->|injects| Contents

    Background -->|read/write| FS
    FS -->|provides scripts| Background

    Background -->|fetch updates| Remote

    ExtShared --> Background
    ExtShared --> Popup
    ExtShared --> PageUI
    SharedUI --> Popup
    SharedUI --> PageUI
    SharedUI --> AppUI
    SharedUI --> DevUI

    Manifests --> Background

    %% Click Events
    click iOS "https://github.com/quoid/userscripts/tree/main/xcode/App-iOS"
    click Mac "https://github.com/quoid/userscripts/tree/main/xcode/App-Mac"
    click SwiftShared "https://github.com/quoid/userscripts/tree/main/xcode/Shared"
    click Bridge "https://github.com/quoid/userscripts/blob/main/xcode/Ext-Safari/SafariWebExtensionHandler.swift"
    click Background "https://github.com/quoid/userscripts/blob/main/src/ext/background/main.js"
    click Popup "https://github.com/quoid/userscripts/blob/main/src/ext/action-popup/main.js"
    click PageUI "https://github.com/quoid/userscripts/blob/main/src/ext/extension-page/main.js"
    click Contents "https://github.com/quoid/userscripts/tree/main/src/ext/content-scripts"
    click ExtShared "https://github.com/quoid/userscripts/tree/main/src/ext/shared"
    click Manifests "https://github.com/quoid/userscripts/tree/main/public/ext"
    click AppUI "https://github.com/quoid/userscripts/blob/main/src/app/main.js"
    click DevUI "https://github.com/quoid/userscripts/blob/main/src/dev/main.js"
    click SharedUI "https://github.com/quoid/userscripts/tree/main/src/shared/Components"
    click BuildScripts "https://github.com/quoid/userscripts/blob/main/scripts/build-safari-15.js"
    click Vite "https://github.com/quoid/userscripts/blob/main/vite.config.js"
    click Fastlane "https://github.com/quoid/userscripts/tree/main/fastlane/Fastfile"

    %% Styles
    classDef native fill:#add8e6,stroke:#333,stroke-width:1px
    classDef ext fill:#90ee90,stroke:#333,stroke-width:1px
    classDef shared fill:#fdfd96,stroke:#333,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef pipeline fill:#ffcccb,stroke:#333,stroke-width:1px
    classDef webview fill:#90ee90,stroke:#333,stroke-width:1px
```
