Omniscio

Portable startup splash

The two invisible phases before the real Omniscio window appears — the portable .exe's extraction phase and the app's own boot phase — and how the startup splash makes both visible: the static extraction image, the boot splash with its logo, spinner, phase checklist and live status line, and the kill switches that suppress it.

On this page

What it is

When you double-click Omniscio-Portable-<VERSION>.exe — the single-file build a local snapshot build produces; a public release ships the installer instead, see "The portable build (and what a release ships)" below — two invisible phases happen before the real Omniscio window appears. The startup splash makes both of them visible so you can tell the app is doing work — not frozen. (The instant-launch zip build skips Phase A entirely — see the same section — so it only ever shows the Phase-B boot splash.)

  1. Extraction phase (tens of seconds, EVERY launch — varies by disk). The portable .exe is a self-extracting bundle from electron-builder. The ~340 MB compressed .exe unpacks its full ~1.6 GB payload (Electron runtime + Omniscio code + bundled models) into a temp directory before any of Omniscio's own code runs. This is not a one-time first-launch cost — the NSIS portable wrapper (portable.nsi) does an unconditional RMDir /r + re-extract on every launch and deletes the temp copy again on exit, so the full unpack happens each time you double-click the .exe. (This is the entire reason the instant-launch zip exists — see "Two distribution formats" below.) During this phase Omniscio has not started yet, so no Omniscio window can possibly appear — only electron-builder's built-in portable wrapper can show anything. We give it a static build/splash.bmp (400×220, 24-bit, dark theme, brand-matched: title "Omniscio" with an indigo accent rule, then "Unpacking files, please wait" and "The app will open automatically") via the portable.splashImage field in package.json. It deliberately has no animation, no spinner, no dots — the wrapper can only paint one static image, so anything that looks like a loader (we previously used three dots) reads as frozen/broken; a static accent rule reads as an intentional design element. It MUST be a .bmp — the NSIS portable template (portable.nsi) copies the file to $PLUGINSDIR\splash.bmp and loads it with the BgImage plugin, which decodes only real BMP data. A PNG (even one renamed .bmp) fails to load and the extraction splash silently shows nothing, with no build error. It pops up on the user's primary monitor, stays until the wrapper hands off to Electron, then vanishes — no spinner, no status text, no elapsed counter, because the wrapper is a C++ stub that can only display a single image.
  2. Boot phase (~2–10 s, varies by SQLite + auth init). Once Electron starts, Omniscio's own main process runs through its startup pipeline: load config.json, open mission-control.db, replay crash recovery, refresh auth tokens, create the main window. The main window stays hidden until ready-to-show fires, so without intervention the user would stare at an empty desktop for several more seconds. The boot splash is a small frameless BrowserWindow (300×470, dark theme, its text filling the card edge to edge, indigo spinner — it grows taller only while the rare "Skip" control is showing) that opens as the very first thing inside app.whenReady() — before database init, auth, recovery, or main-window creation. The boot sequence then waits (briefly, capped) for the splash to actually paint before running that blocking work: the DB / migrations / reconcile / recovery passes are synchronous and hold the main thread, and the splash's own ready-to-show→.show() is itself a main-thread task — so without this wait the splash couldn't appear until boot was nearly done (the "splash shows up ~60 s in" bug on a large database). It shows:
    • Logo: the Omniscio tower-badge logo (the hi-res master, downsized to 240×240 and embedded inline as a base64 data: image) sits above the title so the boot window is brand-matched to the rest of Omniscio. If the logo asset is ever missing or unreadable the splash still renders — just without the image (see the fail-safe note under "Why it works this way").
    • Title: "OMNISCIO" in the brand wordmark gradient (the aurora stops from src/shared/brand-wordmark.ts — the card is dark in every theme), with the same thin aurora rule the inbox's "All clear" shows under its title. The rule is drawn outside the layout, so it adds no height to the fixed-size card.
    • Spinner: 17-px indigo ring rotating at 0.8 s/turn, riding inline at the start of the step line
    • Everything reads centred: the checklist is one block centred under the title (its rows stay left-aligned so the icons line up, and each label reserves its bold width so the block never shifts when a row turns active); the step line and the quieter reassurance line beneath it are centred text, whether they fit on one row or wrap onto two. The step line uses fixed-width digits so a ticking "Backing up database... NN%" does not wobble.
    • Phase checklist: five boot phases — Loading settings → Preparing your data → Restoring your work → Signing in → Opening the app — each a row showing ✓ when done, a pulsing ● while active, or ○ until reached. The checklist only ever moves forward, so a conditional/skipped step (disk compaction, or recovery when there's nothing to recover) auto-completes the instant a later phase lights up. A row is named for the whole phase, never for one step inside it, because the row is what you read for as long as any of its steps runs — "Preparing your data" covers the database work and the project-storage tidy-up that ends that phase.
    • Step line: live text naming the specific sub-step inside the active phase — "Reading your preferences...", "Opening your database...", "Applying the latest updates...", "Restoring previous sessions...", "Signing you in...", "Almost ready...". During database upgrades it shows a live "Applying update N of M..." counter (pushed free-form from the ledger migration runner) so a long migration run visibly progresses instead of sitting on one frozen line. An unmapped kebab-case codename (e.g. contextdock-preload-start, fired late on a slow boot while the splash is still up) is suppressed — it resolves to nothing so the splash keeps the last real step rather than leaking an internal slug, while a free-form string (the live "Backing up database... NN%") passes through verbatim; either way the current phase is kept, so a new milestone never blanks the line. Nothing but a real progress push can write this line — not even the reassurance below it.
    • "Still working" reassurance: a second, quieter line beneath the step line, and the only thing the splash's own clock is allowed to write. Because the splash is its OWN window with its OWN clock it keeps moving even when the main process is blocked solid on a single long step (a slow migration, a silent git-storage compaction, the 60 s+ renderer warm-up): once the current step has been quiet past a threshold, this line escalates a reassuring message — "Still working — this can take a little while..." → "Still working — larger projects can take several minutes..." → "Still working — a large project can take up to 45 minutes. You can stop it at any time..." during the data phase, or "Still working — this usually only takes a moment..." → "Still working — larger projects take a bit longer..." → "Still working — thanks for your patience..." during the long "Opening the app" tail — so a long wait never looks frozen. Every message describes the WAIT and never the work: the step line already names the work, and a message that guesses at it is a message that can name the wrong job. A real status push clears this line and resets its clock, so it never sits beside a newer step, and an ordinary boot shows one line only.

The boot splash closes the instant the main window's ready-to-show event fires (which is exactly when Omniscio's UI becomes interactive). There's a brief overlap — splash still up, main window starting to paint — which prevents a black-screen flicker between the two.

Where to find it

You don't. It's purely a startup affordance — there is nothing in the app that opens it, and no menu, panel or shortcut reaches it. The splash shows itself.

There is no Settings toggle for the boot splash. It only ever shows for ~2–10 s during startup, then closes itself. A user-facing toggle would do nothing useful 99.99% of the time.

How it behaves

The portable build (and what a release ships)

A public release ships one Windows download: the NSIS installer (Omniscio-Installer-<VER>.exe, with Omniscio-Setup-<VER>.exe alongside it), covered in windows-installer.md. The release workflow overrides the Windows target to the installer only (.github/workflows/release.yml, -c.win.target=nsis), so neither a portable .exe nor an (unzip-and-run).zip is published — the pages that used to promise them were wrong.

package.json still declares all three Windows targets (build.win.target: ["nsis", "portable", "zip"]) because the local snapshot build (scripts/build-snapshot.mjs, driven by the build-amc-snapshot skill) packages them for trying out a commit: it writes the portable .exe, the zip and the unpacked folder into a timestamped dist/ directory, and its --exe-only mode produces just the portable .exe. Those two formats are therefore local build artifacts, not release downloads:

  • Omniscio-Portable-<VER>.exe — the single-file self-extractor described above. Double-click and it runs; nothing to unzip. The cost is the extraction phase: it re-unpacks its ~1.6 GB payload to TEMP on every launch, so startup is slow and you see the static "Unpacking files" splash each time. Best for handing Omniscio to someone as one foolproof file.
  • Omniscio-<VER>-unzip-and-run.zip — a zip of the already-unpacked app folder (the same files electron-builder writes to dist/win-unpacked). Extract it once to a folder, then run Omniscio.exe inside. There is no extraction phase and no Phase-A splash — Electron starts immediately, so you go straight to the Phase-B boot splash. Best for daily use.

The zip's filename comes from build.win.artifactName; the .exe's comes from the more-specific build.portable.artifactName override. Neither format auto-updates (electron-updater is disabled for portable distributions) — a new version is a fresh build that replaces the old one.

Why it works this way

  • Two phases, two technologies. Phase A (extraction) is a static .bmp because the wrapper is a C++ self-extracting stub with no scripting surface — and the NSIS BgImage plugin it uses to paint the splash decodes only BMP. Phase B (boot) is a real BrowserWindow because we want a live status line and a phase checklist. Trying to share rendering between them was rejected — the wrapper literally cannot run JavaScript.
  • Splash MUST NEVER block startup. The splash window is created inside a try { ... } catch { ... } block that swallows every error and logs a warning. If BrowserWindow construction throws (driver issue, GPU init failure, etc.), Omniscio continues as if no splash was requested. The logo read is independently fail-safe too: loadSplashLogoDataUri() is wrapped in its own try/catch and returns '' on any read error (missing file, perms, I/O), and buildSplashHtml() omits the <img> entirely when the string is empty — so a missing or locked logo file can never throw out of splash creation.
  • Paints before the blocking boot work. The boot splash is created early, but its ready-to-show→.show() runs on the main thread — which the synchronous DB / migrations / reconcile / recovery passes immediately seize. So the boot sequence awaits awaitSplashFirstPaint(SPLASH_FIRST_PAINT_CEILING_MS) right after createSplashWindow(), giving the splash a guaranteed paint frame before that work; the heavy work then runs behind an already-visible, animating splash (its spinner + "still working" reassurance live in the splash's own renderer process, so they keep moving even while the main thread is busy). The wait is bounded by the ceiling and a no-op when no splash exists (suppressed harness / create failure), so it can never hang or otherwise gate startup. This mirrors app/first-paint-signal.ts (the same pattern for the MAIN window) and is the fix for the "splash shows up ~60 s in" report.
  • 90-second watchdog. If the main window never reaches ready-to-show (crash mid-init, hung migration, infinite loop), a setTimeout force-closes the splash after 90 s and writes [splash] watchdog fired after 90000ms to startup.log. The user then sees whatever the broken state actually is (empty desktop, tray-only) instead of staring at a frozen "Loading..." box forever.
  • Inline HTML via data: URL. The splash HTML is produced by the pure buildSplashHtml(logoDataUri) function in splash-window.ts (logo passed in as an argument; no I/O inside it) and loaded via data:text/html;charset=utf-8,.... No external file, no Vite involvement, no extra packaging step. CSP is default-src 'none'; img-src data:; style-src 'unsafe-inline'; script-src 'unsafe-inline' — the img-src data: clause is what permits the inline base64 logo to paint; drop it and default-src 'none' silently blocks the image (no error, no log, no broken-image icon).
  • Security-locked webPreferences. contextIsolation: true, nodeIntegration: false, sandbox: true. Splash is just a status display — no IPC, no preload bridge, no Node access.
  • Progress updates use JSON.stringify. The main process pushes (phaseIndex, detail) to the splash via webContents.executeJavaScript(\window.__amcSetSplashProgress(${JSON.stringify(phaseIndex)}, ${JSON.stringify(detail)})`). Both args are JSON.stringify-escaped, defending against quotes, backslashes, and newlines in raw startup-trace marks. A phaseIndexof-1means "keep the current phase, just update the detail line" — that's how the liveBacking up database... NN%` text shows without moving the checklist.
  • No persistence, no telemetry. Splash is purely visual — opens, shows status, closes. Nothing about its lifecycle is written to the DB or the diagnostic logs (the underlying startup-trace marks are logged to startup.log; splash just mirrors them visually).

When it does NOT show

  • During npm test / vitest run (NODE_ENV=test)
  • During E2E test runs (AMC_INSTANCE_ID=e2e)
  • During Claude-driven sandbox (AMC_SANDBOX_HEADLESS=1)
  • When AMC_DISABLE_SPLASH=1 is set
  • In development — NODE_ENV defaults to test in Vitest, but a dev run sets it to development so the splash does show. If that's annoying during HMR cycles, set AMC_DISABLE_SPLASH=1 in your shell.
  • If new BrowserWindow(...) throws — caught, logged, swallowed. Startup continues.

windows-installer.md covers the Windows install path a release download runs through — the installer is what a release ships, while the two portable formats above come from the local snapshot build. startup-trace.md covers the startup log the splash mirrors visually — every status line it shows is a startup mark already written there. And app-already-running-or-frozen.md covers the other reason no window appears at launch, when an earlier Omniscio instance is still holding the app.

Last verified 2026-10-18