DictShelf (1)

Queries the selected dictionaries concurrently and streams one line per dictionary as it finishes. Lines arrive in completion order, never in slot order: each hit carries i, its index in the begin line's slots array.

A dictionary that fails, that cannot serve the requested mode, or whose index is not ready reports that on its own line. None of those is a request failure, and the other dictionaries still answer.

A search runs until it finishes or the reader stops it: there is no clock on it.

Answers 204 with the extension grant. The extension's own requests are CORS-simple and never preflight; this exists so a future one does not meet a 405 that explains nothing.

With progress=1, checking events report how many dictionary files have been checked before row resolution begins. Then begin carries the total from registry ids, and dict rows follow in completion order.

end carries etag when the answer may be kept. Send it back as If-None-Match and an unchanged list is a 304 with no body, decided without opening any dictionary. There is no ETag header: whether an answer may be kept is known only after its last row.

Images, stylesheets, scripts and audio, as the article references them.

path is the whole remainder of the URL and may contain slashes, which an OpenAPI path parameter cannot express: send it unencoded, exactly as the article asks for it.

Speex audio is transcoded to WAV and answered as audio/wav. A .spx that cannot be transcoded, or one supplied in a res/ override folder, is answered raw as audio/ogg. Files from a res/ folder are served uncached, so an edit takes effect on reload.

The contract of the running build, served by it.

Requires local access or ALLOW_REMOTE_DELETE. Source dictionaries and their resources are preserved. Index rebuilds atomically replace the main index, retaining optional indexes unless selected for removal. Obsolete cleanup includes unused prepared folders regardless of keep markers, duplicates, incomplete indexes, abandoned ingest files and packed media. Obsolete active indexes are refreshed from their sources. Database dictionaries supplied as sources are never cleared.

New dictionaries receive a main index and only the selected optional indexes, respecting configured DSL variants. Existing optional indexes are updated only when already present; deletion cancels pending creation. Keep preserves existing feature presence. Cleanup always removes unused or disabled prepared indexes and legacy packed media. Sources survive.

Stop is cooperative. The active dictionary reaches a consistent state, then unstarted dictionaries are skipped and cleanup and registry refresh finish.

With status=1, returns live progress for the server-owned index job. Otherwise reads the dictionary folders again, warms the registry, and answers exactly as /api/dicts does. Removes unused prepared folders (including previously kept caches), abandoned indexes and packed media. Source files and both discovered DSL variants are preserved. Requires removal permission, like POST /api/clear-database.

Copies the built-in guide (wudict-howto.wudict.md and its wudict-howto.wudict.files/) into the folder imports go to - the first dictionary folder - then rescans. The copy is listed in place of the built-in guide. An existing copy is never overwritten. With restore=1 it instead brings the built-in guide back after the user removed it (DELETE /api/library?dict=wudict-howto, which records the removal so it is not written back at the next start).

Brings one dictionary to the feature state you ask for, streaming Server-Sent Events:

event: progress   data: {"done":N,"total":M}
event: done       data: {…a /api/dicts row…}
event: error      data: {"error":"…"}

Each switch is a state, not a verb: a parameter you leave out keeps whatever that feature is now, so toggling one thing cannot strip another, and a request naming none prepares an unprepared dictionary with its headword index only. Progress is emitted at most every 200 ms.

The change runs as the dictionary's job on the server, not inside the request: a client that disconnects loses only the stream, and the work goes on. While a change to a dictionary runs, its /api/dicts row carries job, and a request for that dictionary follows the running change instead of starting another - what it asked for is not queued, and the done it receives carries what the dictionary now has.

Everything in the library folder, whether or not it is currently enrolled. Listing is not consent: reading this never adds anything to the registry.

Removes the prepared folder, the original files, or both. Both default to on, which is "remove this dictionary".

Irreversible. Files are unlinked, not moved to a Trash or Recycle Bin, and nothing here can be undone.

From the machine running DictShelf this is always allowed - it is your library and your disk. From a browser on another machine it follows ALLOW_REMOTE_DELETE (default off); with that off, the remote caller gets a 403 and canDelete: false in GET /api/config.

Every prepared folder in the library whose recorded source file is no longer on disk, whatever the reason (deleted, renamed, on a drive that is not connected), except those kept on purpose. A source that was only moved inside a dictionary folder is not listed: a rescan re-links the folder to it. The built-in guide is never listed.

Deletes the prepared folders named in delete and marks those in keep as standalone (keep = standalone in the folder's info.txt), after which they are never listed again. Folders are named by Orphan.folder, never by path, and each is checked again when it is acted on: one that is no longer an orphan is reported under failed. A folder named twice, or in both lists, fails too. Body is capped at 1 MiB.

Deleting is irreversible. Files are unlinked, not moved to a Trash or Recycle Bin. Allowed on the machine running DictShelf; from another machine only with ALLOW_REMOTE_DELETE, which also governs keep.

One row per language, merging the published catalogue (LEMMA_URL) with what is present in LEMMA_DIR, plus the state of any download running right now. Always answers 200: what is installed is the half of the answer that needs no network, and an unreachable catalogue is reported in error rather than by failing.

Starts a download and returns at once; follow it with GET /api/lemmas. The download runs in the server, not in this request, so it survives the page being reloaded, closed, or rotated away on Android.

The catalogue is never taken from the caller: only the configured LEMMA_URL is fetched. A second call for a language already downloading joins the running download instead of starting another.

On success the language is searchable immediately - no restart, because the lemma folder is re-indexed in place.

Removes every file in LEMMA_DIR supplying this language, not only the one in use, and re-indexes the folder. Deleting English falls back to the pack compiled into the binary rather than losing the language. Unlike dictionary removal this is offered on every platform: these are files DictShelf downloaded, not files the user brought.

Two acts on one route. Without confirm it ACQUIRES an archive and reports the dictionaries inside it, decompressing nothing: a zip is answered from its central directory and a 7z from its header, so listing a multi-gigabyte bundle costs a seek. With confirm it extracts the ones the caller chose.

A plain dictionary file is read too - an .mdx, an .ifo, a .dsl, a .slob, a .bgl - and so are the companions lying beside it in the same folder, because that is the same grouping rule the library uses. Nothing is unpacked in that case; the files are copied into place.

.zip and .7z are read. A 7z is decoded strictly in archive order on one goroutine: a 7z folder is a single stream holding several files end to end, so that order is the difference between reading it once and decompressing it again per file. A password-protected archive is refused rather than half-read.

The archive arrives either as a path already on disk (path, used by the Android shell, which hands over a download without copying it) or as the request body. A streamed body is spooled inside the destination folder, never into the temporary directory: on Android that is a small cache partition, and on every platform it is a different filesystem, which would make the install a second full copy instead of a rename.

One import runs at a time, everywhere. Extraction outlives this request and is followed with GET /api/intake, for the same reason a lemma download is: on Android the page dies whenever the device rotates.

A url is fetched by the server instead, which is how a phone imports: the shell has no networking of its own, and a download that lived in the page would die with it. It answers 202 at once and downloads behind the same poll, sniffing when it lands. Any site, unless IMPORT_URL_HOSTS restricts it; https only and no address on the local network, unless IMPORT_INSECURE lifts both; an unfinished download is resumed by the next attempt.

A url may also name SEVERAL dictionaries: a web folder page (every link on it to a dictionary, a companion or an archive), a .txt list (one file name or link per line, the first # line its title), or several links pasted at once - and a share link https://legbehindneck.com/wudict#<link> stands for the link after # (#/dict/x/ is short for a path on that site), or for several links after # separated by commas. A Google Drive file link (drive.google.com/file/d/<id>/view) is fetched from Drive's download address, and named by Drive's answer. Such a job is a collection: ready arrives with nothing downloaded, one candidate per dictionary sized and dated from the site's own headers, and each dictionary's media offered in extras. Confirming downloads and installs each chosen dictionary in turn; one that fails is named in error and the job still ends done with the rest installed.

A dictionary the library already holds is reported as such on the candidate (existing, or elsewhere for one in another configured folder; unchanged when the files are the same) and, when the caller picks it, is REPLACED - its folder, or its files in place - rather than installed a second time. Not picking it is skipping it. Nothing is ever installed or downloaded under a numbered name.

A downloaded plain file has its companions LOOKED FOR at the sibling URLs the format tables name - oxford.mdd, oxford.1.mdd, and so on, stopping at the first that is not there. What is found is reported in extras and downloaded only when the caller asks for it by index: a companion can be several hundred megabytes of somebody's phone data, so it is offered on the screen that asks which dictionaries to install and never taken on the strength of the probe.

The source file's fate follows IMPORT_KEEP; keep answers it only when that is ask. A FAILED import always keeps the source, which is policy and not a setting - deleting somebody's only copy after an import that did not work cannot be undone.

The poll. Always 200: an empty state means nothing is happening, which is an answer the page acts on and must not have to tell apart from a request that did not arrive. done and total are bytes.

Stops an extraction and forgets a sniffed archive that was never confirmed. Everything staged is removed; dictionaries already renamed into the library stay, because they are whole. Always 200 - cancelling nothing is not a failure. With id, only that job is cancelled, and only while it is still the current one: a client releasing its own job never cancels one another client started since. A download that nobody has confirmed and nobody has polled for 75 seconds is not "running" any more: a new import replaces it instead of being refused. A confirmed import is never replaced.

Rebuilds each dictionary /api/dicts reports as outdated - prepared by an older build, from a source edited since, or unreadable by this one - with the indexes it already has. A packed media.db the rebuild leaves unpaired is packed again. Dictionaries that are current are not touched, and one whose original files are gone is never outdated, since nothing can rebuild it.

Never started by the server itself: on a large library this is hours of work, so an upgrade only marks the library outdated and waits for this request. It runs in the background indexing lane, one dictionary at a time, and outlives the request; follow it with GET /api/reindex. One job at a time: while one runs, this answers its status instead of starting another.

The poll. Always 200; running: false with total: 0 means no rebuild has run in this process.

Stops the job after the dictionary it is rebuilding now. What is finished stays finished; each rebuild replaces the old data only when it completes, so nothing is left half-built. Always 200.

Drives the first-run page. Without save it only reports what the folder holds, which is what live typing needs. With save=1 it switches the registry over and writes DICT_DIR. Repeat path for several folders; found is then the deduplicated total across all of them, because overlapping folders must not be counted twice. Saving runs as a server-owned job and survives closing the page. With async=1, poll /api/index-work?id=folder-setup for progress and the retained result. migration=status reports an optional Windows first-run import choice; migration=import|copy|move applies that choice before folders are saved.

What the panel's folders section shows, including which layer set DICT_DIR - so the page can say that saving will not take effect, rather than silently doing nothing.

Defaults to System, which follows the requesting app or browser's preferred language when supported (English or Russian), then falls back to English. An explicit English or Russian choice overrides it. Dictionary languages are unchanged.

Saves System, English or Russian. System follows the requesting app or browser's preferred language. Reload the page to apply.

Healed against the dictionaries that exist right now. exists is false on a first run, which is the client's cue to adopt what an older build left in localStorage, once, instead of starting the user over.

Array order is the user's order. Entries record the path as well as the id, because ids are derived from the path: moving a dictionary folder changes every id at once, and the path is what re-attaches the state instead of resetting it. Body is capped at 1 MiB.

Index is always enabled. Existing dictionaries are not changed. Pending preparation plans survive restart. GET /api/config returns these defaults as indexDefaults.

Two CSS files the user owns, applied to everything DictShelf renders. app styles the page itself - its colours, its own layout - and its :root custom properties reach articles too, because they inherit across the shadow boundary. article styles what dictionaries render, in both article flavours (shadow root and sandboxed iframe).

The split is what keeps body{}, p{} and a{} - written with articles in mind - from also restyling the chrome.

dir is where the two files live on disk, beside the wudict.toml in effect, so they can be edited with an ordinary text editor as well; writable is false when there is no config directory at all, and the editor says so instead of failing to save.

Omit a field to leave that file untouched: absent and empty are different, and the App tab and the Article tab are one editor sending different bodies. An empty string REMOVES the file, so "I cleared the box" and "there is a file here containing nothing" do not become two states that behave the same but read differently.

Each file is capped at 256 KiB. A stylesheet that hides the app can be stepped around with GET /?style=off, which omits it.

groups.ini, beside the dictshelf.toml in effect: a [Section] line is a "Group by" heading (at most 32, names of at most 64 bytes), and Name = text, text a group under it that a dictionary joins when one of the texts (at least 2 characters) is anywhere in its title or file name, in any case. An item between backticks is a regular expression (Go RE2, case-insensitive), read verbatim and tested against the title and the file name separately. ; and # start a comment outside backticks. A group line before any section belongs to [My groups]. While there is no file the built-in list is in effect (custom false); once saved, the file is the whole list.

Ids are the names, trimmed and lower-cased: a dictionary row's groups[].f and groups[].v (GET /api/dicts) are exactly these. problems lists the lines and items that were skipped (an invalid regular expression, a line with no =, a one-character item, more than 500 regular expressions); the rest of the file still applies. At most 100 are listed: a last entry with more stands for the rest. text and msg are clipped to 200 bytes. unusable means the file exists but could not be read: the built-in list is in effect, and problems has one entry, with no line, saying why.

The body is the whole file, as text. Lines that do not parse are reported in problems, never refused. A body identical to the built-in list removes the file instead, so an unchanged copy does not stop the list from following the built-in one. Capped at 256 KiB. While the current file is unusable, a save is refused unless replace=1 is given: the file is the user's, and the editor could not show it.

Removes groups.ini; the built-in list is in effect again.

The presets the Appearance sheet offers as ready-made layers: a background look, palettes, layout and text tweaks, article roles. Each preset carries its CSS inline (app and/or article, the two scopes a stylesheet can reach), because the page composes the article layer itself and must not fetch preset files one by one.

The groups are the conflict model: presets inside one group claim the same surfaces, so at most ONE of them can be enabled - enabling one switches its group-mates off, radio-style. A preset that conflicts with nothing lives in a group of its own and behaves as a plain toggle. writable is false when there is no config directory, and the pane says so instead of offering switches that cannot stick.

Switching a preset on inside a conflict group switches its group-mates off; the fresh state comes back, so a client never has to guess what the radio rule did. The choice is remembered in the config folder beside the stylesheets it composes with.

A look is the whole Appearance sheet under a name: the article's size and weight, which built-in preset layers are on, the window's colour and wallpaper per theme, what the screen margins and the bars do, and the reader's own stylesheets. Three ship with the app - Clean, Sepia and Old paper - and the reader can save their own beside them.

Only names are listed. A look's state is the server's to read - the four stylesheets it speaks for are files, not fields a menu needs - and current is the look in force, empty when none has been applied yet. writable is false when there is no config directory, and the row says so instead of offering a list that cannot stick.

The state is assembled by the server: the settings and the four stylesheets it owns, plus the shell's half as the client sends it - the backdrop of each theme, the margin mode and colour, the bar mask. A client with no shell (a browser) simply omits shell, and the look it saves is a look with no backdrop.

The new look becomes the one in force, because it IS what is in force.