π¬ A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots π
The desktop app
Electron. Main (src/main) owns the input hook, the screenshots, the overlay windows and the
network. The renderer (src/renderer) owns IndexedDB and writes guides through @mimik/core
exactly as the extension does. The preload exposes window.mimik with context isolation on.
Main-process rules
- The recording lifecycle is core's capture machine (
IDLE,ARMED,RECORDING,PAUSED), run by one actor in main. The overlay sends it events and renders its windows from its state. Never keep a second copy of "is it recording" anywhere. Redrawing the area mid-recording isPAUSEDwith reasonarea. - Main bundles
@mimik/core(it is excluded fromexternalizeDepsPlugin), so value imports from core work there. Every other dependency stays external. - A packed app has its Electron fuses flipped (
scripts/flip-fuses.cjs): no run-as-node, noNODE_OPTIONSand no--inspect. Pack withMIMIK_INSPECTABLE=1to keep the inspector. out/mainstays flat (chunkFileNamesis pinned), because main resolves../rendererand../preloadfrom__dirname.- Every AI and provider request goes through main (
mimik:ai:fetch). A rendererfetchto a provider fails on CORS and looks like a rejected key. - Screenshot bytes never cross IPC. Main writes a PNG under
userData/screenshotsand sends an id and amimik-screenshot://URL. ask()from main to the renderer rejects when the handler throws. Never resolve with the error.- Never unregister a global shortcut from inside its own handler, or Windows hangs. Rebinds are
deferred with
setImmediate.
Capture
- A click is the press, not the release. The element lookup and the display grab both start in the
mousedownhandler, and the frame is chosen after the grab. - A click frames the window under the pointer (
windowAt). A typing step frames the window its field is in. A key step reads the focused window. - Typing is an
InputSession, finalized like the extension's. Its text is read from the focused field, andtypedTextForfalls back to the keystroke buffer when the field has no value, spans lines or holds more than 200 characters. - A failed screenshot still writes the step, without a picture. A failed lookup is
null, never an error. - A desktop step is an ordinary
Guide/Step/Screenshot. There is no desktop step type, and consumers never branch onelementMeta.source(Guide Me'sisReplayableis the one exception).
Overlays
setContentProtection(true)is applied after a window is shown, never at creation. On Linux, where it does nothing,overlay.withHiddenhides the overlays around each grab.- The card, boundary and area editor share one HTML file. Scope card rules under
body.controls.check:overlayasserts the hint stays static. - Anything hidden on the card uses
hidden, whichbody.controls [hidden]forces todisplay: none. - Icons come from
lucide(vanilla) and the mascot frommascot-shapes. Never copy path data.
macOS
- Accessibility and Screen Recording are checked through
whenPermittedbefore every start. Never check them at launch. - The microphone status comes from
systemPreferences, because Electron grants the page's own permission silently. - On a Mac, shortcuts are written with
ββ₯β§βand no separator, throughshortcutLabel.
Checks
check:storage, check:pipeline, check:overlay and check:capture build the app and drive
real windows. Run them under xvfb-run on Linux. check:pipeline covers capture, cropping, every
exporter and the .mimik round trip. CI runs them on Linux (desktop.yml), and on Windows and
macOS (desktop-windows.yml, desktop-macos.yml) when desktop or shared code changes.
Only desktop-windows-release.yml signs, through electron-builder.signed.yml. Every other build
is unsigned, so the base config never gets signing options.
Releasing
release.yml keeps a desktop release PR open against main beside the extension's. It works out
the next version from the feat and fix commits since the last desktop-v tag, skipping commits
that only touch apps/extension, and writes the changelog into apps/desktop/CHANGELOG.md.
Merging that PR tags desktop-v<version> and opens a draft release. The signed Windows build waits
for approval in the desktop-production environment, then attaches the installer, its blockmap and
latest.yml and publishes the release as Latest, because the updater reads latest.yml from
whichever release holds that flag. The config is in .github/release-please/.