Ranobe Gemini

NOTICE FOR REVIEWERS: Please check this Reviewer Notes

---

Cross-platform AI reading companion for web novels and fanfiction

Ranobe Gemini is a local-first browser extension that enhances chapter readability, generates summaries, and manages a full reading library across multiple sites.

Privacy-safe impact metrics

• Metrics are collected only after explicit consent on first Library open.
• Telemetry records anonymous event counts only (startup/install/feature usage/opt-in/out).
• No chapter text, reading history payloads, API keys, OAuth tokens, or personal identifiers are sent.
• Public counters are visible on the landing page: https://ranobe.vkrishna04.me/#impact

Features

• AI-Powered Enhancement: Improves grammar, flow, and readability of translated text using Gemini AI.
• Chapter Summarization: Generates concise or detailed summaries for long chapters without leaving the page.
• Multi-Site Support: Works on ranobes.top, fanfiction.net (desktop + mobile), archiveofourown.org (AO3), scribblehub.com, and more.
• Novel Library: Track novels across all supported sites with shelf-aware metadata, reading status, characters, relationships, genres, and tags.
• Shareable Library Deep Links: Open and share direct modal links like library.html?novel=<id>&openModal=1 with context-aware prev/next modal navigation on the library and per-site shelf pages.
• Missing-ID Recovery Flow: If a shared modal link points to a novel not yet in your library, Ranobe Gemini can regenerate the source URL, open it, and auto-add the entry.
• Reading Lists & Badges: Apply list badges independent of status (🔁 Rereading, ⭐ Favourites, plus custom labels like R18).
• Unified Status Dropdown: Manage primary status and toggle reading-list membership directly from each novel card dropdown.
• Compact Mobile Controls: Narrow-screen library chips and filters stay compact instead of forcing full-width buttons.
• Adaptive URL Import: Import URLs now canonicalize per-handler templates, skip novels already in your library, and suppress duplicate links in the same paste batch.
• Collapsible Content Sections: Fight scenes, R18 content, and author notes can be hidden/shown on demand.
• Incognito Mode: Temporarily pause library tracking without disabling the extension.
• Custom Content Box Types: Define your own CSS classes and styling for special content blocks.
• Smart Chunking: Automatically splits large chapters (10 K+ words) to avoid API timeouts, with pause/skip controls.
• Canvas Background Animations: Five animation types (particles, snow, rain, falling leaves, fireflies) for library pages, color-synced to your theme.
• Theme System: Multiple built-in themes (Tokyo Night, Catppuccin Mocha, Synthwave, and more) with auto dark/light scheduling.
• Rolling Backups: Automatic backup rotation (up to 5 snapshots) in browser storage; one-click restore.
• Google Drive Sync: Optional OAuth-based backup to Google Drive with configurable retention, using the canonical web redirect flow.
• True Web PWA Entry: Installable landing web app (Android/Windows supported browsers) with secure extension presence detection and library handoff.
• Customizable Prompts: Per-site and per-novel prompts for enhancement, summarization, and permanent instructions.
• Provider Selection: Switch the active AI provider in popup settings (Gemini, OpenAI-compatible, Ollama) without changing core workflows.
• Multiple Gemini Models: Gemini 2.0 Flash (recommended), 2.5 Flash (fastest), 2.5 Pro (highest quality), with backup key rotation.
• Export Templates: Configurable filename templates for novel copy/download operations.
• FicHub Integration: One-click download button for EPUB/MOBI via FicHub.
• Restore Original: Revert to the original chapter text at any time.
• Dynamic Domain System: Automatically handles subdomains and new site variations via build-time manifest generation.

Installation (Firefox)

From Firefox Add-ons (Recommended):

1. Visit the Firefox Add-ons page
2. Click "Add to Firefox"
3. Confirm the installation when prompted

Latest Version from GitHub Releases (If AMO is pending update):

⚠️ Note: The GitHub Releases page always contains the latest official build. If the Firefox Add-ons store hasn't been updated yet with the newest version, download from GitHub releases.

1. Download: Go to the Releases page and download the latest RanobeGemini_vX.X.X.zip file.
2. Install: Open Firefox, navigate to about:addons, click the gear icon, select "Install Add-on From File...", and choose the downloaded ZIP file.

For Development:

1. Clone the repository: git clone https://github.com/Life-Experimentalist/RanobeGemini.git
2. Open Firefox and navigate to about:debugging#/runtime/this-firefox
3. Click "Load Temporary Add-on..." and select the manifest.json file inside the src directory.

Installation (Edge + Other Browsers)

• Edge (published): https://microsoftedge.microsoft.com/addons/detail/ranobe-gemini/agbhdkiciomjlifhlfbjanpnhhokaimn
• Firefox (published): https://addons.mozilla.org/en-US/firefox/addon/ranobegemini/
• Chrome / Brave / Opera / Vivaldi / Ulaa / Arc: temporary/sideload install from the latest Chromium package.

For the canonical Google Drive OAuth redirect URI setup, use:

• Landing install guide: https://ranobe.vkrishna04.me/install-guide.html

The landing page checks for an installed extension through a safe external ping before showing the direct library button.

Build Instructions (For AMO Reviewers)

Build Environment

• Operating System: Cross-platform (Windows/Linux/macOS compatible)
• Node.js: v14 or higher (tested with Node.js 22 LTS)
• npm: v6 or higher (tested with npm 10)
• Architecture: x64 or ARM64
• Disk Space: ~50MB for dependencies and build

Prerequisites

# Install Node.js and npm (if not already installed)
# Visit https://nodejs.org/ for installation instructions

# Verify installation
node --version
npm --version

Building from Source

# 1. Install dependencies
npm install

# 2. Build the extension
npm run package

Output: releases/RanobeGemini_v4.4.0.zip

Build Process Details

The npm run package command executes:

1. npm run update-domains - Runs dev/generate-manifest-domains.js to extract domains from handler files and update src/manifest.json match patterns
2. npm run archive - Runs dev/package-firefox.js to create a zip archive of the src/ directory

Source Code Verification

The extension is built directly from the src/ directory with:

• No minification - All code remains in readable form
• No obfuscation - Variable and function names are preserved
• No transpilation - Pure JavaScript ES6+ without compilation
• No bundling - Files are packaged as-is without webpack or similar tools

Only processing performed:

• Automatic generation of manifest.json match patterns from handler domain arrays (see dev/generate-manifest-domains.js)

Additional Build Commands

# Generate source code package for submission
npm run package-source

# Update manifest domains without building
npm run update-domains

# Development watch mode
npm run watch

Store Publishing

For release automation, use npm run publish:stores after the build artifacts are ready.

• Publishing is now modular: stores run only when configured.
• Missing credentials are skipped by default (no hard failure).
• Set PUBLISH_STRICT=true to fail when an explicitly enabled store is missing required credentials.

Environment modes per store:

• PUBLISH_FIREFOX=auto|on|off
• PUBLISH_CHROME=auto|on|off
• PUBLISH_EDGE_MANUAL=auto|on|off
• Optional Chromium-manual channels:
  • PUBLISH_BRAVE_MANUAL=on
  • PUBLISH_OPERA_MANUAL=on
  • PUBLISH_VIVALDI_MANUAL=on
  • PUBLISH_ULAA_MANUAL=on
  • PUBLISH_ARC_MANUAL=on

Required credentials:

• Firefox AMO API: AMO_API_KEY, AMO_API_SECRET
• Chrome Web Store API: CWS_CLIENT_ID, CWS_CLIENT_SECRET, CWS_REFRESH_TOKEN, CWS_PUBLISHER_ID, CWS_EXTENSION_ID

Optional Firefox publish extras (not required for standard version submission):

• AMO_METADATA_FILE (when you need to submit metadata payload via web-ext sign)
• AMO_UPLOAD_SOURCE_CODE=true|false (defaults to enabled if a source zip exists)

Edge Add-ons API Credentials (What Key to Use)

Edge Add-ons publishing does not use a single "store key" like AMO. Use Partner Center API credentials:

1. Open Microsoft Partner Center and go to your Edge Add-ons product.
2. Open API access / credentials for the product.
3. Create an app credential set (client app).
4. Save values securely (tenant/app identifiers and secret values provided by Partner Center/Azure setup flow).
5. Keep these in CI secrets only.

Until a stable automated path is enabled in this repo, PUBLISH_EDGE_MANUAL keeps Edge in artifact-assisted manual submission mode.

Usage

1. Configure Provider: Click the Ranobe Gemini icon in your Firefox toolbar. In popup settings, select your AI provider and configure credentials (Gemini API key, OpenAI-compatible key/endpoint, or local Ollama runtime as needed).
2. Navigate: Go to a chapter page on any supported website (Ranobes, FanFiction.net, AO3, or WebNovel).
3. Enhance/Summarize: Click the "Enhance with Gemini" or "Summarize Chapter" buttons that appear near the chapter content.
4. View Results: Wait for the processing to complete. The enhanced text will replace the original, or the summary will appear.
5. Restore: Use the "Restore Original" button if needed.

Configuration

Access the extension's settings via the toolbar icon:

• API Key: Essential for the extension to function.
• AI Provider: Select Gemini, OpenAI-compatible, or Ollama as the active runtime provider.
• Sync Provider: Select the active storage sync backend (Google Drive baseline via activeSync).
• Gemini Model: Select the desired AI model.
• Prompts: Customize the Enhancement, Summary, and Permanent prompts.
• Chunking: Enable/disable automatic splitting of large chapters.
• Debug Mode: Enable console logging for troubleshooting.

Supported Websites

Site	Domains	Notes
Ranobes	ranobes.top, ranobes.net, ranobes.com, ranobes.org, and more	Novel + chapter pages
FanFiction.net	www.fanfiction.net, m.fanfiction.net, fanfiction.ws	Desktop + mobile handlers
Archive of Our Own (AO3)	archiveofourown.org, ao3.org	Work + chapter pages
ScribbleHub	scribblehub.com	Series + chapter pages
WebNovel	webnovel.com	Temporarily disabled — infinite scroll refinement in progress

Architecture & Development

For developers extending or contributing to Ranobe Gemini:

• Architecture Documentation — Detailed system design and modular architecture
• Quick Reference — Index of all systems and where things are located
• Implementation Guide — Metadata fetching and handler settings API
• Build System — Complete build process, scripts, and manifest generation
• Visual Dashboard — Auto-generated Mermaid charts for browser/site support and delivery topology
• Changelog — Full version history

Adding New Website Support

Please refer to the docs/ADDING_NEW_WEBSITES.md guide for instructions on how to extend the extension to support more websites.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read our Code of Conduct and check out the Contributing Guidelines before getting started.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Copyright 2025 VKrishna04

Acknowledgements

• Powered by the Google Gemini API
• EPUB/MOBI downloads via FicHub
• OAuth backup support for Google Drive via the canonical ranobe.vkrishna04.me/oauth-redirect.html flow

---

Project Topics

browser-extension firefox-extension chrome-extension edge-extension gemini-ai web-novel fanfiction archiveofourown ranobes scribblehub reading-tracker novel-library javascript manifest-v3 google-ai ai-enhancement light-novel translation

Stats note: Anonymous aggregate usage counters are powered by CFlair Counter and only run after telemetry consent in the Library.