comic-looms: a userscript reader with thumbnail browsing and gallery downloads

One reader imposed on many gallery sites

Comic Looms is a userscript, which means it runs inside your browser through a script manager extension rather than as a standalone application. Its stated purpose is to provide a unified and practical reader for a set of sites, with download support on top.

The problem it addresses is the inconsistency of the sites themselves. Each gallery has its own layout, its own pagination, and its own idea of what a page looks like, so a reader habit built on one site does not transfer to the next. Comic Looms replaces that per site interface with a common one.

The feature the README puts first is the thumbnail view. A clean list of thumbnails gives an at a glance impression of an entire gallery or of an artist's body of work before you commit to loading full size pages. Clicking any thumbnail starts browsing from that point in the gallery, and the big image viewer offers two modes, pagination and scroll.

The intended user is someone who reads a lot of image galleries and cares about the browsing experience, plus the download capability that comes with it. The repository is TypeScript, MIT licensed, and its topics list names downloader, ehentai, nhentai, pixiv, twitter, userscript, viewer and x.

Site support is a folder of matchers, and new adaptations are not queued

The set of supported sites is defined in code rather than in a setting, and the README points at the matchers directory under src/platform/matchers for the complete list.

The main ones are named in the README: e-hentai.org, exhentai.org and an onion address for exhentai, Twitter/X for user media, lists, the For you feed and Following, pixiv.net for artists' illustrations and manga and for your own homepage, nhentai.net, hitomi.la, gelbooru.com, manhuagui.com, mangacopy.com and copymanga.tv, 18comic.vip and 18comic.org (with the note that this site has no default thumbnails), rule34.xxx, wnacg.com and mycomic.com.

That list is the whole story about maintenance of site support, and it comes with a caveat worth reading twice. The README thanks the users who contributed support for new sites, and then says that given limited time and energy, new adaptation requests will not be actively supported.

So adding a site is possible but not a service the maintainer offers. The repository has a CONTRIBUTING.md for anyone who wants to try it, which tells you the project accepts community adapters even though it will not write them for you. If your browsing depends on a site that is not on the list today, treat that as a blocker rather than a request.

Request throttling: the script slows itself down on purpose

The behaviour that distinguishes Comic Looms from a naive bulk downloader is a rate limit that changes with what you are doing. The README calls this low load pursuit and describes three states.

When the script is enabled but you are not scrolling, big images load at a gentle request rate. While you are browsing, the rate is slightly faster. When you are downloading, the rate increases by the configured number of download threads.

That third clause is the important one, because it means the download speed is a function of a setting you choose, and it is the only state where the script asks a site for more than it needs to draw the page in front of you. Anyone who cares about how much traffic a site receives can reason about the load from these three rules rather than guessing.

The same restraint shows up in the dependency installation step, where the README asks you to check that you can reach jsdelivr.net so the script runs properly. The script manager fetches its dependencies from there at install time, which is a network dependency outside the gallery site itself.

A self hosted userscript also carries the usual question of who the traffic appears to come from. Here the answer is your browser and your connection, so the site's view of it is a normal reader session plus, during downloads, as many parallel requests as you configured threads for. The README does not document a way to change the base rates, only the thread count that adds to them.

Installing the script: script manager, network, then one of two links

The installation requirements are listed as three prerequisites.

A modern browser, with Firefox, Chrome and Edge given as examples. An installed script manager extension, either Violentmonkey or TamperMonkey. And an unobstructed network, because the script manager installs dependencies along with the script and the README asks you to verify that you can access jsdelivr.net.

Then there are two installation links. The first is the GreasyFork listing, and the second is a direct install from the GitHub releases page at comic-looms.user.js. Both give you the same userscript; the difference is where the update notices and version history live.

For mobile, the README notes that the script requires a browser that supports script manager extensions, naming Firefox Android and Kiwi Browser as examples. That constraint decides the platform question for anyone whose only device is a phone: a stock mobile browser with no extension support cannot run this script at all.

The README also states plainly that the full functionality is only guaranteed on recent Firefox and Chromium based browsers with Violentmonkey and TamperMonkey. Anything outside that combination is best effort, which is worth keeping in mind before you commit to a workflow built on the script.

After install: the floating icon, the thumbnail view and the CONF panel

Once the script is active, it marks itself on supported pages with a floating icon in the bottom left corner of gallery pages. That icon is the entry point into the thumbnail display view, where clicking an image begins loading big images from that point onward.

The rest of the interface is organised around a CONF panel. The keyboard section of it lists the available keyboard operations and lets you configure them, which is the feature the README describes as full keyboard operation. Help is another entry in the same panel, and a separate HELP.md file exists in the repository's assets for longer documentation.

The download options follow the same pattern. A gallery can be downloaded in full, or limited to the images you have already viewed, or limited to the images you have selected. The middle option is the one that changes how the tool is used in practice, since it turns a long gallery into an incremental workflow where you browse first and keep only what you actually saw.

The dependency list in package.json explains the mechanics behind the images and the archives. pica is there for image processing, @zip.js/zip.js for building the archive, and file-saver for handing the finished file to the browser as a download.

Building from source with TypeScript and Vite

The development environment is NodeJs and TypeScript, and the build is driven by npm scripts.

# Install dependencies
npm run install
# Regular build; the output is located at `dist/comic-looms.user.js`
npm run build
# The following command is for development; it starts a local server hosting `dist/comic-looms.user.js` and automatically builds when the code changes.
# Visit `http://localhost:8080/dist/comic-looms.user.js` to install the built script.
# `Violentmonkey` is recommended; this script manager supports `Track external edits`, so it can automatically install the changed build.
npm run dev

The regular build writes a single distributable userscript to dist/comic-looms.user.js. The dev command serves that same path from a local server and rebuilds on change, and the README recommends Violentmonkey for the dev loop because it supports tracking external edits and can install the rebuilt script automatically.

There is a small discrepancy worth flagging before you run these. The build script in package.json is tsc && vite build, and the other scripts defined there are test, dev and preview. There is no install script defined in package.json, so the npm run install line in the README does not match a script the project defines; installing dependencies is normally done with npm install, which the README does not spell out. If you follow the README block literally, that first line will fail on the scripts listed in package.json.

The repository also carries a test entry, node --import ./tests/register.mjs --test tests/*.test.mjs, along with a tests directory, a tsconfig.json and a vite.config.ts. The sources live under src, and userscript.meta.ts and userscript.icon.ts sit at the top level, so the emitted userscript's metadata and icon are handled there rather than in a separate template. A flake.nix and flake.lock are present as well, for Nix based tooling.

Limits: browser support, dependency delivery and unreliability by design

The boundaries are documented well enough to plan around. The first is the browser and script manager combination, already noted: recent Firefox or Chromium with Violentmonkey or TamperMonkey for full functionality, and a browser with extension support on mobile.

The second is the dependency host. Because the script manager pulls dependencies from jsdelivr.net when the script is installed, a network that blocks or throttles that domain leaves you with a script that does not run properly. The README treats this as a check you perform before installing, which is an unusually honest prerequisite, since most userscripts would fail silently in the same situation.

The third is site coverage and its direction of travel. New adaptation requests will not be actively supported, so the list of matchers is what you get unless you write one yourself. A site that changes its layout may also break an existing matcher, and there is no versioning scheme described for site adapters that would keep old and new layouts working side by side.

The fourth is a matter of intent rather than defect. The script is built to keep its request rate low, which means a full gallery download is deliberately not fast. For a large gallery on a slow connection, the download thread setting is the knob that decides how long it takes, and pushing it up increases the load the site sees. If your priority is speed, this is the wrong tool, and if your priority is a quiet footprint, the throttle is the feature.

Editorial conclusion

Comic Looms fits readers who browse many gallery sites and want one consistent interface, a thumbnail overview and a choice of what to download, and it is worth trying if you want to see how the request throttling behaves on your own connection before relying on it for bulk archiving. Do not expect it to work on a browser without a userscript manager, on a network that blocks jsdelivr.net, or as a general downloader for sites the matchers do not cover. Before using it, check the terms of the sites you point it at, verify that the CONF panel shows the keyboard and download thread settings you expect, and confirm the script manager combination the README guarantees, namely recent Firefox or Chromium with Violentmonkey or TamperMonkey.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. MapoMagpie/comic-looms on GitHub
4. README
5. Releases