19 kB 108 lines
b2461cb6
nanachi.org
⋯
docs/decisions.md
download raw history
at master Markdown

Decisions #

Active design decisions and their reasons.

Direction #

  • Rust + Slint, one executable. .slint views compile to typed bindings and embedded resources; no runtime assets, no web view. TypeScript and Bun are development tooling only.
  • Copy the game's Mods window and the portal's style. Game screenshots are authoritative for game widgets; typography, geometry, per-cell bevels, states and single-pixel details come from sources or measurements.
  • Personal project, private repo. Game and portal assets are copied freely and credited (docs/game-assets.md); no licensing work. The build and runtime subset is tracked, so a fresh clone builds without a game install.
  • Fidelity is scored, then eyeballed. At 100% scale a surface passes at max channel delta <= 2, or is near at <= 8 with at most 2% of pixels over 2. Text ink boxes are scored separately with a 1 px tolerance. A person's look at the full screen is the final check.

Rendering #

  • Media order: game graphical sets from gui-new.png cut at the target scale and drawn with nine-slice(), then portal border-image PNGs for portal-only widgets, then flat bands measured from a reference. This keeps edges and glows identical to the game.
  • No CSS shadow lists. The software renderer used for captures can't draw them.
  • Fonts: bundled Titillium Web Regular, SemiBold and Bold. Dialog buttons use Bold, ordinary labels Regular.
  • Nine-slice borders are logical pixels (physical divided by scale). Other scales are cut from the 2x atlas rather than resampled from a precut PNG.
  • The window is freely resizable. Reference screenshots don't imply a fixed size.
  • Live rendering uses FemtoVG; captures use an in-process software renderer so they never open a window.

Data and behaviour #

  • Explore reads the portal website. Anonymous search and browse HTML supplies results, counts and relevance; the cached bulk catalogue is the fallback when parsing or filter normalisation fails. Blank Relevance and Downloads use the Downloaded browse route.

  • The mirror supplies zips. Official downloads need a login and are unused.

  • Exact game-line match decides installability. Updates use full release arrays so another line's newer release can't hide an update.

  • One toggle changes one mod. Missing, inactive or unsatisfied required dependencies warn in red with a prefix icon, and both enabled sides of an incompatibility are marked. No cascades; Confirm saves exactly what the user chose.

  • "Install missing" resolves all active required constraints and uses the normal confirmation, even for a single update. Optional dependencies are listed, not installed.

  • Version pins and "Latest" are pending choices saved through Confirm; diagnostics and the local changelog use the selected version, with the portal changelog as fallback.

  • Manage and Updates offer Table, Rows and Grid; Explore offers Rows and Grid. Icons stay visible and the details pane keeps its content in every view. The choice lasts for the session; lists and grid bands stay virtualised.

  • Descriptions mix supported Markdown and inline HTML with readable fallbacks. Description images load on demand from HTTPS DNS hosts, flow at natural size with 4 px gaps and shrink/wrap to fit; refused or failed images become alt-text links. GIF, animated WebP and APNG play in the view while visible, resume their current frame after hiding, and use a shared decoded-frame budget. Linked images open their outer link; plain images open a still of the current frame in the lightbox. The gallery and lightbox must not steal parent scrolling or keyboard focus (docs/portal.md).

  • Dependencies offer exact Explore navigation and installed Manage focus. The second dependency button selects its installed copy in Manage's table, clearing the Manage search and scrolling it into view. Installed Explore details also offer Show in Manage beside Remove. Validated HTTP(S) links open in the system browser; tests inject the opener.

  • Settings choose the data and install folders and the SHA-1 switch (default on). Folder changes need a restart; the switch applies on Save. The catalogue refresh interval is fixed at six hours.

  • External description images (owner, 2026-10-23): this is the sole exception to the portal network allow-list. GET only, existing User-Agent, no cookies, Referer, Authorization, credentials or environment proxy. HTTPS DNS hosts only, port absent or 443; reject userinfo, whitespace, controls, backslashes, IP literals (including alternate numeric forms), single-label names, localhost and its subdomains, *.local and *.internal, and credential parameters (username/token/password, including escaped names). Manually follow at most three redirects, resolving relative Locations and revalidating each destination. 15 s per image, no download size cap; decode limits apply. The deadline spans redirects and reads; a failure caches nothing and the queue continues. Sniff PNG/JPEG/GIF/WebP, ignoring Content-Type. Successful external bytes use disposable cache/description-images/; portal-host images retain cache/portal-thumbs/. Clear cache removes these and other known disposable entries, preserving settings/metadata even if roots overlap. Failures stay in memory until restart or explicit Clear cache. Ureq 3.4's resolver hook is explicitly unversioned, so resolve-time private-address blocking is not installed: a valid public-looking DNS name may resolve privately.

  • Description decoding: maximum 4096 px per side and 16,000,000 pixels per frame; 500 frames and 64 MiB retained RGBA per animation, otherwise the first frame. Delays at or below 10 ms become 100 ms. The shared retained-frame budget is 256 MiB, including still frames; least recently shown animations release their later frames through shared models. If even a new first frame cannot fit, that image fails with its alt-text link. Decoder working buffers and encoded HTTP bytes are temporary, separate from retained frames. Timers pause outside the viewport, under another tab/changelog and while minimized; only a small view-owned playhead model changes each frame.

Writes and recovery #

  • Install and update are one serialised batch: dependency-first validated plans, no-overwrite moves, staleness and path checks, action-specific running-game guards repeated before each effect, and rollback with recovery paths on failure. There is no crash journal.
  • Owner revision, 2026-10-21: new mod installs never write mod-list.json, create a list backup or auto-enable a saved entry. They may run while Factorio runs and are independent of list staleness. Factorio's default for an unlisted installed mod is enabled; the app displays that state and allows an explicit pending disable. Downloads and removals keep unrelated unsaved toggles/pins through rescans; removed mods lose their pending choices. A small floppy button saves pending choices without quitting, with the same guarded atomic save as Save and quit.
  • Pending Manage rows: unsaved enable/disable or pin choices and installed mods absent from mod-list.json use gui_color.blue (#80CEF0) name/version text and a thin blue_slot_glow_color (#22B5FF, alpha 128) left accent in Table, Rows and Grid. Values are verified from the read-only Factorio 2.0.77 data/core/prototypes/style.lua declarations. Disabled pending text dims the blue; orange selection retains native black text and keeps the blue accent. Save records every installed mod with its displayed state, clearing both kinds of pending state. Unlisted pending state alone makes the save-only button available; Undo discards drafts but leaves unlisted pending state.
  • Running-game removal: use saved state, not pending UI state. Refuse only listed, saved-enabled mods. Allow unlisted and saved-disabled mods into the Recycle Bin/Trash without writing the list while the game runs; retain any disabled entries. Absence from the saved list is the complete unlisted rule; no file-age or process-start checks apply. Stopped-game removal still removes list entries. Updates replacing any existing version retain the running-game guard, backup/rollback and pin advancement. New installs remain successful if a separate update's list commit fails. Temporary-part cleanup remains guarded; skipping it while the game runs must not block new installs.
  • Disabling verification keeps completeness checks: size, zip entries and CRCs, info.json identity, and the temp's second digest and size check before promotion.
  • Cache cleanup never touches durable data. Settings and installed-mod metadata survive it. Metadata records never expire; metadata errors never reverse a successful install.

Dependencies and network #

  • Direct crates are those in the Cargo manifests: Slint and slint-build 1.18.1, serde, serde_json, zip, png, image (explicit GIF, PNG, JPEG and WebP features; enables the existing transitive image-webp crate without pulling the AV1 encoder), sha1, ureq with rustls, and winresource for the Windows icon. Tooling uses fflate, wasmoon, TypeScript and Bun types. New dependencies need a decision here first.
  • HTTP is allow-listed, anonymous, cookie-free and redirect-free, except description images (see Descriptions above: any HTTPS DNS host, up to three checked redirects). The bulk catalogue refreshes at most every six hours and /full is cached for 24 hours. No publishing or upload endpoints.
  • Credentials are off limits until a login feature defines secure storage. The app never reads player-data.json.
  • Prior art: the debounce, stale-result and streamed-download ideas credit vaibhavvikas/factorio-mod-downloader; no code is vendored.

Linux (M7, owner approved 2026-10-20) #

  • Linux-only dependencies: trash 5.2.9 (default features disabled, chrono enabled for deletion timestamps) implements freedesktop Trash 1.0; rustix 1.1 with fs/process provides kernel no-replace moves and user identity checks. Windows uses its existing Win32 code. See trash implementation and rustix renameat_with. Lockfile pins exact resolutions.

  • XDG split: absolute XDG config/data/cache bases (falling back to absolute HOME) hold settings, durable metadata and disposable cache respectively, under werry/factoriomodmanager; metadata adds metadata/. Independent FMM_*_DIR overrides remain. No credentials or automatic migration.

  • Moves: renameat2(RENAME_NOREPLACE) for backup, promotion, demotion and restore. Existing destinations, EXDEV and unsupported filesystems return errors; no overwrite/copy fallback.

  • Process guard fails open: /proc/<pid>/comm, then cmdline argv0 basename, detect factorio and factorio.exe. Per-process access/exit errors are normal; a broken process table logs a warning and reports not running. This intentionally favors usable operations in hardened/container environments.

  • Browser and packaging: validated HTTP(S) URLs go to xdg-open as one argument, reaped on a worker thread. Personal-use local-source Arch packaging first; AppImage, Flatpak manager distribution, macOS and Windows runtime regression verification are deferred.

  • Trash backend boundary (owner feedback, 2026-10-20): call trash::delete and let freedesktop selection use home or volume Trash, including KDE-owned mode-0755 folders. No app chmod/creation, ownership policy, mount-table or device pre-refusal. Source-reviewed 5.2.9 move_items_no_replace does copy+remove on EXDEV: vendor the MIT crate with only that fallback replaced by the rename error (and remove its unused copy helper). This protects folder mods without refusing normal per-volume Trash. Keep the cheap relative-XDG guard. Metadata precedes the move; failure preserves source bytes (an empty placeholder may remain). Record removals only after success. Report manual Trash recovery separately from actual failed rollback moves. Windows retains Recycle Bin wording/implementation. Tests use isolated child HOME/XDG and accept KDE 0755; no real Trash enumeration or emptying.

  • Configuration boundary: supported macros are __PATH__executable__ (install/bin/x64), __PATH__system-read-data__ (install/data) and __PATH__system-write-data__ (native ~/.factorio, Flatpak sandbox ~/.factorio, or install for the portable flag). Executable macro paths normalize .. lexically. Literal relative paths and unknown macros are diagnosed and require an absolute Settings choice; they are never guessed into writable locations.

  • Linux pointer fixes (2026-10-20): scrollbar strips are siblings of their viewports, so explicitly forward unrounded vertical wheel deltas to the same bounded content position. Slint 1.18.1 already handles TouchArea up/cancel; do not introduce a hover latch. Native Linux title movement starts once on left press; no move-time calls or release-dependent state. A second nearby press within 400 ms maximizes/restores even when the compositor consumed release. Windows retains its motion threshold and double-click path. Resize remains Slint/winit's native resize-border-width path; no app resize loop or position writes.

macOS (owner approved 2026-10-25) #

  • Dependencies: the Linux trash 5.2.9 (vendored) and rustix 1.1 dependencies extend to macOS. Their macOS paths resolve only crates already in Cargo.lock (objc2 0.6 / objc2-foundation 0.3 through winit), so the lockfile is unchanged. libproc is linked directly from the system; no process is spawned for the guard.
  • App-owned paths: settings and metadata/ under ~/Library/Application Support/werry/factoriomodmanager/, and disposable cache under ~/Library/Caches/werry/factoriomodmanager/. HOME and FMM_*_DIR overrides must be absolute. No migration.
  • Trash: the crate's default NSFileManager trashItemAtURL backend: synchronous, no Automation prompt, item's volume Trash, no delete fallback. Finder AppleScript ("Put Back", Finder sound) was rejected because it needs a permission prompt and a running Finder.
  • Moves and guard: renameatx_np(RENAME_EXCL) through rustix's RenameFlags::NOREPLACE; there's no copy fallback. The running guard matches factorio/factorio.exe against libproc proc_name and proc_pidpath basenames and fails open with a warning like Linux.
  • Discovery: the game root is factorio.app/Contents (Steam steamapps/common/Factorio/, /Applications, ~/Applications). Settings and FACTORIO_DIR accept the bundle or its parent folder and save the resolved Contents path. Title-bar moves start on press like Linux (performWindowDrag needs the mouse-down event and its loop consumes the release), with the same second-press maximize; the Windows motion-threshold path briefly showed a resize cursor. The crate's default macOS Trash method is Finder AppleScript, so the app sets NsFileManager explicitly (tested).

Outside mods-folder changes (owner approved 2026-10-25) #

notify =8.2.1 (CC0-1.0; default macos_fsevent) watches mods/ non-recursively: FSEvents on macOS, inotify on Linux, ReadDirectoryChangesW on Windows. New lock entries are notify, notify-types (MIT OR Apache-2.0), objc2-core-services (Zlib OR Apache-2.0 OR MIT), inotify/inotify-sys (ISC), and BSD-only kqueue/kqueue-sys/mio (MIT) that no supported target builds. The 9.0 line was a release candidate. A 2 s stat poll and focus-only checks were rejected for latency and missed changes. Only top-level entries count; dotfiles, folder-mod contents, .fmm-part downloads and the list's .tmp/.bak siblings are ignored. Bursts settle for 400 ms. Rescans read only and run on a worker; while an operation is planned or running they wait until it's idle, and a result that arrives after an operation started is dropped and retried. The adoption path is the post-operation one: still-valid pending toggles, pins and selection survive, and cleared pins are reported. Captures start no watcher.

Release packaging (owner approved 2026-10-25) #

Releases are built on the owner's macOS machine. Linux runs on a LAN host over SSH because AMD Hackintoshes can't run a hypervisor. GitHub Actions through a private mirror stays an option if macOS access is lost. macOS ships one universal DMG, ad-hoc signed and not notarized. Windows ships one .exe cross-compiled with cargo-xwin (Microsoft CRT/SDK license accepted by the owner) in an Ubuntu 24.04 container on the Linux host: compiling Homebrew LLVM on the Intel Hackintosh took over an hour, and LLVM ships only Apple-silicon macOS binaries. Woodpecker or Forgejo CI was considered, but rejected for now: it needs a public webhook endpoint behind CGNAT, and a Mac agent that isn't reliably booted, since the owner dual-boots. Linux ships an AppImage and an Arch -bin package, both built on Ubuntu 22.04 (glibc 2.35) for compatibility; the plain tarball was dropped. Build-only downloads are pinned: Rust 1.99.1 in the container, appimagetool 1.9.1 and type2-runtime 20251108 by SHA-256. The AppImage bundles no system libraries, to avoid mismatched graphics/font stacks. .cargo/config.toml links the MSVC C runtime statically (+crt-static) for native and cross builds, so the .exe needs no Visual C++ Redistributable; collation still uses Windows' built-in ICU (icuin.dll, Windows 10 1703+). The AUR is a possible follow-up; agents create no AUR account or push. The owner runs tools/release.ts personally, including pushes and uploads.

R9 UI audio (owner approved, 2026-10-20) #

Use Rodio 0.23.0 with defaults disabled and only playback + lewton. Rodio and Lewton 0.10.2 are MIT OR Apache-2.0; transitive Ogg 0.8 is BSD-3-Clause and CPAL 0.18.2 is Apache-2.0. CPAL remains transitive: no direct dependency, bridge enumeration, optional backends or device selection. Open Rodio's default output on every platform. Linux links ALSA (alsa-lib runtime, ALSA headers/pkg-config for builds); the owner's default ALSA route supplies PipeWire. Windows uses the default WASAPI route. No native playback/latency or mute fidelity is claimed until owner listening tests.

Embed only the used Wube/Factorio 2.0.77 Vorbis clips, extracted read-only by the asset tool and inventoried with source, gain and SHA-256. Predecode once on a worker, submit through a bounded nonblocking queue, cap overlapping voices and stop voices on mute. Missing/corrupt clips and unavailable/disconnected output are silent with capped diagnostics. Tests/captures never open a device. No audio cache or new write paths. Sounds default on at 50%; Settings previews immediately, Save persists existing atomic settings, Cancel/Escape restores runtime values. The slider is disabled while off and retains its value. Rodio avoids owning a second mixing/resampling implementation; Lewton avoids unused codec defaults.

Feature-tree inspection on Linux and for x86_64-pc-windows-msvc resolves only Rodio playback/Lewton, with ALSA on Linux and Windows audio APIs on Windows. No Symphonia, ASIO, JACK, native PipeWire/PulseAudio or recording feature is enabled. Added transitive package versions/licenses (including other target lock entries) are inventoried in docs/reference/audio-dependencies.txt. Linux ldd confirms libasound.so.2; Windows native build/playback remains unverified here.