π¬ A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots π
TypeScript browser-extensionchrome-extensiondocumentationfirefox-extensionguide-generatorlocal-firstmanifest-v3privacy-firstproductivityreactscreenshotstep-by-step-guidetutorialtypescriptworkflowwxt
feat(desktop): add the capture area overlay and recording controls
Luis Ortiz0b0b69cfcbf5
diff --git a/apps/desktop/electron.vite.config.ts b/apps/desktop/electron.vite.config.tsindex 73a3f17..95c75a1 100644--- a/apps/desktop/electron.vite.config.ts+++ b/apps/desktop/electron.vite.config.ts@@ -13,8 +13,9 @@ export default defineConfig({index: resolve(__dirname, 'src/main/index.ts'),'check-capture': resolve(__dirname, 'scripts/check-capture.ts'),'check-storage': resolve(__dirname, 'scripts/check-storage.ts'),+ 'check-overlay': resolve(__dirname, 'scripts/check-overlay.ts'),},- output: { entryFileNames: '[name].js' },+ output: { entryFileNames: '[name].js', chunkFileNames: '[name].js' },},},},@@ -22,7 +23,13 @@ export default defineConfig({plugins: [externalizeDepsPlugin()],build: {outDir: resolve(__dirname, 'out/preload'),- lib: { entry: resolve(__dirname, 'src/preload/index.ts'), formats: ['cjs'], fileName: () => 'index.cjs' },+ rollupOptions: {+ input: {+ index: resolve(__dirname, 'src/preload/index.ts'),+ overlay: resolve(__dirname, 'src/preload/overlay.ts'),+ },+ output: { format: 'cjs', entryFileNames: '[name].cjs' },+ },},},renderer: {@@ -35,6 +42,7 @@ export default defineConfig({input: {index: resolve(__dirname, 'src/renderer/index.html'),'check-storage': resolve(__dirname, 'src/renderer/check-storage.html'),+ overlay: resolve(__dirname, 'src/renderer/overlay.html'),},},},diff --git a/apps/desktop/src/main/overlay/index.ts b/apps/desktop/src/main/overlay/index.tsnew file mode 100644index 0000000..3a6d3a6--- /dev/null+++ b/apps/desktop/src/main/overlay/index.ts@@ -0,0 +1,205 @@+import { join } from 'node:path';+import { BrowserWindow, ipcMain, screen } from 'electron';+import { clampToDisplays, loadRegion, type Region, saveRegion } from '../capture/region';++export type OverlayState = 'hidden' | 'editing' | 'armed' | 'recording' | 'paused';+export type OverlayCommand = 'edit' | 'arm' | 'cancel' | 'start' | 'pause' | 'resume' | 'stop';++const BORDER = 3;+const CONTROLS = { width: 268, height: 48, gap: 12 };++function rendererFile(): string {+ return join(__dirname, '../renderer/overlay.html');+}++function preloadFile(): string {+ return join(__dirname, '../preload/overlay.cjs');+}++function overlayWindow(bounds: Electron.Rectangle, hash: string, interactive: boolean): BrowserWindow {+ const win = new BrowserWindow({+ ...bounds,+ show: false,+ frame: false,+ transparent: true,+ resizable: false,+ movable: false,+ minimizable: false,+ maximizable: false,+ fullscreenable: false,+ skipTaskbar: true,+ hasShadow: false,+ focusable: interactive,+ acceptFirstMouse: true,+ webPreferences: { preload: preloadFile(), contextIsolation: true, nodeIntegration: false },+ });++ win.setAlwaysOnTop(true, 'screen-saver');+ win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });+ win.setContentProtection(true);+ if (!interactive) win.setIgnoreMouseEvents(true);+ win.loadFile(rendererFile(), { hash }).catch((error) => {+ process.stderr.write(`overlay window ${hash} failed to load: ${error}\n`);+ });+ return win;+}++export class CaptureOverlay {+ private editors: BrowserWindow[] = [];+ private boundary: BrowserWindow | null = null;+ private controls: BrowserWindow | null = null;+ private current: OverlayState = 'hidden';+ private rect: Region;++ constructor(private onCommand: (command: OverlayCommand) => void) {+ this.rect = loadRegion();+ ipcMain.handle('mimik:overlay:region', () => this.rect);+ ipcMain.handle('mimik:overlay:state', () => this.current);+ ipcMain.on('mimik:overlay:setRegion', (_event, next: Region) => this.setRegion(next));+ ipcMain.on('mimik:overlay:command', (_event, command: OverlayCommand) => this.command(command));+ }++ get region(): Region {+ return this.rect;+ }++ get state(): OverlayState {+ return this.current;+ }++ private windows(): BrowserWindow[] {+ return [...this.editors, this.boundary, this.controls].filter(+ (w): w is BrowserWindow => w !== null && !w.isDestroyed(),+ );+ }++ private broadcast(): void {+ for (const win of this.windows()) win.webContents.send('mimik:overlay:update', this.current, this.rect);+ }++ private setRegion(next: Region): void {+ this.rect = saveRegion(next);+ if (this.boundary && !this.boundary.isDestroyed()) this.boundary.setBounds(this.frameBounds());+ this.positionControls();+ this.broadcast();+ }++ private frameBounds(): Electron.Rectangle {+ return {+ x: this.rect.x - BORDER,+ y: this.rect.y - BORDER,+ width: this.rect.width + BORDER * 2,+ height: this.rect.height + BORDER * 2,+ };+ }++ private positionControls(): void {+ if (!this.controls || this.controls.isDestroyed()) return;+ const { workArea } = screen.getDisplayMatching(this.rect);+ const below = this.rect.y + this.rect.height + CONTROLS.gap;+ const fits = below + CONTROLS.height <= workArea.y + workArea.height;+ this.controls.setBounds({+ x: Math.round(+ Math.min(+ Math.max(this.rect.x + (this.rect.width - CONTROLS.width) / 2, workArea.x),+ workArea.x + workArea.width - CONTROLS.width,+ ),+ ),+ y: Math.round(fits ? below : Math.max(this.rect.y - CONTROLS.height - CONTROLS.gap, workArea.y)),+ width: CONTROLS.width,+ height: CONTROLS.height,+ });+ }++ private closeEditors(): void {+ for (const win of this.editors) if (!win.isDestroyed()) win.destroy();+ this.editors = [];+ }++ private ensureBoundary(): void {+ if (this.boundary && !this.boundary.isDestroyed()) return;+ this.boundary = overlayWindow(this.frameBounds(), 'boundary', false);+ }++ private ensureControls(): void {+ if (this.controls?.isDestroyed()) this.controls = null;+ if (!this.controls) {+ this.controls = overlayWindow({ x: 0, y: 0, ...CONTROLS }, 'controls', true);+ this.controls.setIgnoreMouseEvents(false);+ }+ this.positionControls();+ }++ edit(): void {+ this.current = 'editing';+ if (this.boundary && !this.boundary.isDestroyed()) this.boundary.hide();+ if (this.controls && !this.controls.isDestroyed()) this.controls.hide();+ this.closeEditors();++ this.editors = screen.getAllDisplays().map((display) => {+ const win = overlayWindow(display.bounds, `editor:${display.bounds.x}:${display.bounds.y}`, true);+ win.setIgnoreMouseEvents(false);+ win.once('ready-to-show', () => win.show());+ return win;+ });+ }++ private show(state: Exclude<OverlayState, 'hidden' | 'editing'>): void {+ this.closeEditors();+ this.current = state;+ this.ensureBoundary();+ this.ensureControls();+ for (const win of this.windows()) win.showInactive();+ this.broadcast();+ }++ arm(): void {+ this.show('armed');+ }++ record(): void {+ this.show('recording');+ }++ pause(): void {+ this.show('paused');+ }++ hide(): void {+ this.current = 'hidden';+ this.closeEditors();+ for (const win of this.windows()) win.hide();+ }++ private command(command: OverlayCommand): void {+ if (command === 'edit') this.edit();+ else if (command === 'arm') this.arm();+ else if (command === 'start' || command === 'resume') this.record();+ else if (command === 'pause') this.pause();+ else this.hide();+ this.onCommand(command);+ }++ async withHidden<T>(fn: () => Promise<T>): Promise<T> {+ const shown = this.windows().filter((win) => win.isVisible());+ for (const win of shown) win.hide();+ try {+ return await fn();+ } finally {+ for (const win of shown) if (!win.isDestroyed()) win.showInactive();+ }+ }++ destroy(): void {+ this.closeEditors();+ for (const win of [this.boundary, this.controls]) if (win && !win.isDestroyed()) win.destroy();+ this.boundary = null;+ this.controls = null;+ this.current = 'hidden';+ for (const channel of ['mimik:overlay:region', 'mimik:overlay:state']) ipcMain.removeHandler(channel);+ ipcMain.removeAllListeners('mimik:overlay:setRegion');+ ipcMain.removeAllListeners('mimik:overlay:command');+ }+}++export { clampToDisplays, loadRegion, type Region, saveRegion };diff --git a/apps/desktop/src/preload/overlay.ts b/apps/desktop/src/preload/overlay.tsnew file mode 100644index 0000000..637c16c--- /dev/null+++ b/apps/desktop/src/preload/overlay.ts@@ -0,0 +1,22 @@+import { contextBridge, ipcRenderer } from 'electron';++interface Region {+ x: number;+ y: number;+ width: number;+ height: number;+}++const api = {+ region: (): Promise<Region> => ipcRenderer.invoke('mimik:overlay:region'),+ state: (): Promise<string> => ipcRenderer.invoke('mimik:overlay:state'),+ setRegion: (region: Region): void => ipcRenderer.send('mimik:overlay:setRegion', region),+ command: (command: string): void => ipcRenderer.send('mimik:overlay:command', command),+ onUpdate: (handler: (state: string, region: Region) => void): void => {+ ipcRenderer.on('mimik:overlay:update', (_event, state: string, region: Region) => handler(state, region));+ },+};++contextBridge.exposeInMainWorld('mimikOverlay', api);++export type MimikOverlayApi = typeof api;diff --git a/apps/desktop/src/renderer/overlay.css b/apps/desktop/src/renderer/overlay.cssnew file mode 100644index 0000000..4d335b1--- /dev/null+++ b/apps/desktop/src/renderer/overlay.css@@ -0,0 +1,203 @@+:root {+ --accent: #4f46e5;+ --deep: #1e1b4b;+ --lavender: #c7d2fe;+ --muted: #6b7280;+ --success: #059669;+}++* {+ box-sizing: border-box;+}++html,+body {+ margin: 0;+ height: 100%;+ overflow: hidden;+ background: transparent;+ font-family: system-ui, sans-serif;+ color: var(--lavender);+ user-select: none;+ cursor: default;+}++body.editor {+ cursor: crosshair;+}++#region {+ position: absolute;+ box-shadow: 0 0 0 100vmax rgba(30, 27, 75, 0.38);+ outline: 2px dashed var(--accent);+ outline-offset: -1px;+ cursor: move;+}++#region.empty {+ display: none;+}++#size {+ position: absolute;+ top: -26px;+ left: 0;+ padding: 2px 8px;+ border-radius: 6px;+ background: var(--deep);+ color: var(--lavender);+ font-size: 11px;+ font-variant-numeric: tabular-nums;+}++.handle {+ position: absolute;+ width: 12px;+ height: 12px;+ border: 2px solid var(--accent);+ border-radius: 3px;+ background: #fff;+}++.handle[data-handle^='n'] {+ top: -6px;+}+.handle[data-handle^='s'] {+ bottom: -6px;+}+.handle[data-handle$='w'] {+ left: -6px;+}+.handle[data-handle$='e'] {+ right: -6px;+}+.handle[data-handle='n'],+.handle[data-handle='s'] {+ left: calc(50% - 6px);+}+.handle[data-handle='w'],+.handle[data-handle='e'] {+ top: calc(50% - 6px);+}+.handle[data-handle='n'],+.handle[data-handle='s'] {+ cursor: ns-resize;+}+.handle[data-handle='w'],+.handle[data-handle='e'] {+ cursor: ew-resize;+}+.handle[data-handle='nw'],+.handle[data-handle='se'] {+ cursor: nwse-resize;+}+.handle[data-handle='ne'],+.handle[data-handle='sw'] {+ cursor: nesw-resize;+}++#hint {+ position: absolute;+ left: 50%;+ bottom: 40px;+ transform: translateX(-50%);+ padding: 10px 16px;+ border-radius: 10px;+ background: var(--deep);+ font-size: 12px;+ white-space: nowrap;+}++#hint b {+ color: #fff;+ font-weight: 600;+}++body.boundary #frame {+ position: absolute;+ inset: 0;+ border: 3px solid var(--accent);+ border-radius: 2px;+}++body.boundary[data-state='recording'] #frame {+ animation: pulse 1.8s ease-in-out infinite;+}++body.boundary[data-state='paused'] #frame {+ border-style: dashed;+ border-color: var(--muted);+ animation: none;+}++body.boundary[data-state='armed'] #frame {+ border-style: dashed;+}++@keyframes pulse {+ 0%,+ 100% {+ border-color: var(--accent);+ }+ 50% {+ border-color: var(--lavender);+ }+}++body.controls {+ display: flex;+ align-items: center;+ gap: 8px;+ padding: 0 10px;+ border-radius: 12px;+ background: var(--deep);+ -webkit-app-region: drag;+}++#status {+ display: flex;+ align-items: center;+ gap: 6px;+ margin-right: auto;+ padding-left: 4px;+ font-size: 12px;+}++#dot {+ width: 8px;+ height: 8px;+ border-radius: 50%;+ background: var(--muted);+}++body.controls[data-state='recording'] #dot {+ background: var(--success);+ animation: blink 1.4s ease-in-out infinite;+}++@keyframes blink {+ 50% {+ opacity: 0.25;+ }+}++button {+ -webkit-app-region: no-drag;+ padding: 6px 12px;+ border: 1px solid transparent;+ border-radius: 8px;+ background: rgba(199, 210, 254, 0.14);+ color: var(--lavender);+ font: inherit;+ font-size: 12px;+ cursor: pointer;+}++button:hover {+ background: rgba(199, 210, 254, 0.26);+}++button.primary {+ background: var(--accent);+ color: #fff;+}diff --git a/apps/desktop/src/renderer/overlay.html b/apps/desktop/src/renderer/overlay.htmlnew file mode 100644index 0000000..e965bc6--- /dev/null+++ b/apps/desktop/src/renderer/overlay.html@@ -0,0 +1,10 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <title>Mimik capture overlay</title>+ </head>+ <body>+ <script type="module" src="./overlay.ts"></script>+ </body>+</html>diff --git a/apps/desktop/src/renderer/overlay.ts b/apps/desktop/src/renderer/overlay.tsnew file mode 100644index 0000000..b0b0a42--- /dev/null+++ b/apps/desktop/src/renderer/overlay.ts@@ -0,0 +1,185 @@+import './overlay.css';++interface Region {+ x: number;+ y: number;+ width: number;+ height: number;+}++declare global {+ interface Window {+ mimikOverlay: {+ region(): Promise<Region>;+ state(): Promise<string>;+ setRegion(region: Region): void;+ command(command: string): void;+ onUpdate(handler: (state: string, region: Region) => void): void;+ };+ }+}++const MIN = { width: 240, height: 160 };+const HANDLES = ['nw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w'] as const;+type Handle = (typeof HANDLES)[number];++const [role, originX, originY] = window.location.hash.slice(1).split(':');+const origin = { x: Number(originX) || 0, y: Number(originY) || 0 };++function el<K extends keyof HTMLElementTagNameMap>(+ tag: K,+ props: Partial<HTMLElementTagNameMap[K]> = {},+ ...children: (Node | string)[]+): HTMLElementTagNameMap[K] {+ const node = Object.assign(document.createElement(tag), props);+ node.append(...children);+ return node;+}++function normalise(a: { x: number; y: number }, b: { x: number; y: number }): Region {+ return {+ x: Math.min(a.x, b.x),+ y: Math.min(a.y, b.y),+ width: Math.max(Math.abs(a.x - b.x), MIN.width),+ height: Math.max(Math.abs(a.y - b.y), MIN.height),+ };+}++function editor(): void {+ document.body.className = 'editor';++ const size = el('div', { id: 'size' });+ const region = el('div', { id: 'region', className: 'empty' }, size);+ for (const handle of HANDLES) {+ const node = el('div', { className: 'handle' });+ node.dataset.handle = handle;+ region.append(node);+ }++ const hint = el(+ 'div',+ { id: 'hint' },+ 'Drag to set the capture area β ',+ el('b', {}, 'Enter'),+ ' to confirm, ',+ el('b', {}, 'Esc'),+ ' to cancel',+ );+ document.body.append(region, hint);++ let rect: Region | null = null;++ function paint(): void {+ if (!rect) {+ region.className = 'empty';+ return;+ }+ const local = { left: rect.x - origin.x, top: rect.y - origin.y };+ const onScreen =+ local.left + rect.width > 0 &&+ local.top + rect.height > 0 &&+ local.left < window.innerWidth &&+ local.top < window.innerHeight;+ region.className = onScreen ? '' : 'empty';+ region.style.left = `${local.left}px`;+ region.style.top = `${local.top}px`;+ region.style.width = `${rect.width}px`;+ region.style.height = `${rect.height}px`;+ size.textContent = `${rect.width} Γ ${rect.height}`;+ }++ function commit(next: Region): void {+ rect = next;+ paint();+ window.mimikOverlay.setRegion(next);+ }++ document.body.addEventListener('pointerdown', (event) => {+ const target = event.target as HTMLElement;+ const handle = target.dataset.handle as Handle | undefined;+ const moving = !handle && region.contains(target) && rect !== null;+ const start = { x: event.clientX + origin.x, y: event.clientY + origin.y };+ const from = rect ? { ...rect } : null;++ document.body.setPointerCapture(event.pointerId);+ event.preventDefault();++ const move = (e: PointerEvent) => {+ const point = { x: e.clientX + origin.x, y: e.clientY + origin.y };+ if (handle && from) {+ const left = handle.includes('w') ? point.x : from.x;+ const top = handle.includes('n') ? point.y : from.y;+ const right = handle.includes('e') ? point.x : from.x + from.width;+ const bottom = handle.includes('s') ? point.y : from.y + from.height;+ commit(normalise({ x: left, y: top }, { x: right, y: bottom }));+ } else if (moving && from) {+ commit({ ...from, x: from.x + (point.x - start.x), y: from.y + (point.y - start.y) });+ } else {+ commit(normalise(start, point));+ }+ };++ const up = () => {+ document.body.removeEventListener('pointermove', move);+ document.body.removeEventListener('pointerup', up);+ };++ document.body.addEventListener('pointermove', move);+ document.body.addEventListener('pointerup', up);+ });++ window.addEventListener('keydown', (event) => {+ if (event.key === 'Enter') window.mimikOverlay.command('arm');+ if (event.key === 'Escape') window.mimikOverlay.command('cancel');+ });++ window.mimikOverlay.region().then((current) => {+ rect = current;+ paint();+ });+ window.mimikOverlay.onUpdate((_state, current) => {+ rect = current;+ paint();+ });+}++function boundary(): void {+ document.body.className = 'boundary';+ document.body.append(el('div', { id: 'frame' }));+ const apply = (state: string) => document.body.setAttribute('data-state', state);+ window.mimikOverlay.state().then(apply);+ window.mimikOverlay.onUpdate(apply);+}++function controls(): void {+ document.body.className = 'controls';+ const dot = el('div', { id: 'dot' });+ const label = el('span', {}, 'Ready');+ const status = el('div', { id: 'status' }, dot, label);+ const primary = el('button', { className: 'primary' });+ const secondary = el('button', {});+ const close = el('button', {}, 'Stop');+ document.body.append(status, secondary, primary, close);++ const render = (state: string) => {+ document.body.setAttribute('data-state', state);+ label.textContent = state === 'recording' ? 'Recording' : state === 'paused' ? 'Paused' : 'Ready';+ primary.textContent = state === 'recording' ? 'Pause' : state === 'paused' ? 'Resume' : 'Start';+ primary.dataset.command = state === 'recording' ? 'pause' : state === 'paused' ? 'resume' : 'start';+ secondary.textContent = 'Capture area';+ secondary.hidden = state === 'recording';+ close.textContent = state === 'armed' ? 'Close' : 'Stop';+ close.dataset.command = state === 'armed' ? 'cancel' : 'stop';+ };++ primary.addEventListener('click', () => window.mimikOverlay.command(primary.dataset.command ?? 'start'));+ secondary.addEventListener('click', () => window.mimikOverlay.command('edit'));+ close.addEventListener('click', () => window.mimikOverlay.command(close.dataset.command ?? 'stop'));++ window.mimikOverlay.state().then(render);+ window.mimikOverlay.onUpdate(render);+}++if (role === 'editor') editor();+else if (role === 'boundary') boundary();+else controls();