diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index 56a0522..7121f13 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1,4 +1,7 @@ -# These are supported funding model platforms - +# Hellion NewTab — Support & Funding +# All tools are free and open-source. Donations are voluntary and go toward server costs. ko_fi: hellionmedia + +custom: + - "https://hellion-media.de" \ No newline at end of file diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6821da5..246eb29 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,4 +1,4 @@ -# Release — erstellt ZIP-Pakete für Chrome, Firefox und Opera bei neuem Tag +# Release — creates ZIP packages for Chrome, Firefox and Opera on new tag name: Release on: @@ -17,18 +17,18 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Version aus Tag extrahieren + - name: Extract version from tag id: version run: echo "tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT" - - name: Chrome/Edge ZIP erstellen (Manifest V3) + - name: Create Chrome/Edge ZIP (Manifest V3) run: | mkdir -p dist zip -r "dist/hellion-newtab-${{ steps.version.outputs.tag }}-chrome.zip" \ manifest.json newtab.html src/js/*.js src/css/ assets/ \ -x "*.git*" "dist/*" ".github/*" "src/js/opera/*" - - name: Firefox ZIP erstellen (Manifest V3) + - name: Create Firefox ZIP (Manifest V3) run: | cp manifest.json manifest.chrome-backup.json cp manifest.firefox.json manifest.json @@ -37,7 +37,7 @@ jobs: -x "*.git*" "dist/*" ".github/*" "manifest.chrome-backup.json" "manifest.firefox.json" "src/js/opera/*" mv manifest.chrome-backup.json manifest.json - - name: Opera/Opera GX ZIP erstellen (Manifest V3 + Workaround) + - name: Create Opera/Opera GX ZIP (Manifest V3 + workaround) run: | cp manifest.json manifest.chrome-backup.json cp manifest.opera.json manifest.json @@ -46,13 +46,13 @@ jobs: -x "*.git*" "dist/*" ".github/*" "manifest.chrome-backup.json" "manifest.opera.json" mv manifest.chrome-backup.json manifest.json - - name: SHA256 Checksummen erstellen + - name: Generate SHA256 checksums run: | cd dist sha256sum *.zip > checksums-sha256.txt cat checksums-sha256.txt - - name: GitHub Release erstellen + - name: Create GitHub Release uses: softprops/action-gh-release@v2 with: name: "Hellion NewTab ${{ steps.version.outputs.tag }}" @@ -64,13 +64,13 @@ jobs: - **Firefox:** `hellion-newtab-${{ steps.version.outputs.tag }}-firefox.zip` - **Opera / Opera GX:** `hellion-newtab-${{ steps.version.outputs.tag }}-opera.zip` - Siehe [README](README.md) für die vollständige Installationsanleitung. + See [README](README.md) for the full installation instructions. - ### Checksummen - Siehe `checksums-sha256.txt` zur Integritätsprüfung. + ### Checksums + See `checksums-sha256.txt` to verify file integrity. files: | dist/hellion-newtab-${{ steps.version.outputs.tag }}-chrome.zip dist/hellion-newtab-${{ steps.version.outputs.tag }}-firefox.zip dist/hellion-newtab-${{ steps.version.outputs.tag }}-opera.zip dist/checksums-sha256.txt - generate_release_notes: true + generate_release_notes: true \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 2936dda..0354173 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,92 +1,173 @@ # ⬡ Hellion Dashboard — Changelog -Alle relevanten Änderungen pro Version. Format basiert auf [Keep a Changelog](https://keepachangelog.com/de/1.0.0/). +All notable changes per version. Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +> Changelog entries can be written in English or German. English preferred for consistency. + +--- + +### v1.10.0 — 22.03.2026 + +#### Themes + +- **3 new themes** — Satisfactory (Industrial Desert), Avorion (Deep Void) and Hellion Stealth (Tactical Recon) +- Now **11 themes** total, each with its own accent colors, overlays and font styles +- Satisfactory has increased board alpha (0.65) and stronger blur (12px), a deliberate choice for better readability on a visually busy background +- Avorion uses a radial gradient overlay so the ship in the center of the image stays visible +- Hellion Stealth is the only theme with a `border-left` hover effect in tactical scanner style + +--- + +### v1.9.0 — 22.03.2026 + +#### New Features + +- **Onboarding reworked** — 7 slides instead of 6, new slide explains the widget toolbar with all widgets +- **Gaming Starter Board** — Opt-in during onboarding: pre-filled board with links to Satisfactory, Factorio, Avorion, Minecraft and Star Citizen +- **Settings redesign** — Settings panel slimmed down to 3 sections (Widgets, Data & Help, Danger Zone) +- **Appearance modal** — Theme picker and all display settings combined in one modal instead of spread across the panel +- **Fixed about footer** — Developer info, license and links are now permanently visible at the bottom of the settings panel +- **Project documentation** — `docs/architecture.md`, `docs/widget-schema.md` and `docs/patterns.md` for anyone who wants to fork or contribute + +#### Improvements + +- All labels and descriptions unified in German, no more language mix +- Dropdown options use theme colors instead of white browser default +- Firefox update URL for store publishing added to `manifest.firefox.json` + +--- + +### v1.8.0 — 21.03.2026 + +#### New Features + +- **Image Reference Widget** — Drop images as floating reference widgets (max. 3 at once) +- Canvas API WebP conversion for smaller file sizes, all local in the browser +- Two-layer storage: metadata persistent, image data session-only (sessionStorage) +- Load images via drag & drop or file dialog +- Labels editable with debounced save +- Feature is off by default, enable via Settings → Widgets + +--- + +### v1.7.1 — 21.03.2026 + +#### Improvements + +- **Timer mute toggle** — Alarm can be muted via icon button without restarting the timer +- Alarm volume reduced to 7%, 30% was a bit much +- Mute state is saved and persists on next open + +--- + +### v1.7.0 — 21.03.2026 + +#### New Features + +- **Calculator widget** — Shunting-yard parser (no `eval()`), history of last calculations, keyboard input +- **Timer/countdown widget** — Saveable presets, Web Audio API alarm, tab title blinks when timer completes +- **Widget z-index fix** — Widgets now correctly render above the search bar (z-index 100+) + +--- + +### v1.6.0 — 21.03.2026 + +#### New Features + +- **Widget system** — Draggable, resizable floating panels managed by WidgetManager +- **Notes & checklists** — Multi-instance widgets (max. 5) with text and checklist template, Markdown support, export as `.md` +- **Notebook sidebar** — All notes at a glance, quick access via toolbar +- **Widget toolbar** — Floating buttons on the side for quick access to all widgets, position (left/right) configurable in Settings +- **Sticky note migration** — Old sticky notes are automatically migrated to the new widget system on first launch + +#### Improvements + +- Ko-fi support link added to the about section and `FUNDING.yml` --- ### v1.5.2 — 21.03.2026 -#### Neue Features +#### New Features -- **Custom Dialog-System** — Native `confirm()` und `alert()` durch Frosted-Glass-Dialoge ersetzt (`dialog.js`) -- **Onboarding** — 6-stufiger Willkommens-Flow beim ersten Start mit Boards, Themes, Features und Backup-Hinweis -- **Backup-Reminder** — Erinnert alle 7 Tage an JSON-Export, warnt vor Datenverlust bei Browser-Reset -- **Theme-Modal** — Theme-Picker als eigenes Modal aus Settings ausgelagert, eigener Header-Button -- **Accordion-Settings** — Alle Settings-Sektionen einklappbar mit Chevron (About/Danger Zone standardmäßig zu) +- **Custom dialog system** — Native `confirm()` and `alert()` replaced with frosted glass dialogs (`dialog.js`) +- **Onboarding** — 6-step welcome flow on first launch with explanations for boards, themes, features and a backup reminder +- **Backup reminder** — Reminds every 7 days to run a JSON export and warns about data loss on browser reset +- **Theme modal** — Theme picker moved to its own modal with its own header button +- **Accordion settings** — All settings sections collapsible (About and Danger Zone closed by default) -#### Verbesserungen +#### Improvements -- Fonts von Google Fonts API auf lokale WOFF2-Dateien umgestellt (DSGVO) -- Ungenutzte Font-Dateien entfernt (~388 KB gespart) -- `innerHTML` komplett durch `createElement`/`createElementNS` ersetzt (XSS-Schutz) -- SVG-Icons via `createElementNS` statt Inline-HTML -- Drag & Drop: Inline-Styles durch CSS-Klassen ersetzt (`.drag-ghost`, `.drag-over`, `.dragging-source`) -- Suchleisten-Toggle von DATA nach BEHAVIOR verschoben -- Nicht implementiertes "Quick Save" UI-Element entfernt -- Onboarding wiederholbar über Settings → Help +- Fonts migrated from Google Fonts API to local WOFF2 files (GDPR, ~388 KB saved) +- `innerHTML` fully replaced with `createElement` and `createElementNS` (XSS protection) +- SVG icons now via `createElementNS` instead of inline HTML +- Drag & drop uses CSS classes instead of inline styles (`.drag-ghost`, `.drag-over`, `.dragging-source`) +- Search bar toggle moved from DATA to BEHAVIOR section +- Unimplemented "Quick Save" UI element removed +- Onboarding repeatable via Settings → Help #### Opera / Opera GX -- `manifest.opera.json` hinzugefügt (MV3 mit Workaround-Skripten) -- `src/js/opera/background.js` — Tab-Management gegen Opera Speed Dial -- `src/js/opera/redirect.js` — Content Script Redirect bei `document_start` +- `manifest.opera.json` added (MV3 with workaround scripts) +- `src/js/opera/background.js` monitors tabs and redirects away from Opera Speed Dial +- `src/js/opera/redirect.js` fires as content script at `document_start` #### Firefox -- `manifest.firefox.json` auf Manifest V3 migriert -- `browser_specific_settings` mit Gecko-ID und `data_collection_permissions` +- `manifest.firefox.json` migrated to Manifest V3 +- `browser_specific_settings` with Gecko ID and `data_collection_permissions` added #### Build & CI -- GitHub Actions: Release erstellt jetzt 3 ZIP-Pakete (Chrome, Firefox, Opera) -- Quality-Check prüft alle 3 Manifests und Opera-Ordner +- GitHub Actions release now builds 3 ZIP packages (Chrome, Firefox, Opera) +- Quality check validates all 3 manifests and the Opera folder --- ### v1.2.0 — 20.03.2026 -- Projektstruktur in `src/js/`, `src/css/`, `assets/` aufgeteilt -- JS in 10 Module aufgeteilt (storage, state, themes, boards, drag, settings, search, sticky, data, app) -- Firefox-Kompatibilität (`manifest.firefox.json`, Manifest V3) -- Vivaldi bestätigt kompatibel -- Theme-Bildpfade korrigiert (Settings Preview) -- URL-Validierung bei Bookmark-Erstellung -- JSON-Import mit Board- und Bookmark-Struktur-Validierung -- XSS-Schutz: `createElement` statt `innerHTML` für Bookmarks -- Storage-Quota-Prüfung mit Warnung bei 8 MB+ -- Event Delegation für Bookmark-Klicks (Performance) -- Responsive Design (Tablet 768px, Smartphone 480px) -- Sticky Note Header-Kollision behoben -- FileReader-Fehlerbehandlung für Hintergrundbild-Upload -- GitHub Actions: Security Scan, Code Quality, Release Automation -- 3 Themes ersetzt: Astronaut → Nebula, Cosmic Clock → Crescent, Void Mage → Event Horizon -- Alle Theme-Bilder lizenzrechtlich geprüft und dokumentiert -- LICENSE (CC BY-NC-SA 4.0), SECURITY.md und DISCLAIMER.md hinzugefügt +- Project structure split into `src/js/`, `src/css/` and `assets/` +- JS split into 10 modules (storage, state, themes, boards, drag, settings, search, sticky, data, app) +- Firefox compatibility (`manifest.firefox.json`, Manifest V3) +- Vivaldi confirmed compatible +- Theme image paths fixed (settings preview) +- URL validation on bookmark creation +- JSON import validates board and bookmark structure +- XSS protection: `createElement` instead of `innerHTML` for bookmarks +- Storage quota check with warning at 8 MB+ +- Event delegation for bookmark clicks (performance) +- Responsive design (tablet 768px, smartphone 480px) +- Sticky note header collision fixed +- FileReader error handling for background image upload +- GitHub Actions: security scan, code quality, release automation +- 3 themes replaced: Astronaut → Nebula, Cosmic Clock → Crescent, Void Mage → Event Horizon +- All theme images checked and documented for license compliance +- LICENSE (CC BY-NC-SA 4.0), SECURITY.md and DISCLAIMER.md added --- ### v1.1.0 — 20.03.2026 -- 5 neue Themes (Merchantman, Julia & Jin, SC Sunset, Hellion HUD, Hellion Energy) -- Suchleiste (Google / DuckDuckGo / Bing) -- Sticky Note Widget -- JSON Export & Import -- Datum neben der Uhr -- About / Impressum in Settings -- Board Blur-Funktion (Privat-Modus) -- Drag & Drop auf Pointer Events umgestellt -- Opera / Opera GX Kompatibilität +- 5 new themes (Merchantman, Julia & Jin, SC Sunset, Hellion HUD, Hellion Energy) +- Search bar (Google, DuckDuckGo, Bing) +- Sticky note widget +- JSON export & import +- Date next to the clock +- About / imprint in settings +- Board blur function (privacy mode) +- Drag & drop migrated to Pointer Events API +- Opera / Opera GX compatibility --- ### v1.0.0 — 20.03.2026 -- Initiales Release -- Boards & Bookmarks mit Drag & Drop -- 3 Themes (Nebula, Crescent, Event Horizon) -- HTML-Import (Browser-Lesezeichen) -- Settings Panel +- Initial release +- Boards & bookmarks with drag & drop +- 3 themes (Nebula, Crescent, Event Horizon) +- HTML import (browser bookmarks) +- Settings panel --- -**Hellion NewTab** — [Hellion Online Media](https://hellion-media.de) — JonKazama-Hellion \ No newline at end of file +**Hellion NewTab** — [Hellion Online Media](https://hellion-media.de) — JonKazama-Hellion diff --git a/DISCLAIMER.md b/DISCLAIMER.md index 538035b..dc9681f 100644 --- a/DISCLAIMER.md +++ b/DISCLAIMER.md @@ -1,47 +1,81 @@ -# Haftungsausschluss — Hellion NewTab +# Disclaimer — Hellion NewTab -## Nutzung auf eigenes Risiko +## Use at Your Own Risk -Diese Browser-Extension wird "wie besehen" (as-is) zur Verfügung gestellt, ohne jegliche ausdrückliche oder stillschweigende Gewährleistung, einschließlich, aber nicht beschränkt auf die Gewährleistung der Marktgängigkeit, der Eignung für einen bestimmten Zweck und der Nichtverletzung von Rechten Dritter. +This browser extension is provided "as is", without warranty of any kind, express +or implied, including but not limited to the warranties of merchantability, fitness +for a particular purpose and non-infringement. -## Keine Garantie +## No Guarantee -Der Entwickler übernimmt keine Haftung für: +The developer assumes no liability for: -- Datenverlust durch fehlerhafte Speicherung, Browser-Updates oder Extension-Deinstallation -- Inkompatibilitäten mit bestimmten Browser-Versionen oder Betriebssystemen -- Schäden, die durch die Nutzung oder Nichtnutzung dieser Extension entstehen -- Verfügbarkeit oder Korrektheit von Drittanbieter-Diensten (Google Favicons API) +- Data loss caused by storage errors, browser updates or extension uninstallation +- Incompatibilities with specific browser versions or operating systems +- Damages arising from the use or inability to use this extension +- Availability or accuracy of third-party services (Google Favicons API) -## Datenspeicherung +## Data Storage -Alle Daten werden ausschließlich lokal im Browser gespeichert (`chrome.storage.local`). Es erfolgt keine Übertragung an externe Server. Der Entwickler hat keinen Zugriff auf gespeicherte Bookmarks, Einstellungen oder Notizen. +All data is stored exclusively in the local browser (`chrome.storage.local`). +No data is transmitted to external servers. The developer has no access to stored +bookmarks, settings, notes or any other user data. -**Empfehlung:** Regelmäßig JSON-Backups über die Export-Funktion erstellen. +**Recommendation:** Create regular JSON backups using the export function in Settings. -## Drittanbieter-Dienste +## No Guaranteed Updates -Diese Extension nutzt folgende externe Dienste: +This extension is maintained by a single developer in their spare time. +Continued development and updates are not guaranteed. Features may change, +projects may pause, and support is provided on a best-effort basis, not as an obligation. -| Dienst | Zweck | Datenschutz | -| --- | --- | --- | -| Google Favicons API | Bookmark-Icons laden | Es wird nur die Domain übermittelt, keine vollständige URL | -| Google Fonts | Schriftarten (Rajdhani, Inter, Cinzel) | Standardmäßige Google-Fonts-Nutzungsbedingungen | +## Third-Party Services -## Änderungen +| Service | Purpose | Privacy | +|---|---|---| +| Google Favicons API | Load bookmark icons | Only the domain is transmitted, not the full URL | -Der Entwickler behält sich das Recht vor, diese Extension jederzeit zu ändern, zu aktualisieren oder einzustellen, ohne vorherige Ankündigung. +## Trademark -## Kontakt +The name "Hellion Online Media", the associated logo and all related graphics are +the property of Florian Wathling / Hellion Online Media and may not be used without +explicit permission. The CC BY-NC-SA 4.0 license applies to the source code and +content of this project, not to trademarks or brand assets. -| | | -| --- | --- | -| **Entwickler** | Florian Wathling | -| **Unternehmen** | Hellion Online Media | -| **Web** | [hellion-media.de](https://hellion-media.de) | -| **E-Mail** | [kontakt@hellion-media.de](mailto:kontakt@hellion-media.de) | -| **Impressum** | [hellion-media.de/impressum](https://hellion-media.de/impressum) | +Forks and derivative works must remove or replace all Hellion Online Media branding. + +## Legal + +This extension is developed and maintained by Florian Wathling / Hellion Online Media, +based in Bad Harzburg, Germany. All matters are handled in accordance with German +and EU law, including the General Data Protection Regulation (GDPR / DSGVO). + +For legal inquiries: [hellion-media.de/impressum](https://hellion-media.de/impressum) + +## Use of AI + +**Claude:** Code analysis, bug fixing, documentation and proofreading. +**Me:** Architecture, features and logic are planned, thought through and written by me. + +Who looks for "AI patterns" in the code: clean indentation is the linter, +okayish variable names are the developer, and the semicolon hiding somewhere +is what Claude finds. That's how it works. + +I have ADHD and mild dyslexia. Claude helps me stay focused and makes sure +others can follow the code too. That's exactly what open source is for. + +Source code is open, every decision is traceable. --- -**Hellion NewTab** — [Hellion Online Media - Florian Wathing](https://hellion-media.de) — JonKazama-Hellion +| | | +|---|---| +| **Developer** | Florian Wathling | +| **Company** | Hellion Online Media | +| **Web** | [hellion-media.de](https://hellion-media.de) | +| **Imprint** | [hellion-media.de/impressum](https://hellion-media.de/impressum) | +| **Contact** | [kontakt@hellion-media.de](mailto:kontakt@hellion-media.de) | + +--- + +**Hellion NewTab** — [Hellion Online Media — Florian Wathling](https://hellion-media.de) — JonKazama-Hellion diff --git a/README.md b/README.md index 421839e..2c7e4a1 100644 --- a/README.md +++ b/README.md @@ -4,31 +4,31 @@ ![JavaScript](https://img.shields.io/badge/JavaScript-Vanilla%20ES2020-F7DF1E?logo=javascript&logoColor=black) ![Manifest](https://img.shields.io/badge/Manifest-V3-green) ![License](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-orange) -![Privacy](https://img.shields.io/badge/Privacy-100%25%20Lokal-448f45) +![Privacy](https://img.shields.io/badge/Privacy-100%25%20Local-448f45) [![Ko-fi](https://img.shields.io/badge/Support-Ko--fi-ff5e5b?logo=ko-fi)](https://ko-fi.com/hellionmedia) -**Kein Account. Kein Abo. Keine Cloud. Alle Daten bleiben 100% lokal.** +**No account. No subscription. No cloud. All data stays 100% local.** -Ein persönlicher Bookmark-Dashboard als Browser-Extension. -Boards, Drag & Drop, 8 Themes, Suchleiste, Sticky Notes — alles im Browser, alles offline. -Keine externe Datenübertragung, keine Tracker, keine Analytics, keine Werbung. +A personal bookmark dashboard as a browser extension. +Boards, drag & drop, 11 themes, search bar, widget system with notes, calculator, timer and more. All in the browser, all offline. +No external data transmission, no trackers, no analytics, no ads. -Entwickelt von **[Hellion Online Media — Florian Wathling](https://hellion-media.de)** — JonKazama-Hellion. +Developed by **[Hellion Online Media — Florian Wathling](https://hellion-media.de)** — JonKazama-Hellion. --- -## Was diese Extension NICHT ist +## What this extension is NOT -- Kein Cloud-Sync und kein Account-System -- Keine Datenerfassung oder Telemetrie -- Keine Drittanbieter-Abhängigkeiten oder Build-Tools -- Kein Netzwerkverkehr außer Favicon-Abruf (Google Favicons API) +- No cloud sync and no account system +- No data collection or telemetry +- No third-party dependencies or build tools +- No network traffic except favicon fetching (Google Favicons API) -## Was diese Extension IST +## What this extension IS -Ein lokaler, privater NewTab-Ersatz für alle gängigen Browser. -Bookmarks werden in `chrome.storage.local` gespeichert — nichts verlässt den Browser. -Was angezeigt wird, ist was gespeichert ist. Keine Magie. +A local, private NewTab replacement for all major browsers. +Bookmarks are stored in `chrome.storage.local`, nothing leaves the browser. +What you see is what's saved. No magic. --- @@ -36,25 +36,30 @@ Was angezeigt wird, ist was gespeichert ist. Keine Magie. ### Boards & Bookmarks -- Boards als Gruppen für Links — per Drag & Drop umsortierbar -- Bookmarks mit Favicon, Titel, optionaler Beschreibung -- Boards per Blur-Button verstecken (Privat-Modus) -- HTML-Import von Browser-Lesezeichen (Chrome, Edge, Firefox) -- JSON Export & Import (Backup & Restore) +- Boards as groups for links, sortable via drag & drop +- Bookmarks with favicon, title and optional description +- Hide boards with the blur button (privacy mode) +- HTML import from browser bookmarks (Chrome, Edge, Firefox) +- JSON export & import (backup & restore) -### Suchleiste +### Search Bar -- Google, DuckDuckGo oder Bing — per Klick wechselbar -- Ein/ausblendbar über Settings +- Google, DuckDuckGo or Bing, switchable with a click +- Toggleable via Settings -### Sticky Note +### Widget System -- Schwebendes Notiz-Widget, frei positionierbar -- Text und Position werden persistent gespeichert +- **Notes & Checklists** — Floating note widgets with text or checklist template (max. 5) +- **Calculator** — Shunting-yard parser (no `eval()`), history, keyboard input +- **Timer / Countdown** — Saveable presets, Web Audio API alarm, mute toggle, tab title blinks on completion +- **Image Reference** — Images as floating reference widgets, Canvas API WebP conversion (max. 3, enable in Settings) +- **Notebook Sidebar** — All notes at a glance +- **Widget Toolbar** — Floating buttons for quick access, position (left/right) configurable in Settings +- All widgets: draggable, resizable, z-index stacking on click -### 8 Themes +### 11 Themes -| Theme | Akzent | Stil | +| Theme | Accent | Style | |---|---|---| | Nebula | `#b359ff` Magenta | Cosmic Nebula | | Crescent | `#d4bd8a` Gold | Minimalist Night | @@ -64,60 +69,58 @@ Was angezeigt wird, ist was gespeichert ist. Keine Magie. | SC Sunset | `#ff8c3d` Amber | Planet-Side | | Hellion HUD | `#32ff6a` Neon Green | Circuit Board | | Hellion Energy | `#1eff8e` Acid Green | Tactical | +| Satisfactory | `#00b4d8` Cyan | Industrial Desert | +| Avorion | `#2ec4a0` Turquoise | Deep Void | +| Hellion Stealth | `#5ec2ff` Tech Blue | Tactical Recon | -### Bild-Credits +### Image Credits -| Theme | Quelle | Lizenz | +| Theme | Source | License | |---|---|---| -| Nebula | [Temel / mrwashingt0n](https://pixabay.com/de/users/mrwashingt0n-15745216/) auf Pixabay | Pixabay License (frei) | -| Crescent | [Daniil Silantev](https://unsplash.com) auf Unsplash | Unsplash License (frei) | -| Event Horizon | Eigenes Werk — Stillframe von [hellion-initiative.online](https://hellion-initiative.online) | Hellion Online Media | -| Merchantman | [Roberts Space Industries](https://robertsspaceindustries.com) — Made by the community | RSI Community Content | -| SC Sunset | Screenshot aus Star Citizen von Cloud Imperium Games | Fan Content | -| Julia & Jin | Eigenes Werk — Final Fantasy XIV Screenshot, bearbeitet in Photoshop | Hellion Online Media | -| Hellion HUD | Eigenes Werk — AI-generiert und nachbearbeitet für hellion-media.de | Hellion Online Media | -| Hellion Energy | Eigenes Werk — AI-generiert für hellion-media.de | Hellion Online Media | +| Nebula | [Temel / mrwashingt0n](https://pixabay.com/de/users/mrwashingt0n-15745216/) on Pixabay | Pixabay License (free) | +| Crescent | [Daniil Silantev](https://unsplash.com) on Unsplash | Unsplash License (free) | +| Event Horizon | Own work, still frame from [hellion-initiative.online](https://hellion-initiative.online) | Hellion Online Media | +| Merchantman | [Roberts Space Industries](https://robertsspaceindustries.com), made by the community | RSI Community Content | +| SC Sunset | Screenshot from Star Citizen by Cloud Imperium Games | Fan Content | +| Julia & Jin | Own work, Final Fantasy XIV screenshot, edited in Photoshop | Hellion Online Media | +| Hellion HUD | Own work, AI-generated and post-processed for hellion-media.de | Hellion Online Media | +| Hellion Energy | Own work, AI-generated for hellion-media.de | Hellion Online Media | +| Satisfactory | Screenshot from Satisfactory by Coffee Stain Studios | Fan Content | +| Avorion | Own work, screenshot from Avorion, Hellion Initiative ship | Hellion Online Media | +| Hellion Stealth | Screenshot from Star Citizen by Cloud Imperium Games | Fan Content | -### Onboarding & Dialoge +### Onboarding & Dialogs -- 6-stufiger Willkommens-Flow beim ersten Start -- Custom Frosted-Glass-Dialoge statt nativer Browser-Popups -- Backup-Reminder alle 7 Tage (warnt vor Datenverlust bei Browser-Reset) +- 7-step welcome flow on first launch with widget explanation and optional gaming starter board +- Custom frosted glass dialogs instead of native browser popups +- Backup reminder every 7 days (warns about data loss on browser reset) -### Settings (Accordion) +### Appearance & Settings -- Einklappbare Sektionen mit Chevron — About/Danger Zone standardmäßig geschlossen -- Compact Mode — reduziert Abstände für mehr Bookmarks -- Shorten Titles — kürzt lange Titel auf eine Zeile -- Open in New Tab — Bookmarks in neuem Tab öffnen -- Show Descriptions — Beschreibungen unter Bookmarks anzeigen -- Hide Extra Bookmarks — Boards ab 5/10/20 Bookmarks einklappen -- Suchleiste ein/ausblenden -- JSON Export / Import -- Onboarding wiederholbar -- Danger Zone — Reset aller Daten - -### Theme-Picker (eigener Header-Button) - -- 8 Themes als zentriertes Modal -- Hintergrundbild per URL oder lokaler Upload +- **Appearance modal** (header button), theme picker, background image and all display options in one modal +- **Settings panel** (header button), widgets, data & help, danger zone +- **About footer**, developer info, license and support links permanently visible +- Compact mode, shorten titles, search bar toggle, open links in new tab, descriptions, hide extra bookmarks +- JSON export & import (backup & restore) +- Onboarding repeatable +- All UI labels in German (English coming in v2.1) --- -## Browser-Kompatibilität +## Browser Compatibility | Browser | Status | Manifest | |---|---|---| -| Chrome | ✅ Kompatibel | V3 (`manifest.json`) | -| Edge | ✅ Kompatibel | V3 (`manifest.json`) | -| Brave | ✅ Kompatibel | V3 (`manifest.json`) | -| Opera | ✅ Kompatibel | V3 (`manifest.opera.json`) | -| Opera GX | ✅ Kompatibel | V3 (`manifest.opera.json`) | -| Vivaldi | ✅ Kompatibel | V3 (`manifest.json`) | -| Firefox | ✅ Kompatibel | V3 (`manifest.firefox.json`) | +| Chrome | ✅ Compatible | V3 (`manifest.json`) | +| Edge | ✅ Compatible | V3 (`manifest.json`) | +| Brave | ✅ Compatible | V3 (`manifest.json`) | +| Opera | ✅ Compatible | V3 (`manifest.opera.json`) | +| Opera GX | ✅ Compatible | V3 (`manifest.opera.json`) | +| Vivaldi | ✅ Compatible | V3 (`manifest.json`) | +| Firefox | ✅ Compatible | V3 (`manifest.firefox.json`) | -> **Firefox-Hinweis:** Ab v1.2.0 läuft die Extension auf Manifest V3 — identisch zu Chrome/Edge. -> `manifest.firefox.json` bleibt als separate Datei erhalten für Firefox-spezifische Anpassungen. +> **Firefox note:** From v1.2.0 onwards the extension runs on Manifest V3, identical to Chrome/Edge. +> `manifest.firefox.json` remains a separate file for Firefox-specific adjustments. --- @@ -126,144 +129,154 @@ Was angezeigt wird, ist was gespeichert ist. Keine Magie. ### Chrome / Edge / Brave / Vivaldi ```text -1. Repository als ZIP herunterladen oder git clone -2. chrome://extensions öffnen (bzw. edge:// / brave://) -3. Entwicklermodus aktivieren -4. "Entpackte Erweiterung laden" → Ordner auswählen in dem manifest.json liegt -5. Neuen Tab öffnen +1. Download the repository as ZIP or git clone +2. Open chrome://extensions (or edge:// / brave://) +3. Enable developer mode +4. Click "Load unpacked" and select the folder containing manifest.json +5. Open a new tab ``` ### Opera / Opera GX ```bash -# manifest.opera.json als manifest.json verwenden: +# Use manifest.opera.json as manifest.json: copy manifest.opera.json manifest.json # Windows cp manifest.opera.json manifest.json # Linux/Mac ``` ```text -1. opera://extensions öffnen -2. Entwicklermodus aktivieren -3. "Entpackte Erweiterung laden" → Ordner auswählen -4. Neuen Tab öffnen +1. Open opera://extensions +2. Enable developer mode +3. Click "Load unpacked" and select the folder +4. Open a new tab ``` -> **Opera-Hinweis:** Opera GX priorisiert Speed Dial — der enthaltene Workaround -> übernimmt die New-Tab-Seite zuverlässig. Details: [src/js/opera/README.md](src/js/opera/README.md) +> **Opera note:** Opera GX prioritizes Speed Dial, the included workaround +> takes over the new tab page reliably. Details: [src/js/opera/README.md](src/js/opera/README.md) ### Firefox ```bash -# manifest.firefox.json als manifest.json verwenden: +# Use manifest.firefox.json as manifest.json: copy manifest.firefox.json manifest.json # Windows cp manifest.firefox.json manifest.json # Linux/Mac ``` ```text -1. about:debugging#/runtime/this-firefox öffnen -2. "Temporäres Add-on laden" -3. Die manifest.json aus dem Projektordner auswählen +1. Open about:debugging#/runtime/this-firefox +2. Click "Load Temporary Add-on" +3. Select the manifest.json from the project folder ``` -> **Hinweis:** Temporäre Add-ons werden beim Browser-Neustart entfernt. -> Für dauerhafte Installation ist eine signierte `.xpi`-Datei nötig. +> **Note:** Temporary add-ons are removed on browser restart. +> For permanent installation a signed `.xpi` file is required. --- -## Browser-Bookmarks exportieren & importieren +## Importing Browser Bookmarks -| Browser | Export-Pfad | +| Browser | Export path | |---|---| -| Chrome / Edge | Einstellungen → Lesezeichen → Exportieren | -| Firefox | Lesezeichen → Alle Lesezeichen → Importieren und Sichern → Als HTML exportieren | +| Chrome / Edge | Settings → Bookmarks → Export bookmarks | +| Firefox | Bookmarks → All Bookmarks → Import and Backup → Export Bookmarks to HTML | -Die exportierte `.html`-Datei über den **Import**-Button in der Extension laden. +Load the exported `.html` file via the **Import** button in the extension. --- -## Datenschutz +## Privacy -- Keine externe Datenübertragung (außer Google Favicons API für Icons) -- Speicherung in `chrome.storage.local` (Chromium) bzw. `browser.storage.local` (Firefox) -- Keine Tracker, keine Analytics, keine Werbung -- Keine Cookies, keine Session-Daten -- Storage-Quota-Prüfung warnt bei 8 MB+ (Limit: 10 MB) -- Permissions: `storage`, `bookmarks` +- No external data transmission (except Google Favicons API for icons) +- Storage in `chrome.storage.local` (Chromium) or `browser.storage.local` (Firefox) +- No trackers, no analytics, no ads +- No cookies, no session data +- Storage quota check warns at 8 MB+ (limit: 10 MB) +- Permissions: `storage`, `bookmarks` (all browsers) + `tabs` (Opera / Opera GX only) --- -## Tech-Stack +## Tech Stack -| Komponente | Details | +| Component | Details | |---|---| -| Sprache | JavaScript (Vanilla ES2020, keine Frameworks) | -| Styling | CSS Custom Properties (Theme-System) | -| Fonts | Lokale Fonts (Rajdhani, Inter, Cinzel) | -| Storage | `chrome.storage.local` / `localStorage` Fallback | +| Language | JavaScript (Vanilla ES2020, no frameworks) | +| Styling | CSS Custom Properties (theme system) | +| Fonts | Local fonts (Rajdhani, Inter, Cinzel) | +| Storage | `chrome.storage.local` / `localStorage` fallback | | Favicons | Google Favicons API (`/s2/favicons`) | -| Drag & Drop | Pointer Events API (nativ) | -| Build | Kein Build-Schritt — direkt lauffähig | -| CI/CD | GitHub Actions (Security, Quality, Release) | +| Drag & Drop | Pointer Events API (native) | +| Build | No build step, runs directly | +| CI/CD | GitHub Actions (security, quality, release) | --- -## Architektur +## Architecture ```text hellion-newtab/ ├── manifest.json # Chrome, Edge, Brave, Vivaldi (MV3) ├── manifest.firefox.json # Firefox (MV3) -├── manifest.opera.json # Opera / Opera GX (MV3 + Workaround) -├── newtab.html # Haupt-HTML (UI-Struktur, Modals, Settings Panel) +├── manifest.opera.json # Opera / Opera GX (MV3 + workaround) +├── newtab.html # Main HTML (UI structure, modals, settings panel) ├── LICENSE # CC BY-NC-SA 4.0 -├── CHANGELOG.md # Versionshistorie -├── SECURITY.md # Sicherheitsrichtlinie und Meldeprozess -├── DISCLAIMER.md # Haftungsausschluss +├── CHANGELOG.md # Version history +├── SECURITY.md # Security policy and reporting +├── DISCLAIMER.md # Disclaimer and legal │ ├── src/ │ ├── js/ -│ │ ├── storage.js # Storage Abstraction + Quota-Prüfung -│ │ ├── state.js # Globaler State, Defaults, Hilfsfunktionen -│ │ ├── dialog.js # Custom Dialog-System (HellionDialog.alert/confirm) -│ │ ├── themes.js # Theme-Definitionen & Anwendungslogik -│ │ ├── boards.js # Board/Bookmark Rendering, Event Delegation, Modals -│ │ ├── drag.js # Drag & Drop (Pointer Events, Board + Bookmark) -│ │ ├── settings.js # Settings Panel, Theme-Modal, Accordion -│ │ ├── search.js # Suchleiste (Google, DuckDuckGo, Bing) -│ │ ├── sticky.js # Sticky Note Widget (Drag, Persist, Toggle) -│ │ ├── data.js # JSON Export / Import mit Validierung -│ │ ├── onboarding.js # Mehrstufiger Willkommens-Flow -│ │ ├── app.js # Init, Clock, globale Events (Einstiegspunkt) -│ │ └── opera/ # Opera GX Workaround-Skripte -│ │ ├── background.js # Tab-Management gegen Speed Dial -│ │ └── redirect.js # Content Script Redirect +│ │ ├── storage.js # Storage abstraction + quota check +│ │ ├── state.js # Global state, defaults, helpers +│ │ ├── dialog.js # Custom dialog system (HellionDialog.alert/confirm) +│ │ ├── themes.js # Theme definitions & application (11 themes) +│ │ ├── boards.js # Board/bookmark rendering, event delegation, modals +│ │ ├── drag.js # Drag & drop (Pointer Events, board + bookmark) +│ │ ├── settings.js # Settings panel, appearance modal, accordion +│ │ ├── search.js # Search bar (Google, DuckDuckGo, Bing) +│ │ ├── widgets.js # Widget manager (registry, drag, resize, z-index) +│ │ ├── notes.js # Notes & checklists (multi-instance, max. 5) +│ │ ├── calculator.js # Calculator (shunting-yard, history) +│ │ ├── timer.js # Timer/countdown (presets, Web Audio alarm) +│ │ ├── image-ref.js # Image reference widget (Canvas API, sessionStorage) +│ │ ├── data.js # JSON export / import with validation +│ │ ├── onboarding.js # 7-step welcome flow + gaming board +│ │ ├── app.js # Init, clock, global events (entry point) +│ │ └── opera/ # Opera GX workaround scripts +│ │ ├── background.js # Tab management against Speed Dial +│ │ └── redirect.js # Content script redirect │ └── css/ -│ └── main.css # Styles + Theme-System + Responsive Breakpoints +│ └── main.css # Styles + 11 themes + responsive breakpoints │ ├── assets/ -│ ├── fonts/ # Lokale Fonts (Rajdhani, Inter, Cinzel) -│ ├── themes/ # 8 Theme-Hintergrundbilder +│ ├── fonts/ # Local fonts (Rajdhani, Inter, Cinzel) +│ ├── themes/ # 11 theme background images (WebP only) │ └── icons/ │ ├── icon16.png │ ├── icon48.png │ └── icon128.png │ +├── docs/ +│ ├── architecture.md # Project architecture and init sequence +│ ├── widget-schema.md # Widget system API and schema reference +│ ├── patterns.md # Code patterns and conventions +│ └── style-guide.md # Design system and theme documentation +│ └── .github/ └── workflows/ - ├── security.yml # CodeQL-Analyse + Dependency Review - ├── quality.yml # Struktur, Manifest, Syntax, Versions-Konsistenz - └── release.yml # ZIP-Pakete (Chrome + Firefox + Opera) + SHA256 + ├── security.yml # CodeQL analysis + dependency review + ├── quality.yml # Structure, manifest, syntax, version consistency + └── release.yml # ZIP packages (Chrome + Firefox + Opera) + SHA256 ``` -### Design-Prinzipien +### Design Principles -- **Zero Dependencies** — Kein npm, kein Build, kein Framework. Direkt lauffähig -- **Privacy First** — Alle Daten lokal, kein Server-Kontakt -- **Modular** — 12 JS-Dateien mit klarer Zuständigkeit -- **Responsive** — Tablet (768px) und Smartphone (480px) Breakpoints -- **Secure** — `createElement` statt `innerHTML`, URL-Validierung, Storage-Fehlerbehandlung -- **Event Delegation** — Ein Listener pro Board-Liste statt pro Bookmark (Performance) -- **Theme-System** — CSS Custom Properties, 8 Themes, Custom-Background-Support +- **Zero Dependencies** — No npm, no build, no framework. Runs directly +- **Privacy First** — All data local, no server contact +- **Modular** — 15 JS files with clear responsibilities +- **Responsive** — Tablet (768px) and smartphone (480px) breakpoints +- **Secure** — `createElement` instead of `innerHTML`, URL validation, storage error handling +- **Event Delegation** — One listener per board list instead of per bookmark (performance) +- **Theme System** — CSS Custom Properties, 11 themes, custom background support --- @@ -271,85 +284,88 @@ hellion-newtab/ ### Security Scan (`security.yml`) -- **CodeQL-Analyse** — Statische Sicherheitsanalyse für JavaScript -- **Dependency Review** — Prüft Pull Requests auf bekannte Schwachstellen -- **Zeitplan** — Automatisch wöchentlich (Montag 06:00 UTC) + bei Push/PR +- **CodeQL analysis** — Static security analysis for JavaScript +- **Dependency review** — Checks pull requests for known vulnerabilities +- **Schedule** — Automatically weekly (Monday 06:00 UTC) + on push/PR ### Code Quality (`quality.yml`) -- **Projektstruktur** — Alle Pflichtdateien und -ordner vorhanden -- **Manifest-Validierung** — JSON-Syntax, Version, Permissions -- **JavaScript Syntax-Check** — `node --check` für alle JS-Dateien -- **Versions-Konsistenz** — manifest.json, manifest.firefox.json und newtab.html müssen übereinstimmen -- **Icon-Prüfung** — Alle Extension-Icons vorhanden +- **Project structure** — All required files and folders present +- **Manifest validation** — JSON syntax, version, permissions +- **JavaScript syntax check** — `node --check` for all JS files +- **Version consistency** — manifest.json, manifest.firefox.json and newtab.html must match +- **Icon check** — All extension icons present ### Release (`release.yml`) -- **Trigger** — Bei Git-Tag (`v*`) -- **Pakete** — Chrome-ZIP + Firefox-ZIP + Opera-ZIP (alle MV3) -- **Checksummen** — SHA256 für alle Artefakte -- **GitHub Release** — Automatisch mit Installationsanleitung +- **Trigger** — On Git tag (`v*`) +- **Packages** — Chrome ZIP + Firefox ZIP + Opera ZIP (all MV3) +- **Checksums** — SHA256 for all artifacts +- **GitHub Release** — Automatic with installation instructions ```bash -# Release erstellen: -git tag v1.5.2 -git push origin v1.5.2 -# → GitHub Action erstellt automatisch Release mit ZIP-Dateien +# Create a release: +git tag v1.10.0 +git push origin v1.10.0 +# → GitHub Action automatically creates release with ZIP files ``` --- -## Entwicklung +## Development ```bash -# Repository klonen +# Clone the repository git clone https://github.com/JonKazama-Hellion/Hellion-NewTab.git -# Extension im Browser laden (siehe Installation) +# Load the extension in your browser (see Installation) -# Nach Änderungen: Extension neu laden -chrome://extensions → Hellion NewTab → Neu laden +# After changes: reload the extension +chrome://extensions → Hellion NewTab → Reload ``` -Kein Build-Schritt nötig. Dateien ändern, Extension neu laden, fertig. +No build step needed. Change files, reload extension, done. --- -## Sicherheit +## Security -Sicherheitslücken bitte **nicht** über öffentliche Issues melden. -Details zur Meldung, Reaktionszeiten und Sicherheitsarchitektur: [SECURITY.md](SECURITY.md) +Please do **not** report security vulnerabilities through public GitHub issues. +Details on reporting, response times and security architecture: [SECURITY.md](SECURITY.md) --- -## Lizenz & Impressum +## License & Legal Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International -- Kostenlos für private Nutzung -- Teilen und Modifikation erlaubt mit Namensnennung -- Kommerzielle Nutzung ohne Erlaubnis verboten +- Free for private use +- Sharing and modification allowed with attribution +- Commercial use without permission prohibited -Vollständige Lizenz: [LICENSE](LICENSE) | [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) +Full license: [LICENSE](LICENSE) | [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) | | | |---|---| -| **Entwickler** | Florian Wathling | -| **Unternehmen** | Hellion Online Media | +| **Developer** | Florian Wathling | +| **Company** | Hellion Online Media | | **Web** | [hellion-media.de](https://hellion-media.de) | -| **Impressum** | [hellion-media.de/impressum](https://hellion-media.de/impressum) | +| **Imprint** | [hellion-media.de/impressum](https://hellion-media.de/impressum) | | **Bug Reports** | [kontakt@hellion-media.de](mailto:kontakt@hellion-media.de?subject=Hellion%20NewTab%20%E2%80%93%20Bug%20Report) | | **Security** | [SECURITY.md](SECURITY.md) | | **Support** | [Ko-fi](https://ko-fi.com/hellionmedia) | --- -### Einsatz von AI +### Use of AI -AI (Claude Code, Opus 4.6 von Anthropic) wurde als Hilfsmittel eingesetzt — für Fehleridentifikation, Code-Review und Qualitätssicherung. Architektur, Features und alle Entscheidungen sind Eigenleistung. +**Claude:** Code analysis, bug fixing, documentation and proofreading. +**Me:** Architecture, features and logic are planned, thought through and written by me. + +Details: [DISCLAIMER.md](DISCLAIMER.md) --- -> Vollständige Versionshistorie: [CHANGELOG.md](CHANGELOG.md) +> Full version history: [CHANGELOG.md](CHANGELOG.md) -**Hellion NewTab** — [Hellion Online Media](https://hellion-media.de) — JonKazama-Hellion \ No newline at end of file +**Hellion NewTab** — [Hellion Online Media](https://hellion-media.de) — JonKazama-Hellion diff --git a/SECURITY.md b/SECURITY.md index 9cf54ca..8ab1ad4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,76 +1,92 @@ -# Sicherheitsrichtlinie — Hellion NewTab +# Security Policy — Hellion NewTab -## Unterstützte Versionen +## Supported Versions | Version | Status | -| --- | --- | -| 1.2.x | Aktiv unterstützt | -| < 1.2.0 | Nicht unterstützt | +|---|---| +| 1.9.x | Actively supported | +| < 1.9.0 | Not supported | -## Sicherheitslücke melden +## Reporting a Vulnerability -Wenn du eine Sicherheitslücke in Hellion NewTab findest, melde sie bitte **nicht** über ein öffentliches GitHub Issue. +If you find a security vulnerability in Hellion NewTab, please **do not** open a public GitHub issue. -### Kontakt +### Contact -**E-Mail:** [kontakt@hellion-media.de](mailto:kontakt@hellion-media.de?subject=Hellion%20NewTab%20%E2%80%93%20Security%20Report) +**Email:** [kontakt@hellion-media.de](mailto:kontakt@hellion-media.de?subject=Hellion%20NewTab%20%E2%80%93%20Security%20Report) -Bitte folgende Informationen angeben: +Please include the following information: -- Beschreibung der Schwachstelle -- Schritte zur Reproduktion -- Betroffene Version(en) -- Mögliche Auswirkungen (Datenverlust, XSS, etc.) +- Description of the vulnerability +- Steps to reproduce +- Affected version(s) +- Potential impact (data loss, XSS, etc.) -### Reaktionszeit +### Response Times -- **Bestätigung:** Innerhalb von 48 Stunden -- **Ersteinschätzung:** Innerhalb von 7 Tagen -- **Fix:** Abhängig von Schweregrad, Ziel innerhalb von 14 Tagen +- **Acknowledgement:** Within 48 hours +- **Initial assessment:** Within 7 days +- **Fix:** Depends on severity, target within 14 days -### Schweregrad-Einstufung +### Severity Levels -| Stufe | Beschreibung | Beispiel | -| --- | --- | --- | -| Kritisch | Datenverlust oder Remote Code Execution | Storage-Manipulation durch Dritte | -| Hoch | XSS oder ungewollte Datenübertragung | Script-Injection via Bookmark-Import | -| Mittel | Umgehung von UI-Schutzmechanismen | Blur-Bypass, Settings-Manipulation | -| Niedrig | Kosmetisch oder theoretisch | Edge-Cases ohne praktische Auswirkung | - -## Sicherheitsarchitektur - -### Datenverarbeitung - -- **Keine externe Datenübertragung** — Alle Daten bleiben in `chrome.storage.local` -- **Kein Server-Kontakt** — Außer Google Favicons API für Bookmark-Icons -- **Keine Cookies, Sessions oder Tokens** -- **Kein Netzwerkzugriff** außer Favicon-Abruf - -### Eingabe-Validierung - -- URL-Validierung bei Bookmark-Erstellung (`new URL()`) -- JSON-Import: Board- und Bookmark-Struktur wird validiert -- HTML-Sanitierung via `escHtml()` und `createElement` (kein `innerHTML` für User-Daten) -- Storage-Quota-Prüfung mit Warnung bei 8 MB+ - -### Permissions - -Diese Extension benötigt nur zwei Browser-Permissions: - -| Permission | Grund | -| --- | --- | -| `storage` | Boards, Settings und Sticky Note lokal speichern | -| `bookmarks` | Browser-Lesezeichen für HTML-Import lesen | - -Keine Permissions für: Tabs, History, Web Requests, Downloads, Clipboard oder Host-Zugriff. - -### CI/CD-Sicherheit - -- **CodeQL** — Automatische statische Analyse bei Push und PR -- **Dependency Review** — Prüft auf bekannte Schwachstellen in PRs -- **Wöchentlicher Scan** — Automatischer CodeQL-Lauf jeden Montag -- **SHA256-Checksummen** — Alle Release-Artefakte werden signiert +| Level | Description | Example | +|---|---|---| +| Critical | Data loss or remote code execution | Storage manipulation by third parties | +| High | XSS or unintended data transmission | Script injection via bookmark import | +| Medium | UI protection bypass | Blur bypass, settings manipulation | +| Low | Cosmetic or theoretical | Edge cases without practical impact | --- -**Hellion Dashboard** — [Hellion Online Media - Florian Wathling](https://hellion-media.de) — JonKazama-Hellion +## Security Architecture + +### Data Handling + +- **No external data transmission** — all data stays in `chrome.storage.local` +- **No server contact** — except Google Favicons API for bookmark icons +- **No cookies, sessions or tokens** +- **No network access** beyond favicon fetching + +### Input Validation + +- URL validation on bookmark creation (`new URL()`) +- JSON import validates board and bookmark structure before applying +- HTML sanitization via `escHtml()` and `createElement` — no `innerHTML` for user data +- Storage quota check with warning at 8 MB+ + +### Permissions + +This extension requests the following browser permissions: + +| Permission | Browsers | Reason | +|---|---|---| +| `storage` | All | Store boards, settings and widget states locally | +| `bookmarks` | All | Read browser bookmarks for direct import | +| `tabs` | Opera / Opera GX only | Required for the Speed Dial workaround — `background.js` monitors tab URLs and redirects via `chrome.tabs.update` | + +No permissions requested for: history, web requests, downloads, clipboard or host access. + +### CI/CD Security + +- **CodeQL** — Automatic static analysis on every push and PR +- **Dependency Review** — Checks for known vulnerabilities in PRs +- **Weekly scan** — Automated CodeQL run every Monday at 06:00 UTC +- **SHA256 checksums** — All release artifacts are checksummed + +--- + +## Legal + +Hellion NewTab is developed and maintained by **Florian Wathling / Hellion Online Media**, +based in Bad Harzburg, Germany. + +All security matters are handled in accordance with **German and EU law**, including +the General Data Protection Regulation (GDPR / DSGVO). Users in the European Union +are covered by the same legal framework. + +For legal inquiries: [hellion-media.de/impressum](https://hellion-media.de/impressum) + +--- + +**Hellion Dashboard** — [Hellion Online Media — Florian Wathling](https://hellion-media.de) — JonKazama-Hellion diff --git a/docs/STYLE_GUIDE.md b/docs/STYLE_GUIDE.md new file mode 100644 index 0000000..0b99bdb --- /dev/null +++ b/docs/STYLE_GUIDE.md @@ -0,0 +1,316 @@ +# Hellion Dashboard — Design & Theme System + +> This document is intentionally written in English. Full German/English i18n support +> is planned for v2.0 — until then, English keeps the docs accessible to anyone +> who wants to contribute or fork the project. + +--- + +## Design Pillars + +| Pillar | Description | +|---|---| +| **Immersion** | The interface feels like a HUD floating over the scene, not a foreign object sitting on top of it | +| **Visual Clarity** | Deliberate use of `blur` separates UI from background and reduces visual noise and cognitive load | +| **Harmony** | Every theme pulls its colors from the dominant light sources in its background image | + +--- + +## Background Images — WebP Only + +**All background images must be in WebP format.** This is an intentional architectural +decision to keep storage quota usage predictable and leave room for future features +(widgets, image references, etc.) that also compete for the 10 MB `chrome.storage` limit. + +JPG, PNG and other formats are not accepted, so convert before adding a theme. + +### Recommended Settings + +| Quality | When to use | +|---|---| +| 85 | Default, good balance of size and sharpness | +| 80 | For images over 500 KB | +| 90 | For images with fine details (stars, in-game UI text) | + +### Conversion Tools + +**Squoosh** (squoosh.app) — browser-based, no install, nothing gets uploaded to external servers. +Drag in the image, pick WebP, set quality to 85, download. Done. + +**cwebp** (command line): +```bash +cwebp -q 85 input.jpg -o output.webp +``` + +### Current Theme Images + +| File | Status | +|---|---| +| `bg-nebula.webp` | ✅ WebP | +| `bg-crescent.webp` | ✅ WebP | +| `bg-event-horizon.webp` | ✅ WebP | +| `bg-merchantman.webp` | ✅ WebP | +| `bg-julia-jin.webp` | ✅ WebP | +| `bg-sc-sunset.webp` | ✅ WebP | +| `bg-hellion-hud.webp` | ✅ WebP | +| `bg-hellion-energy.webp` | ✅ WebP | +| `bg-satisfactory.webp` | ✅ WebP | +| `bg-avorion.webp` | ✅ WebP | +| `bg-scPolaris.webp` | ✅ WebP | + +--- + +## Anatomy of a Theme + +Every theme lives in `main.css` as a `[data-theme="name"]` block. Copy this template +to add a new one: + +```css +[data-theme="your-theme-name"] { + /* 1. ACCENTS — The light source */ + --accent: #HEXCODE; /* Main color (neon/light) */ + --accent-dim: rgba(R, G, B, 0.12); /* Subtle background tint */ + --accent-glow: rgba(R, G, B, 0.08); /* Glow for logo & clock */ + --border-accent: rgba(R, G, B, 0.25); /* Focus ring */ + + /* 2. BASE — The foundation */ + --bg-primary: #HEXCODE; /* Darkest point in the image */ + --bg-board: rgba(R, G, B, 0.55); /* Glass effect on boards */ + --border: rgba(R, G, B, 0.12); /* Default border */ + + /* 3. TEXT — Contrast */ + --text-primary: #FFFFFF; /* Readable, slightly tinted */ + --text-secondary: #A0A0A0; /* Desaturated, less visual weight */ + --text-muted: #606060; /* Barely visible, for hints */ + + /* 4. OVERLAY — Vignette */ + --overlay-bg: radial-gradient( + circle at center, + transparent 0%, + var(--bg-primary) 100% + ); + + /* 5. COMPONENT COLORS */ + --header-bg: rgba(R, G, B, 0.94); + --board-hover-border: rgba(R, G, B, 0.22); + --toggle-on-bg: rgba(R, G, B, 0.20); + --logo-shadow: rgba(R, G, B, 0.50); + + /* 6. FONTS */ + --font-display: 'Rajdhani', sans-serif; + --font-body: 'Inter', sans-serif; +} + +/* Theme-specific overrides */ +[data-theme="your-theme-name"] .logo { letter-spacing: 4px; } +[data-theme="your-theme-name"] .clock { color: var(--accent); } +[data-theme="your-theme-name"] .board-title { text-transform: uppercase; } +[data-theme="your-theme-name"] .board { backdrop-filter: blur(8px); } +[data-theme="your-theme-name"] .bm-item:hover { background: var(--accent-dim); } +``` + +After adding the CSS block, register the theme in `src/js/themes.js` and add a preview entry in the theme picker. + +--- + +## UI Patterns + +### Frosted Glass + +Hardware-accelerated blur for readability on complex backgrounds: + +```css +backdrop-filter: blur(8px); +``` + +Creates depth and visual calm behind text and UI elements. Standard value is `8px`. Only increase it when the background image has a lot of fine detail that competes with the UI. + +### Clock Color + +All themes set `color: var(--accent)` on the clock element. This is a consistent +detail across the entire theme system. Don't skip it for new themes. + +```css +[data-theme="your-theme"] .clock { color: var(--accent); } +``` + +### Typography Hierarchy + +| Font | Usage | +|---|---| +| **Rajdhani** | Display: clock, logo, titles. Anything that should feel like a system readout | +| **Inter** | Body: bookmark titles, lists, interactive elements | +| **Cinzel** | Fantasy: reserved for themes with a majestic or ancient aesthetic (Crescent, Julia & Jin) | + +### Overlay Strategy + +The overlay gradient determines what stays visible in the background image. + +**Radial (default)** draws attention to the center and darkens edges: +```css +--overlay-bg: radial-gradient(circle at center, transparent 0%, var(--bg-primary) 100%); +``` + +**Linear** darkens top and bottom and leaves the middle open. Use when the subject +is horizontally centered and should stay visible (Satisfactory factory floor, SC Sunset horizon): +```css +--overlay-bg: linear-gradient(180deg, rgba(R,G,B,0.85) 0%, rgba(R,G,B,0.15) 50%, rgba(R,G,B,0.90) 100%); +``` + +Choose based on where the most important part of the image is, not by habit. + +--- + +## Focus & Accessibility + +For backgrounds with a lot of detail (many small elements, high contrast, busy textures), +increase board alpha and blur to reduce visual noise. This makes boards easier to scan, +especially for users with ADHD or attention sensitivities. + +```css +--bg-board: rgba(R, G, B, 0.65); /* Up from default 0.55 */ +backdrop-filter: blur(12px); /* Up from default 8px */ +``` + +This was applied intentionally to the Satisfactory theme, because the factory floor screenshot +has a lot going on and needed more visual separation between background and UI. + +--- + +## All 11 Themes + +| Theme | File | Accent | Mood | Overlay | +|---|---|---|---|---| +| Nebula | `bg-nebula.webp` | `#b359ff` Magenta | Chill, Cosmic | Radial | +| Crescent | `bg-crescent.webp` | `#d4bd8a` Gold | Luxury, Night | Radial | +| Event Horizon | `bg-event-horizon.webp` | `#9d5cff` Purple | Deep Space, Void | Radial | +| Merchantman | `bg-merchantman.webp` | `#2eb8b8` Emerald | Industrial, Alien | Radial | +| Julia & Jin | `bg-julia-jin.webp` | `#7db3ff` Aetherial Blue | FFXIV Night | Linear | +| SC Sunset | `bg-sc-sunset.webp` | `#ff8c3d` Amber | Emotional, Horizon | Linear | +| Hellion HUD | `bg-hellion-hud.webp` | `#32ff6a` Neon Green | Tactical, Admin | Radial | +| Hellion Energy | `bg-hellion-energy.webp` | `#1eff8e` Acid Green | Overdrive, Power | Radial | +| Satisfactory | `bg-satisfactory.webp` | `#00b4d8` Cyan | Industrial Desert | Linear | +| Avorion | `bg-avorion.webp` | `#2ec4a0` Turquoise | Deep Void | Radial | +| Hellion Stealth | `bg-scPolaris.webp` | `#5ec2ff` Tech Blue | Tactical Recon | Radial | + +### Theme Quirks Worth Knowing + +**Julia & Jin** uses `Cinzel` as display font and a linear gradient. The subjects in +the screenshot are positioned left of center, so radial would soften them. + +**Satisfactory** has increased board alpha (0.65) and stronger blur (12px), an intentional +ADHD optimization for a visually busy background. + +**Avorion** uses `letter-spacing: 6px` on the logo for maximum HUD feel. + +**Hellion Stealth** is the only theme with `border-left: 2px solid var(--accent)` on +`.bm-item:hover`. Every other theme uses background tinting only. This is intentional +and gives Stealth its tactical scanner character. Don't apply it to other themes. + +--- + +## Registering a Theme in themes.js + +The `THEMES` object in `src/js/themes.js` is the single source of truth for which +themes exist and which background image they use. CSS handles all the visual variables — +`themes.js` only needs the image path. + +```javascript +const THEMES = { + 'nebula': { bg: 'assets/themes/bg-nebula.webp' }, + 'crescent': { bg: 'assets/themes/bg-crescent.webp' }, + 'event-horizon': { bg: 'assets/themes/bg-event-horizon.webp' }, + 'merchantman': { bg: 'assets/themes/bg-merchantman.webp' }, + 'julia-jin': { bg: 'assets/themes/bg-julia-jin.webp' }, + 'sc-sunset': { bg: 'assets/themes/bg-sc-sunset.webp' }, + 'hellion-hud': { bg: 'assets/themes/bg-hellion-hud.webp' }, + 'hellion-energy': { bg: 'assets/themes/bg-hellion-energy.webp' }, + 'satisfactory': { bg: 'assets/themes/bg-satisfactory.webp' }, + 'avorion': { bg: 'assets/themes/bg-avorion.webp' }, + 'hellion-stealth': { bg: 'assets/themes/bg-scPolaris.webp' } +}; +``` + +To add a new theme, add one line. The key must exactly match the `data-theme` +attribute in the CSS block. If they don't match, `applyTheme()` will silently +do nothing and no one will know why. + +```javascript +// New theme: key must match [data-theme="your-theme-name"] in main.css +'your-theme-name': { bg: 'assets/themes/bg-your-theme.webp' } +``` + +### How applyTheme() works + +```javascript +function applyTheme(themeName, skipBgOverride) { + const theme = THEMES[themeName]; + if (!theme) return; + + // Sets data-theme on — activates the matching CSS variable block + document.documentElement.setAttribute('data-theme', themeName); + + // Applies the background image unless a custom background is active + if (!skipBgOverride) { + document.getElementById('bgLayer').style.backgroundImage = `url('${theme.bg}')`; + } + + // Updates the active state in the theme picker UI + document.querySelectorAll('.theme-card').forEach(card => { + card.classList.toggle('active', card.dataset.value === themeName); + }); +} +``` + +The `skipBgOverride` flag exists for one specific case: when a user has set a custom +background image, switching themes should still update the CSS variables and the picker +UI, but not wipe their custom image. Pass `true` to skip the background update. + +--- + +## Adding a Theme Card to newtab.html + +The theme picker modal lives in `newtab.html` as `#themeOverlay`. Every theme +needs a card in the `.theme-grid` — without it the theme exists in CSS and JS +but never shows up in the UI. + +Copy this block and add it inside `.theme-grid`, after the last existing card: + +```html +
+ Your Theme + Your Theme + ✓ +
+``` + +Three things that must match exactly: + +- `data-value` must match the key in `THEMES` in `themes.js` +- `data-value` must match the `[data-theme="..."]` attribute in `main.css` +- `src` must point to the correct WebP file in `assets/themes/` + +The label shown in the picker can be shorter than the full theme name — "HUD" and +"Energy" are good examples of that. Keep it short enough to fit the card. + +The `active` class is toggled by `applyTheme()` automatically, so don't add it +manually unless you want that theme to be the default on first load (Nebula currently +has it as fallback). + +--- + +## Adding a New Theme — Checklist + +- [ ] Background image converted to WebP (quality 85) +- [ ] Image added to `assets/themes/` +- [ ] CSS block added to `src/css/main.css` +- [ ] Theme registered in `src/js/themes.js` (one line, key + bg path) +- [ ] Theme card added to `.theme-grid` in `newtab.html` (data-value, img src, label) +- [ ] Theme added to theme table in `README.md` +- [ ] Theme added to theme table in this document +- [ ] Image credit added to Bild-Credits table in `README.md` +- [ ] `CHANGELOG.md` entry added + +--- + +Developed by **[Hellion Online Media — Florian Wathling](https://hellion-media.de)** — JonKazama-Hellion diff --git a/docs/architecture.md b/docs/architecture.md index 91b94d4..e0f4bd2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,11 +1,17 @@ # Hellion Dashboard — Architecture +> This document is intentionally written in English. Full German/English i18n support +> is planned for v2.0 — until then, English keeps the docs accessible to anyone +> who wants to contribute or fork the project. + +--- + ## Overview Hellion Dashboard is a browser extension (NewTab replacement) built with **Vanilla JavaScript ES2020**, **CSS Custom Properties**, and **zero dependencies**. No build step, no framework, no bundler — files are loaded directly via ` @@ -117,8 +124,6 @@ Scripts are loaded in `newtab.html` in dependency order: ``` -**Rule:** A module may only reference modules loaded before it. - --- ## Z-Index Hierarchy @@ -133,7 +138,7 @@ Scripts are loaded in `newtab.html` in dependency order: | Dialogs / Modals | 300 | `.hellion-dialog-overlay`, modals | | Onboarding | 400 | `#onboardingOverlay` | -Widgets use incrementing z-index (`WidgetManager._topZ++`) to stack above each other on click. +Widgets use an incrementing z-index (`WidgetManager._topZ++`) so the last clicked widget always sits on top. --- @@ -143,9 +148,9 @@ Widgets use incrementing z-index (`WidgetManager._topZ++`) to stack above each o |---|---|---| | `boards` | Array | Board objects with bookmarks | | `settings` | Object | User preferences (theme, toggles, etc.) | -| `widgetStates` | Object | All widget data (see [widget-schema.md](widget-schema.md)) | -| `onboardingDone` | Boolean | Whether onboarding has been completed | -| `lastBackupReminder` | Number | Timestamp of last backup reminder | +| `widgetStates` | Object | All widget data — see [widget-schema.md](widget-schema.md) | +| `onboardingDone` | Boolean | Whether the first-run onboarding has been completed | +| `lastBackupReminder` | Number | Timestamp of the last backup reminder | --- @@ -160,4 +165,5 @@ Widgets use incrementing z-index (`WidgetManager._topZ++`) to stack above each o | Opera / GX | Chromium MV3 | `manifest.opera.json` | | Firefox | Gecko MV3 | `manifest.firefox.json` | -Changes affecting manifest fields must be synchronized across all three manifest files. +Any change that touches manifest fields — version numbers, permissions, content scripts — +needs to be applied to all three files. The CI quality check will catch it if they drift out of sync. diff --git a/docs/patterns.md b/docs/patterns.md index aa9d1d5..b9f80bb 100644 --- a/docs/patterns.md +++ b/docs/patterns.md @@ -1,5 +1,11 @@ # Hellion Dashboard — Code Patterns & Conventions +> This document is intentionally written in English. Full German/English i18n support +> is planned for v2.0 — until then, English keeps the docs accessible to anyone +> who wants to contribute or fork the project. + +--- + ## Core Principles - **Vanilla JS ES2020** — No frameworks, no TypeScript, no build step @@ -15,11 +21,11 @@ **File:** `src/js/storage.js` -All persistent data goes through the `Store` object. Never access `chrome.storage` or `localStorage` directly. +All persistent data goes through the `Store` object. Never access `chrome.storage` or `localStorage` directly — `Store` handles the fallback between the two transparently and provides unified error handling when storage is full. ```javascript // Reading -const boards = await Store.get('boards'); // Returns null if not found +const boards = await Store.get('boards'); // Returns null if not found const settings = await Store.get('settings'); // Writing @@ -30,13 +36,11 @@ await Store.set('settings', settings); await Store.checkQuota(); ``` -**Why?** The `Store` handles the chrome.storage / localStorage fallback transparently. It also provides unified error handling (shows a dialog when storage is full). - --- ## Pattern: Event Delegation -Instead of attaching listeners to each element, attach one to the container and use `closest()` to find the target. +One listener on the container, `closest()` to find the target. Much cleaner than attaching a listener to every single element, and it works automatically for dynamically added content. ```javascript // GOOD — one listener, handles all bookmarks @@ -53,13 +57,13 @@ bookmarks.forEach(bm => { }); ``` -**Used in:** `boards.js` (board/bookmark events), `notes.js` (toolbar), `calculator.js` (button grid) +Used in `boards.js` (board/bookmark events), `notes.js` (toolbar) and `calculator.js` (button grid). --- ## Pattern: createElement over innerHTML -Always build DOM with `document.createElement()`. This prevents XSS and is the project's #1 security rule. +Always build DOM with `document.createElement()`. This is the project's #1 security rule — `innerHTML` with user-provided content is an XSS risk, full stop. ```javascript // GOOD @@ -76,7 +80,7 @@ container.innerHTML = `${title}`; ## Pattern: Shared Storage Key -Multiple widget modules share the `widgetStates` key. Every module must read-before-write and preserve other modules' data. +All widget modules share the `widgetStates` storage key. Every module that writes to it must read first and preserve what's already there — otherwise modules silently overwrite each other's data. ```javascript async save() { @@ -85,7 +89,7 @@ async save() { // Write your own data data.yourKey = { /* ... */ }; - // DON'T overwrite — the key already contains other modules' data + // Don't replace the whole object — other modules live here too await Store.set('widgetStates', data); } ``` @@ -96,13 +100,13 @@ See [widget-schema.md](widget-schema.md) for the full `widgetStates` structure. ## Pattern: Widget Lifecycle Hooks -Single-instance widgets (Calculator, Timer) need to know when they're closed, minimized, or reopened. They wrap `WidgetManager` methods in their `init()`: +Single-instance widgets (Calculator, Timer) need to react when they're closed, minimized, or reopened. They do this by wrapping `WidgetManager` methods in their `init()`. ```javascript async init() { - // Wrap close const prevClose = WidgetManager.close; const self = this; + WidgetManager.close = function(id) { prevClose.call(WidgetManager, id); if (id === self.WIDGET_ID) { @@ -110,7 +114,6 @@ async init() { } }; - // Wrap minimize const prevMinimize = WidgetManager.minimize; WidgetManager.minimize = async function(id) { await prevMinimize.call(WidgetManager, id); @@ -122,13 +125,13 @@ async init() { } ``` -**Important:** Multiple widgets chain these wraps. Calculator wraps first, Timer wraps Calculator's already-wrapped version, and so on. The chain must not break. +Multiple widgets chain these wraps — Calculator wraps first, Timer wraps Calculator's already-wrapped version, and so on. Always call the previous method (`prevClose.call(...)`) or the chain breaks and other widgets stop responding. --- ## Pattern: Debounced Save -For frequent updates (typing in notes, moving widgets), use debounced saves to avoid excessive storage writes: +For frequent updates like typing in notes or dragging widgets, debouncing avoids hammering storage with a write on every keystroke. ```javascript _saveTimer: null, @@ -138,20 +141,20 @@ _debouncedSave() { this._saveTimer = setTimeout(() => this.save(), 500); } -// Usage: call _debouncedSave() instead of save() for frequent events +// Use _debouncedSave() instead of save() for frequent events textarea.addEventListener('input', () => { noteData.content = textarea.value; this._debouncedSave(); }); ``` -**Used in:** `notes.js` (text editing), `image-ref.js` (label editing) +Used in `notes.js` (text editing) and `image-ref.js` (label editing). --- ## Pattern: Theme System -All themes use CSS Custom Properties defined in `[data-theme="name"]` blocks: +All themes use CSS Custom Properties in `[data-theme="name"]` blocks in `main.css`. There are currently 11 themes. ```css [data-theme="nebula"] { @@ -164,55 +167,51 @@ All themes use CSS Custom Properties defined in `[data-theme="name"]` blocks: } ``` -**Never hardcode colors in JS.** Use CSS classes or variables: +Never hardcode colors in JS. Let CSS handle it. ```javascript -// GOOD — let CSS handle colors +// GOOD element.classList.add('active'); -// BAD — hardcoded color +// BAD — breaks every theme that isn't Nebula element.style.color = '#7db3ff'; ``` -8 themes are available: Nebula, Crescent, Event Horizon, Merchantman, Julia & Jin, SC Sunset, Hellion HUD, Hellion Energy. - --- ## Pattern: Onboarding Slides -The onboarding system (`onboarding.js`) uses a data-driven slide array. Each slide is an object with rendering hints: +The onboarding system in `onboarding.js` is data-driven. Each slide is a plain object — add a new slide by adding an object to the `slides` array, the `_render()` method handles the rest. ```javascript { hero: '🎮', // Large emoji/icon - title: 'Slide Title', // Heading - text: 'Description...', // Optional text paragraph + title: 'Slide Title', + text: 'Optional description', features: ['Item 1', ...], // Optional bullet list showThemes: true, // Optional theme grid interactive: 'gaming-board' // Optional custom buttons } ``` -The `_render()` method reads these properties and builds the DOM. To add a new slide, just add an object to the `slides` array. - --- ## Pattern: Dialog System -Custom dialogs replace native `alert()` and `confirm()`: +Custom dialogs replace native `alert()` and `confirm()` everywhere in the project. ```javascript -// Alert (informational) +// Informational await HellionDialog.alert('Message text', { - type: 'info', // 'info', 'success', 'warning', 'danger' + type: 'info', // 'info', 'success', 'warning', 'danger' title: 'Title' }); -// Confirm (yes/no) +// Yes/no const ok = await HellionDialog.confirm('Are you sure?', { type: 'danger', title: 'Delete', - confirmText: 'Delete', // Custom button text + confirmText: 'Delete', cancelText: 'Cancel' }); if (ok) { /* user confirmed */ } @@ -222,7 +221,7 @@ if (ok) { /* user confirmed */ } ## Pattern: Pointer Events for Drag -Widget dragging and board reordering use the Pointer Events API (not mouse events): +Widget dragging and board reordering use the Pointer Events API instead of mouse events. The reason: Pointer Events work with both mouse and touch, and `setPointerCapture` keeps the events flowing even if the cursor leaves the element mid-drag. ```javascript element.addEventListener('pointerdown', (e) => { @@ -243,13 +242,11 @@ element.addEventListener('pointerdown', (e) => { }); ``` -**Why Pointer Events over Mouse Events?** They work with both mouse and touch, and `setPointerCapture` ensures events continue even if the cursor leaves the element. - --- ## Pattern: Canvas API Image Processing -The image reference widget converts uploaded images to WebP for smaller size: +The image reference widget converts uploaded images to WebP locally in the browser — no external service, no upload, nothing leaves the device. ```javascript _processFile(file) { @@ -264,7 +261,7 @@ _processFile(file) { const ctx = canvas.getContext('2d'); ctx.drawImage(img, 0, 0); const webpUrl = canvas.toDataURL('image/webp', 0.85); - URL.revokeObjectURL(objectUrl); + URL.revokeObjectURL(objectUrl); // Always free the object URL resolve(webpUrl); }; @@ -278,7 +275,7 @@ _processFile(file) { } ``` -**Important:** Always call `URL.revokeObjectURL()` to free memory. +Always call `URL.revokeObjectURL()` after the image has loaded — skipping it leaks memory. --- @@ -287,24 +284,25 @@ _processFile(file) { | Rule | Rationale | |---|---| | `createElement` only, never `innerHTML` | XSS prevention | -| All storage through `Store` | Browser compatibility | -| CSS variables, no hardcoded colors | Theme support | -| Event delegation | Performance, dynamic content | +| All storage through `Store` | Browser compatibility + unified error handling | +| CSS variables, no hardcoded colors | Theme support across all 11 themes | +| Event delegation | Performance, works with dynamic content | | `const`/`let`, never `var` | Block scoping | | No external dependencies | Extension simplicity | -| No build step | Direct development | -| JSDoc comments on public functions | Documentation | +| No build step | Direct development, no toolchain to break | +| JSDoc comments on public functions | Documentation for contributors | | URL validation before `href` | Security | | Error handling on storage operations | Graceful failure | +| `URL.revokeObjectURL()` after Canvas ops | Memory management | --- ## Manifest Synchronization -Three manifest files must stay in sync: +Three manifest files must always stay in sync: - `manifest.json` — Chrome, Edge, Brave, Vivaldi - `manifest.firefox.json` — Firefox - `manifest.opera.json` — Opera, Opera GX -When changing version numbers, permissions, or content script entries, update all three files. +Version numbers, permissions and content script entries need to be updated in all three. The CI quality check will catch drift, but it's cleaner not to let it get there in the first place. diff --git a/docs/widget-schema.md b/docs/widget-schema.md index 04415a5..ce7d50b 100644 --- a/docs/widget-schema.md +++ b/docs/widget-schema.md @@ -1,8 +1,14 @@ # Hellion Dashboard — Widget Schema +> This document is intentionally written in English. Full German/English i18n support +> is planned for v2.0 — until then, English keeps the docs accessible to anyone +> who wants to contribute or fork the project. + +--- + ## Overview -The widget system provides draggable, resizable floating panels managed by `WidgetManager` (`src/js/widgets.js`). Each widget type has its own module that handles content rendering and state management. +The widget system provides draggable, resizable floating panels managed by `WidgetManager` (`src/js/widgets.js`). Each widget type has its own module that handles content rendering and state management — `WidgetManager` only knows about DOM and position, never about content. --- @@ -21,23 +27,23 @@ The widget system provides draggable, resizable floating panels managed by `Widg ### `create(type, config) → string` -Creates a widget and appends it to the DOM. +Creates a widget and appends it to the DOM. Returns the widget ID. ```javascript const id = WidgetManager.create('note', { - id: 'note_abc123', // Optional, auto-generated if omitted - title: 'My Note', // Default: 'Note' - x: 120, // Left position in px - y: 80, // Top position in px - width: 280, // Width in px (min: 200) - height: 220, // Height in px (min: 150) - open: true // Visible state (default: true) + id: 'note_abc123', // Optional, auto-generated if omitted + title: 'My Note', // Default: 'Note' + x: 120, // Left position in px + y: 80, // Top position in px + width: 280, // Width in px (min: 200) + height: 220, // Height in px (min: 150) + open: true // Visible state (default: true) }); ``` ### `getBody(id) → HTMLElement | null` -Returns the `.widget-body` element for content rendering. +Returns the `.widget-body` element. This is where your module renders its content. ```javascript const body = WidgetManager.getBody('widget_calculator'); @@ -46,7 +52,7 @@ if (body) Calculator.renderBody(body); ### `getState(id) → Object | null` -Returns the current widget state (position, size, open status). +Returns the current widget state — position, size, open status. ```javascript const state = WidgetManager.getState('widget_timer'); @@ -55,11 +61,11 @@ const state = WidgetManager.getState('widget_timer'); ### `close(id)` -Permanently removes a widget from the DOM and registry. +Permanently removes a widget from the DOM and registry. No undo. ### `minimize(id)` -Hides a widget with animation. Widget remains in registry with `open: false`. +Hides a widget with animation. The widget stays in the registry with `open: false` so it can be restored. ### `openWidget(id)` @@ -67,36 +73,36 @@ Restores a minimized widget with animation. ### `bringToFront(id)` -Increments z-index to bring widget above all others. +Increments z-index so the widget sits above everything else. Called automatically on `pointerdown`. ### `save() → Array` -Returns an array of all `type: 'note'` widget states. Used by `Notes.save()` to merge with note content data. +Returns an array of all `type: 'note'` widget states. Used by `Notes.save()` to merge position/size data with note content. ### `restore(renderCallback)` -Loads widget states from storage and recreates all note widgets. Only handles notes — single-instance widgets (calculator, timer) restore themselves in their own `init()`. +Loads widget states from storage and recreates all note widgets. Single-instance widgets (Calculator, Timer) restore themselves in their own `init()` — `restore()` only handles notes. --- ## Shared Storage Key: `widgetStates` -All widget modules share a single storage key. Each module's `save()` method must preserve other modules' data. +All widget modules share a single storage key. Every module's `save()` must read first and preserve whatever it doesn't own — otherwise modules silently wipe each other's data on every save. ```javascript -// Structure of widgetStates +// Full widgetStates structure { notes: [ { id: 'note_abc123', title: 'My Note', content: 'Hello world', - template: 'text', // 'text' or 'checklist' + template: 'text', // 'text' or 'checklist' x: 120, y: 80, width: 280, height: 220, open: true, - checklistItems: [], // For checklist template - checkedItems: [] // Checked item IDs + checklistItems: [], // Only used by checklist template + checkedItems: [] // Checked item IDs } ], calculator: { @@ -124,26 +130,27 @@ All widget modules share a single storage key. Each module's `save()` method mus x: 200, y: 120, width: 320, height: 280, open: true + // Image data is NOT stored here — sessionStorage only } ] } } ``` -### Save Pattern — Preserving Other Modules' Data +### The Save Pattern -Every module that saves to `widgetStates` must read existing data first and preserve keys it doesn't own: +Every module that touches `widgetStates` must follow this pattern: ```javascript -// Example from notes.js +// From notes.js — same pattern applies to every widget module async save() { const existing = await Store.get(this.STORAGE_KEY); const saveData = { notes: mergedNotes }; - // Preserve other modules + // Preserve everything we don't own if (existing && existing.calculator) saveData.calculator = existing.calculator; - if (existing && existing.timer) saveData.timer = existing.timer; - if (existing && existing.imageRef) saveData.imageRef = existing.imageRef; + if (existing && existing.timer) saveData.timer = existing.timer; + if (existing && existing.imageRef) saveData.imageRef = existing.imageRef; await Store.set(this.STORAGE_KEY, saveData); } @@ -153,20 +160,21 @@ async save() { ## Creating a New Widget Type -### Step 1: Choose Single or Multi-Instance +### Step 1: Single or Multi-Instance? -- **Single-instance** (like Calculator, Timer): One widget with a fixed ID. `toggle()` opens/closes. -- **Multi-instance** (like Notes, ImageRef): Multiple widgets with dynamic IDs. `create()` adds new ones. +**Single-instance** (Calculator, Timer style): one widget, fixed ID, `toggle()` opens and closes it. +**Multi-instance** (Notes, ImageRef style): multiple widgets, dynamic IDs, `create()` adds new ones. -### Step 2: Create the Module (`src/js/your-widget.js`) +### Step 2: Create the Module + +Here's a minimal single-instance widget template. Follow the same structure — the lifecycle hooks especially are easy to get wrong. ```javascript const YourWidget = { - WIDGET_ID: 'widget_yourwidget', // Fixed ID for single-instance + WIDGET_ID: 'widget_yourwidget', STORAGE_KEY: 'widgetStates', _isOpen: false, - // Load state from storage async load() { const data = await Store.get(this.STORAGE_KEY); if (data && data.yourWidget) { @@ -174,25 +182,23 @@ const YourWidget = { } }, - // Save state, preserving other modules async save() { const data = await Store.get(this.STORAGE_KEY) || {}; if (data.notes === undefined) data.notes = []; const widgetState = WidgetManager.getState(this.WIDGET_ID); data.yourWidget = { - x: widgetState ? widgetState.x : 400, - y: widgetState ? widgetState.y : 120, - width: widgetState ? widgetState.width : 280, + x: widgetState ? widgetState.x : 400, + y: widgetState ? widgetState.y : 120, + width: widgetState ? widgetState.width : 280, height: widgetState ? widgetState.height : 300, - open: this._isOpen, + open: this._isOpen, // ... your custom data }; await Store.set(this.STORAGE_KEY, data); }, - // Open widget async open() { if (this._isOpen) { WidgetManager.bringToFront(this.WIDGET_ID); @@ -203,13 +209,13 @@ const YourWidget = { const saved = (data && data.yourWidget) ? data.yourWidget : {}; WidgetManager.create('yourwidget', { - id: this.WIDGET_ID, - title: 'Your Widget', - x: saved.x || 400, - y: saved.y || 120, - width: saved.width || 280, + id: this.WIDGET_ID, + title: 'Your Widget', + x: saved.x || 400, + y: saved.y || 120, + width: saved.width || 280, height: saved.height || 300, - open: true + open: true }); const body = WidgetManager.getBody(this.WIDGET_ID); @@ -219,7 +225,6 @@ const YourWidget = { await this.save(); }, - // Toggle open/close async toggle() { if (this._isOpen) { const entry = WidgetManager._widgets.get(this.WIDGET_ID); @@ -237,24 +242,23 @@ const YourWidget = { } }, - // Render widget content renderBody(bodyEl) { bodyEl.textContent = ''; - // Build your UI with createElement (never innerHTML!) + // Build your UI with createElement — never innerHTML! }, - // Initialize and hook into lifecycle async init() { await this.load(); - // Restore if was open last time const data = await Store.get(this.STORAGE_KEY); if (data && data.yourWidget && data.yourWidget.open) { await this.open(); } - // Hook into close event + // Lifecycle hooks — always call the previous method first + // or you'll break every widget that wrapped before yours const self = this; + const prevClose = WidgetManager.close; WidgetManager.close = function(id) { prevClose.call(WidgetManager, id); @@ -264,7 +268,6 @@ const YourWidget = { } }; - // Hook into minimize event const prevMinimize = WidgetManager.minimize; WidgetManager.minimize = async function(id) { await prevMinimize.call(WidgetManager, id); @@ -274,7 +277,6 @@ const YourWidget = { } }; - // Hook into open event const prevOpen = WidgetManager.openWidget; WidgetManager.openWidget = async function(id) { await prevOpen.call(WidgetManager, id); @@ -293,38 +295,33 @@ const YourWidget = { ### Step 3: Integration Checklist -1. **`newtab.html`** — Add `